Post Mortem

[nmccann]

First of all I'd like to say thank you very much for open sourcing this project! I've been using the Composable Architecture for a while, and while the case studies provided with it are quite helpful, nothing beats seeing it how it works "in the wild" so to speak. I'm sure I'll be looking at this project for quite a while for tips on how to accomplish particular things in my own projects.

I was wondering if there are any plans to do something like a post mortem of the pro and cons of the decisions made on this project? The blog post announcing the open-sourcing did a good job of introducing some of the things that make this project special, but didn't talk too much about the challenges faced along the way.

In particular, I was quite excited to see how you're using SPM to manage all of your local and remote packages - I'm looking into replicating that on my project, but am concerned about some of the management overhead it adds. Specifically, when adding a new feature it now requires adding a target/test target to the Package.swift, adding the tests to the target's scheme (so CMD+U runs those tests), and optionally adding those tests to the main app target's scheme (so CMD+U on the app target runs tests for all features).

Perhaps there are some lessons learned that you could share in relation to the SPM integration, and any other issues you ran into along the way.

Thank you for your time, and for sharing this resource!

[mbrandonw]

Hey @nmccann, this is a great idea, thanks for sharing! We plan on doing some tour-like episodes and we'll be sure to include little nuggets like this, and we plan on covering some of these things in dedicated episodes too. Also, you can always post questions in isowords discussions, that's why we enabled it on this repo 🙂.

I can give a few more details about the SPM stuff. While the overhead you outlined is definitely a real thing, and we don't know of a way around it, it is still much, much, much better than the alternative of using Xcode targets. I used to grit my teeth when I wanted to create a shareable module from within Xcode because of all the ceremony and the multiple steps that you can get wrong. I would say the only reason we even attempted hyper-modularizing is because of how easy it is to do with SPM, and then doing so unlocked all types of great things for us.

Further, having a simple text description of the dependency graph is much better than it being trapped in the Xcode project. Makes it easier to clean up unused dependencies and track down transitive dependencies.

We even use SPM modules to easily separate out resources. For example, we have AppClipAudioLibrary that holds the bare essentials of audio needed for the app clip (because of the 10 MB limit) and we have AppAudioLibrary that has all of the rest of the sounds. This was so easy to do with SPM.

I do think SPM could help us out more, and we should probably file feedbacks and bugs. For one thing, test targets should probably be automatically added to the test phase of the corresponding main target. That would clear up some manual work.

[nmccann]

Thank you for going into some more detail on those challenges. I'm hopeful that the benefit will outweigh the overhead, it's just difficult to know how things will play out. I do agree that having everything in Xcode has it's own downsides.

One nice-to-have I've encountered already is that I have a simple CLI to encapsulate common actions for my project, and having a single Package.swift at the root of my project makes it easy to execute this via swift run ... - it's similar to the Makefile in the isowords project (in hindsight I probably could have used a Makefile, but I like the idea of it being maintained in Swift, and using swift-argument-parser and ShellOut made it pretty easy). Before I had a single Package.swift, I needed to put a comment at the top of the CLI's Package.swift saying "Look at Xcode to change the app's dependencies".

[lukeredpath]

The app I'm working on is currently going down the route of heavily modularisation using SPM. It's early days but I think we are already seeing the benefits. We have two packages, a Core package containing all of our dependency and utility libraries and a Features package containing core app features.

The main overhead we have found so far is the steps required to add new modules that you have already mentioned. We should probably automate this - I'd be interested in any tooling you can share for managing the package file - but we have fully documented the process.

As well as updating schemes you also need to remember to update your test plans if you use them. We have a unit tests only test plan and a dedicated CI test plan which we use to exclude certain tests that are flakey on CI.

Also don't forget about code coverage. Xcode can include coverage from your test targets in its test results bundle. We use xccov2lcov to convert the JSON output to lcov format which allows you to precisely specify which modules to include (Xcode doesn't let you filter coverage reports at all). We then upload this to Coveralls from CI.

One gotcha I should mention is build configurations as this caught us out - SPM only supports Debug and Release and if you ha e other configurations, Xcode will attempt to map these by some magic undocumented process. We have a Beta configuration which was intended to be a Debug build but Xcode was trying to build our packages for Release which caused issues. We had to rename it to "Beta Development" to get it to map correctly. Xcode gives you no way to control this explicitly! 🤦🏻‍♂️

[stephencelis]

I'd be interested in any tooling you can share for managing the package file - but we have fully documented the process.

The Package Editing Commands proposal was very recently accepted and will hopefully aid in this.

[lukeredpath]

Here's to Xcode 15 🤞🏻

[nmccann]

One downside that I've found to the modular approach, is that you can no longer rely on Xcode to properly export localizable strings. It's "Export for Localizations" functionality only looks within the app targets, not within SPM packages, and there doesn't seem to be a way to configure it to do so (even with using xcodebuild -exportLocalizations).

I've worked around this by using extractLocStrings which from what I understand is what gets used under the hood by that other command, but it allows you to pass an arbitrary list of files to localize. So a command like this:

find App Sources -name "*.swift" -print0 | xargs -0 xcrun extractLocStrings -SwiftUI -o en.lproj

Would look through the App and Sources directories of isowords and save any localizable strings found in Swift files to a Localizable.strings file in the en.lproj directory (requires this directory to already exist). Once you have the strings file in your project, you can then use Xcode's "Export for Localizations" to get an xliff file if that is needed, though if you add any new strings to your project, you'd have to either manually add them to the strings file, or run extractLocStrings again.

This workaround is sufficient for a project that doesn't have a complex localization workflow, but might be a deal breaker for more complex apps. Though I'd argue that even the workflow with a "normal" Xcode app is more painful than it ought to be.

[stephencelis]

One downside that I've found to the modular approach, is that you can no longer rely on Xcode to properly export localizable strings. It's "Export for Localizations" functionality only looks within the app targets, not within SPM packages, and there doesn't seem to be a way to configure it to do so (even with using xcodebuild -exportLocalizations).

Is this true for framework targets, too, or just SPM? If so that's a bummer and seems to be a big oversight :( I could see taking on the additional maintenance burden of modularizing in that fashion instead. It's what we did in the past, after all.

[nmccann]

@stephencelis I can confirm that framework targets work correctly with Xcode's "Export Localizations". Meaning that, the resultant .xcloc folder will have an .xliff file with any strings that can be extracted from the framework target (ex. if you have a SwiftUI view that uses Text("Some string"), the .xliff file will contain "Some string").

From what I can tell, the intention with SPM is that each package would already have it's strings localized, so there would be no reason to include them in the project's .xliff. This makes sense when you're consuming a dependency maintained by a 3rd party (they would localize anything that needs to be localized, and you'd show it as is), but isn't helpful when you're maintaining the package yourself.

If you want to keep using packages, the options appear to be:

• Use a command like I mentioned in my earlier post as a hacky workaround to keep your project's localizable strings up to date.
• Follow instructions here to include localizations within your SPM package. Possibly with one Localizable.strings file for all targets in the package, not sure about that.

Even if you go with the second approach, you'd have to manually use extractLocStrings to find keep your package's Localizable.strings up to date. So the only really advantage you get is that everything is contained within the package, rather than your views etc. defined in your package, and their localizations defined in your project.

For what it's worth, I'm currently going with the first approach - keeping everything in the project, and using a hacky way to keep that up to date. Works for my use case, but I'm sure there is a gotcha I'm not considering.