Aesthetics for new Swift command plugin #172

bachand · 2022-07-21T19:08:30Z

Summary

Cal added a command plugin to format Swift code per our style guide in #168. After watching the WWDC22 talks related to Swift package plugins I had a couple of ideas for improving the aesthetics of this plugin.

Reasoning

Let's avoid command naming collisions in the CLI and simplify the name of our command in Xcode.

Testing

I made edits to the package that didn't conform to our style guide and then ran swift package airbnb-format-swift and saw those edits get fixed.

@calda @airbnb/swift-styleguide-maintainers

Please react with 👍/👎 if you agree or disagree with this proposal.

bachand · 2022-07-21T19:13:55Z

Package.swift

@@ -6,7 +6,7 @@ let package = Package(
  platforms: [.macOS(.v10_13)],
  products: [
    .executable(name: "AirbnbSwiftFormatTool", targets: ["AirbnbSwiftFormatTool"]),
-    .plugin(name: "AirbnbSwiftFormatPlugin", targets: ["AirbnbSwiftFormatPlugin"]),
+    .plugin(name: "FormatSwift", targets: ["FormatSwift"]),


Xcode makes clear that this plugin is from our package, so we can have a simpler name.

bachand · 2022-07-21T19:14:26Z

Package.swift

@@ -30,14 +30,12 @@ let package = Package(
        "AirbnbSwiftFormatTool",
        .product(name: "swiftformat", package: "SwiftFormat"),
        .product(name: "swiftlint", package: "SwiftLint"),
-      ],
-      path: "AirbnbSwiftFormatPlugin"),


We can remove this path by putting the source in a folder under the default Plugins directory.

bachand · 2022-07-21T19:14:33Z

Package.swift

    .executableTarget(
      name: "AirbnbSwiftFormatTool",
      dependencies: [
        .product(name: "ArgumentParser", package: "swift-argument-parser"),
      ],
-      path: "AirbnbSwiftFormatTool",


We can remove this path by putting the source in a folder under the default Sources directory.

bachand · 2022-07-21T19:18:26Z

Package.swift

      capability: .command(
        intent: .custom(
-          verb: "format",
+          verb: "airbnb-format-swift",


When another package consumes this plugin (e.g. https://github.com/airbnb/lottie-ios/blob/97c05f8272fc8e3a2cefb3d41c6bcb90c6d28739/Rakefile#L108) it uses this name. Let's pick a more specific name to avoid collisions. I'm not sure what happens when the names collide.

I think swift package format is noticeably more ergonomic than swift package airbnb-format-swift. I'm not sure how worried we need to be about plugin command conflicts -- perhaps we can hold off on trying to work around that unless it comes up in the future?

I tend to agree with Cal here, I really dislike using - or _ on the CLI since it's much more inconvenient to type.

I'm following the example of the WWDC talk on making these plugins.

Interesting, it looks like we may not need to worry about conflicts (source).

aha cool! So I guess it would be swift package AirbnbSwift:format in that case.

definitely way better than swift package AirbnbSwiftFormatPlugin:format, that change was a good suggestion

bachand · 2022-07-21T19:19:18Z

Package.swift

      capability: .command(
        intent: .custom(
-          verb: "format",
+          verb: "airbnb-format-swift",


This change will break the Lottie repo since the repo depends on the master branch of this repo. I will put up a PR to Lottie before merging this change.

Lottie is pinned to a specific commit in its Package.resolved right?

We should likely start using releases in this repo too though once we make sure this plugin works effectively.

Good call @calda on the Package.resolved 👍 I'm glad we are checking those files in. In any case, I've removed the change to this verb so it's a moot point. I agree with @fdiaz that we should start adding releases to this repo, and a changelog.

Sounds good -- I suppose we'll make a new release when we make config changes from adding a new rule to the style guide?

Sounds good -- I suppose we'll make a new release when we make config changes from adding a new rule to the style guide?

👍

To double check we understand how this works, I tested the Lottie repo after this change. Running swift package format used the previous commit as specified in Package.resolved. When I run swift package update, it updates Package.resolved to reference the most recent commit. I do agree that we should start cutting releases for this repo once we stabilize the tool though.

Thanks for checking @calda

bachand · 2022-07-21T19:19:58Z

Package.swift

@@ -6,7 +6,7 @@ let package = Package(
  platforms: [.macOS(.v10_13)],
  products: [
    .executable(name: "AirbnbSwiftFormatTool", targets: ["AirbnbSwiftFormatTool"]),


I wondered if we should export this tool or simplify export the plugin for now. I also wondered if we should simplify the name of the tool but I left it as-is.

commit 9f2d60d Author: 유재호 <y73447jh@gmail.com> Date: Mon Nov 28 23:53:34 2022 +0900 Add missing space after some comment delimiters (airbnb#208) commit e8412c7 Author: Hanton Yang <hanton.yang@gmail.com> Date: Fri Nov 18 21:28:12 2022 -0800 Fix typo in SE-0156 link (airbnb#207) commit 07bb2e0 Author: Cal Stephens <cal@calstephens.tech> Date: Fri Nov 11 09:21:26 2022 -0800 Update rule for long function declarations to specify effects (`async`, `throws`) should be written on the line after the closing paren (airbnb#205) commit 9ea3428 Author: Cal Stephens <cal@calstephens.tech> Date: Fri Nov 4 17:24:56 2022 -0700 Update `Package.swift` to explicitly not support Linux (airbnb#206) commit 7884f26 Author: Michael Bachand <michael.bachand@airbnb.com> Date: Thu Oct 20 20:26:36 2022 -0700 Update language around when an underscore prefix may be appropriate (airbnb#203) commit 105d7cc Author: Michael Bachand <michael.bachand@airbnb.com> Date: Thu Oct 20 20:25:27 2022 -0700 Update README.md (airbnb#204) commit 831d3c2 Author: 유재호 <y73447jh@gmail.com> Date: Tue Oct 18 11:17:12 2022 +0900 Fix typos in rule 'prefer opaque generic parameter syntax' (airbnb#202) commit fff6fdc Author: Cal Stephens <cal@calstephens.tech> Date: Mon Oct 17 16:42:22 2022 -0700 Bump SwiftFormat version (airbnb#201) commit f600ed0 Author: Cal Stephens <cal@calstephens.tech> Date: Mon Oct 17 11:04:28 2022 -0700 Add rule to prefer opaque generic parameter syntax (airbnb#193) commit f7f2ff9 Author: 유재호 <y73447jh@gmail.com> Date: Tue Oct 18 02:13:17 2022 +0900 Fix naming exception example(underscore prefix) and typos (airbnb#200) commit f5ae3d7 Author: Cal Stephens <cal@calstephens.tech> Date: Fri Oct 14 11:18:27 2022 -0700 Add rule to prefer simplified generic extension syntax (airbnb#194) commit 00216e3 Author: Cal Stephens <cal@calstephens.tech> Date: Thu Oct 13 16:49:19 2022 -0700 Add rule to prefer shorthand `if let` optional unwrapping syntax (airbnb#192) commit 860f0d5 Author: Cal Stephens <cal@calstephens.tech> Date: Tue Oct 11 14:39:32 2022 -0700 Add rule to prefer trailing closure syntax for closure arguments with no parameter name (airbnb#199) commit eff3f23 Author: 유재호 <y73447jh@gmail.com> Date: Tue Aug 23 01:15:12 2022 +0900 Fix typos in README.md (airbnb#191) commit f602b12 Author: Cal Stephens <cal@calstephens.tech> Date: Tue Aug 16 16:52:56 2022 -0500 Update to SwiftFormat build based on 0.49.16 (airbnb#190) commit d1b1bda Author: 유재호 <y73447jh@gmail.com> Date: Mon Aug 15 22:55:29 2022 +0900 Fix typo and broken type annotations (airbnb#189) commit cec2928 Author: Cal Stephens <cal@calstephens.tech> Date: Fri Jul 29 18:30:21 2022 -0700 Improve handling of `--swift-format` and `--exclude` arguments (airbnb#182) commit 1bf9613 Author: Cal Stephens <cal@calstephens.tech> Date: Thu Jul 28 09:21:53 2022 -0700 Infer Swift version from Package.swift swift-tools-version (airbnb#180) commit b53ed2a Author: Cal Stephens <cal@calstephens.tech> Date: Thu Jul 28 08:54:24 2022 -0700 Add `XcodeCommandPlugin` to fully support Xcode 14 (airbnb#181) commit 30e8f68 Author: Michael Bachand <michael.bachand@airbnb.com> Date: Wed Jul 27 09:35:21 2022 -0700 Remove executable as product (airbnb#179) commit 1d8bb91 Author: Cal Stephens <cal@calstephens.tech> Date: Mon Jul 25 15:23:08 2022 -0700 Add Swift Package Index badges (airbnb#178) commit 7ecef5d Author: Cal Stephens <cal@calstephens.tech> Date: Mon Jul 25 13:39:16 2022 -0700 Add info about Swift Package Manager command plugin to README.md (airbnb#176) commit 5542090 Author: Jay Hickey <hi@jayhickey.com> Date: Sat Jul 23 13:56:43 2022 -0700 Add `--paths` argument to only lint specific paths (airbnb#177) commit 503c5bc Author: Cal Stephens <cal@calstephens.tech> Date: Fri Jul 22 14:17:09 2022 -0700 Support target selection dialog in Xcode 14 (airbnb#175) commit 7079bc3 Author: Cal Stephens <cal@calstephens.tech> Date: Fri Jul 22 14:06:02 2022 -0700 Improve error handling, add support for `--exclude` flag (airbnb#173) commit 852a2e3 Author: Cal Stephens <cal@calstephens.tech> Date: Fri Jul 22 11:46:12 2022 -0700 Bump to latest commit of SwiftLint (airbnb#174) commit 20290d8 Author: Michael Bachand <michael.bachand@airbnb.com> Date: Thu Jul 21 13:46:20 2022 -0700 Aesthetics for new Swift command plugin (airbnb#172) * restrucutre * reorganize again * one more change * update ci * Update Package.swift * Update main.yml commit 640b1ee Author: Cal Stephens <cal@calstephens.tech> Date: Thu Jul 21 08:20:35 2022 -0700 Update Swift version to 5.6 (airbnb#169) commit fb658f4 Author: Cal Stephens <cal@calstephens.tech> Date: Wed Jul 20 14:23:23 2022 -0700 Update xcode_settings.sh script to enable Xcode spell check (airbnb#171) commit b844956 Author: Cal Stephens <cal@calstephens.tech> Date: Tue Jul 19 19:14:56 2022 -0700 Add Swift Package Manager command plugin (airbnb#168) commit c60d1f6 Author: Cal Stephens <cal@calstephens.tech> Date: Tue Jul 19 11:59:19 2022 -0700 Include a single space in a set of empty braces (`{ }`) (airbnb#167) commit d53c95b Author: Cal Stephens <cal@calstephens.tech> Date: Tue Jul 19 11:58:54 2022 -0700 Use commas instead of `&&` operators in conditional statements (airbnb#166) commit 15309c9 Author: Cal Stephens <cal@calstephens.tech> Date: Tue Jul 5 10:02:40 2022 -0700 Add rule to remove blank lines from the top and bottom of scopes (excluding type bodies) (airbnb#164) commit a310253 Author: Cal Stephens <cal@calstephens.tech> Date: Sat Jul 2 19:55:48 2022 -0700 Add `actor` to `--organizetypes` option (airbnb#165) commit ea85cf2 Author: Michael Bachand <michael.bachand@airbnb.com> Date: Wed Jun 8 15:00:29 2022 -0700 Fix href for #whitespace-around-comment-delimiters (airbnb#163) commit 5034513 Author: Cal Stephens <cal@calstephens.tech> Date: Tue Jun 7 12:11:13 2022 -0700 Add rule that there should be no spaces inside brackets of collection literals (airbnb#162) commit 9785e35 Author: Cal Stephens <cal@calstephens.tech> Date: Tue Jun 7 12:11:03 2022 -0700 Add rule that there should be no spaces before or inside the parentheses of function calls / declarations (airbnb#161) commit 904b72d Author: Cal Stephens <cal@calstephens.tech> Date: Tue Jun 7 12:10:52 2022 -0700 Add rule to include spaces before and after comment delimiters (airbnb#160)

restrucutre

aca6b27

bachand force-pushed the mb--gardening-format-plugin branch from f618b2e to aca6b27 Compare July 21, 2022 19:09

reorganize again

b049046

bachand commented Jul 21, 2022

View reviewed changes

bachand changed the title ~~reorganize~~ Aesthetics for new Swift command plugin Jul 21, 2022

one more change

ad559b8

bachand commented Jul 21, 2022

View reviewed changes

bachand marked this pull request as ready for review July 21, 2022 19:20

bachand added 3 commits July 21, 2022 12:21

update ci

37218d4

Update Package.swift

fa1df26

Update main.yml

3c5b60e

calda approved these changes Jul 21, 2022

View reviewed changes

bachand merged commit 20290d8 into master Jul 21, 2022

bachand deleted the mb--gardening-format-plugin branch July 21, 2022 20:46

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Aesthetics for new Swift command plugin #172

Aesthetics for new Swift command plugin #172

bachand commented Jul 21, 2022 •

edited

Loading

bachand Jul 21, 2022

bachand Jul 21, 2022

bachand Jul 21, 2022

bachand Jul 21, 2022

calda Jul 21, 2022 •

edited

Loading

fdiaz Jul 21, 2022

bachand Jul 21, 2022 •

edited

Loading

bachand Jul 21, 2022

calda Jul 21, 2022

calda Jul 21, 2022 •

edited

Loading

bachand Jul 21, 2022

calda Jul 21, 2022

fdiaz Jul 21, 2022

bachand Jul 21, 2022

calda Jul 21, 2022

bachand Jul 21, 2022

calda Jul 22, 2022

bachand Jul 23, 2022

bachand Jul 21, 2022

Aesthetics for new Swift command plugin #172

Aesthetics for new Swift command plugin #172

Conversation

bachand commented Jul 21, 2022 • edited Loading

Summary

Reasoning

Testing

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

calda Jul 21, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bachand Jul 21, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

calda Jul 21, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bachand commented Jul 21, 2022 •

edited

Loading

calda Jul 21, 2022 •

edited

Loading

bachand Jul 21, 2022 •

edited

Loading

calda Jul 21, 2022 •

edited

Loading