Add Package.swift

[crazytonyli]

Not just adding a Package.swift file, this PR also proposes a structure that potentially can be shared among all our shared libraries.

Development

During development, we should treat the library as a Swift package. There are two ways to develop the Swift package in Xcode:

• Open Package.swift directly in Xcode. From here, we can build and test the package. One thing missing from this approach is we can't see UI produced by the library, like the icons in this repo. So, it's quite common to have a demo or example project to showcase the library:
• Create a demo/example project and import the library as a local package(Xcode -> File -> Add Packages... -> Add Local). The demo project has an app target where we can see the component in the library. The demo/example project may also be a good place to host UI tests.

Both approaches work, they don't conflict with each other. I don't see there is any need of recommending one over the other. But we may want to add steps in CI to ensure the demo/example app continues to build.

Distribution

The library can be imported as a Swift package and a CocoaPods pod. But since we no longer use the library's podspec file during development, we could easily overlook CocoaPods integration. One way to prevent this issue is adding "test spec" to the podspec so that the pod lib lint step in CI not only validates if the podspec can be imported as a pod but also tests its functionality—kinda like how you can build and test targets in a Swift Package.

I want to highlight one thing. Since CocoaPods and SPM package the library differently, especially on the resource bundles, we'll need to make sure there is test coverage around loading resource bundles.

Summary

To summarize all above, here are list of things that we should do in our libraries.

• Add test_spec to the podspec file. The test spec should have the same test cases that are declared in Package.swift.
• If the library has resources (images, assets, localization, etc.), make sure there is test coverage for them.
• Validate both Swift Package and podspec file in CI. A validate_swift_package script is added in this PR, which should serve the same purpose as validate_podspec and should be moved to the buildkite plugin repo.
• No xcworkspace or xcodeproj in the library's root directory. So that the xcodebuild command line picks up the Package.swift file, not the workspace or project file(*).
• When needed, create a directory and place the demo/example Xcode project there. Import the Swift Package into the demo/example project by navigating Xcode -> File -> Add Packages... -> Add Local -> Choose the repo's root directory.
• ~Ignore two files in the git repo: Package.resolved and .swiftpm directory. I don't think we should not pin the library's dependencies (if there is any) to certain versions during development.~ Update: Check in Package.resolved to pin the dependencies used during development—similar to how we check in Podfile.lock.

(*) xcodebuild has this very strange behavior when dealing with Package.swift. To make the command run tests in the Package.swift, we need to run the command in the directory of Package.swift, without passing -workspace nor -project option. Suppose there is an xcworkspace or xcodeproject in the Package.swift directory, they will use them instead of the Package.swift file—there is no equivalent of -workspace MyApp.workspace for Swift Package.

---

• [x] I have considered if this change warrants release notes and have added them to the appropriate section in the CHANGELOG.md if necessary.

[crazytonyli]

@mokagio I actually changed my mind regarding the Package.resolved file. We probably should check in this file, like how we check in the Podfile.lock file.

[crazytonyli]

This repo doesn't follow the recommended (?) SPM folder structure

My plan for now is keeping the existing folder structure, for two reasons

1. Package.swift DSL should be flexible enough to support any random folder structure.
2. Not renaming folders and files makes git blame easier.

[mokagio]

This repo doesn't follow the recommended (?) SPM folder structure

My plan for now is keeping the existing folder structure, for two reasons

1. Package.swift DSL should be flexible enough to support any random folder structure.
2. Not renaming folders and files makes git blame easier.

@crazytonyli fair enough. I don't feel strongly about the file names. Well, actually... A part of me really wishes we had Sources/ Tests/ Demo/ across repos because it would look neat and homogeneous, but I'm not aware of any practical benefit that would make development easier if we did that 😄

Doing a blanket rename is a straightforward operation that we can do anytime in the future if a good reason for it comes up, so no worries 👍

---

I was curious about the git blame behavior and pushed a branch with renames and checked the blame on GitHub. It seems to follow renames alright. Example, I renamed the whole Gridicons/Gridicons/ folder to Sources/ and checked one file:

[AliSoftware]

I was curious about the git blame behavior and pushed a branch with renames and checked the blame on GitHub. It seems to follow renames alright. Example, I renamed the whole Gridicons/Gridicons/ folder to Sources/ and checked one file:

Yes, git blame follow full-file renames (i.e. if you just renamed a file in a commit without also changing some of its content at the same time) pretty well automatically. If you made both a rename and a content change, you can still get git blame follow those by using -C / -M options, that just makes the blame command a bit slower.

The origin of lines is automatically followed across whole-file renames (currently there is no option to turn the rename-following off). To follow lines moved from one file to another, or to follow lines that were copied and pasted from another file, etc., see the -C and -M options. — Source: https://www.git-scm.com/docs/git-blame

So if we wanted to reorganize the files to follow SPM filesystem structure conventions, that wouldn't cause any trouble with git blame at least.

[crazytonyli]

@AliSoftware I can't remember the exact issue, but I had troubles with git blame option, maybe I wasn't using them correctly.

For easier PR review, I can create a follow up PR to follow SPM's convention, what do you all think?

[AliSoftware]

Yeah if you want to try that doing so in a separate PR would be a good way to go imho.

I wonder if it makes a difference to git blame if you used git mv (vs mv + git add) to rename/move the files… 🤔 I don't think so but to worth checking?

[mokagio]

For easier PR review, I can create a follow up PR to follow SPM's convention, what do you all think?

Sounds good to me. I am not too worried about adhering to the Sources/ Tests/ structure. It can happen later, if at all.