1.0 Preview

[stephencelis]

Hey everyone,

We are very excited to officially share a preview of what 1.0 will bring to the library. We want to be clear upfront that there are no episode or library spoilers in this post, and we are not yet announcing a beta for the navigation tools even though we have started that series. That beta will come in a few weeks.

The 1.0 of the library is something we outlined 4 months ago, and we are now officially starting the process. In a nutshell, 1.0 does not add any actual new features to the library but instead finally cleans up cruft that has accumulated over the years, such as removing most of the 1,100 lines of deprecations and finally renaming ReducerProtocol to Reducer.

We want to reiterate: 1.0 of the Composable Architecture is not a grand rethinking of the library or a feature-rich release. It is merely a breaking change to get rid of tools that have been long deprecated (some of them have been deprecated for years) and to give other tools their proper names.

So then, what is the 1.0 “preview”? It is a branch that you can target today if you want to get a head start on preparing for 1.0.

prerelease/1.0

The branch we are releasing is prerelease/1.0. It is a mostly backwards-compatible version of the library that we will keep up-to-date with the latest release from main, but it makes a few important breaking changes:

For reducers:

• Reducer now refers to the reducer protocol, not the struct that is generic over state, action and environment.
• A soft-deprecated type alias ReducerProtocol = Reducer has been added.

So, this change is only a breaking change if you are still using the old Reducer type alias that refers to the AnyReducer struct. If you are on the ReducerProtocol, which has been out for 4 months, then you should be good to go. Or, if you have updated your uses of Reducer to AnyReducer, you should only have deprecation warnings.

For effects:

• The Effect type now has one single generic for Output. The Failure generic has been removed.
• A soft-deprecated type alias EffectTask = Effect has been added.

So, this change is only a breaking change if you still refer to the old Effect type alias. If you are using the EffectTask type, which has been suggested for over 4 months, then you should be good to go.

Even though there are some breaking changes, the fixes are usually quite simple. For example:

• If you are still using the old Reducer struct type alias, you can simply rename it to AnyReducer. E.g:

  -Reducer<MyState, MyAction, MyEnvironment>
  +AnyReducer<MyState, MyAction, MyEnvironment>

• If you are using the Effect type with two generics, you can simply rename them to EffectPublisher. Or, better yet, if the Effect type with two generics has a failure type of Never, you can simply rename it to EffectTask and remove the failure generic entirely. E.g.:

   // For effects that can fail:
  -Effect<MyAction, Error>
  +EffectPublisher<MyAction, Error>
  
   // For effects that cannot fail:
  -Effect<MyAction, Never>
  +EffectTask<MyAction>

How should I target prerelease/1.0?

If your project has already prepared for the two breaking changes mentioned above, you may benefit from targeting the prerelease/1.0 branch. That is:

• You have no references to the old Reducer type, and have either migrated all of your project’s reducers to take advantage of the ReducerProtocol, or you have at the very least renamed all instances of Reducer to AnyReducer.
• You have no references to the old Effect type, and have renamed all instances to EffectTask or EffectPublisher (ideally preferring EffectTask when the failure type is Never).

By targeting prerelease/1.0 you will get a hard-deprecated view of all APIs that have been soft-deprecated over the past months. If you have no deprecations, you are in good shape for 1.0. If you have deprecations, this means you can begin to incrementally chip away at them to prepare for 1.0’s release in the coming months.

Note: Unless you are fully committed to living on the edge and working with beta software, we do not recommend fully adopting the prerelease/1.0 branch, nor do we recommend adopting the Reducer and Effect renames that come along with it. If you are committed, though, we value your feedback! Please discuss any issues that crop up in these forums, and we’ll do our best to make the experience and smooth as possible for a beta.

For those that do adopt the prerelease/1.0 branch, we also do not recommend literally tracking prerelease/1.0, as that will continually track every single change to the branch. Instead, we recommend pinning to an exact Git SHA, and updating this SHA when you are prepared for the changes that come along with it.

Future branches and releases

In the near future, as we get closer to the official 1.0 release, we may introduce additional branches that you can target to help you update your codebase to be 1.0 compliant. For example, we will have a branch to track all forthcoming “0.x” releases, which will include all of the new navigation tools, but will also be 100% backwards-compatible with the library today.

What about navigation?

The navigation tools that we have just begun covering are coming soon, but not right now. We will be opening a public beta in the coming weeks just as we did with async/await effects and the Reducer protocol. This will give you a chance to play around with the tools before their final release and provide feedback.

Our plan is for the navigation beta to work both with main, which means it will be 100% backwards compatible with your project today, and also work with prerelease/1.0. There will be more information on that soon!

Try it today and give feedback!

Please give the prerelease/1.0 branch a spin and let us know what your feedback is. Consider the branch a “beta”: it may have mistakes, deprecations may behave in strange ways, etc. If you encounter any issues, let us know!

We are excited to finally bring the Composable Architecture to 1.0, though, and we have more big announcements coming soon.

[JimRoepcke]

Super excited about this!

Following up regarding a question I asked previously. I don't see any changes in Package.swift on the prerelease/1.0 branch, yet. I'm curious if the platform or Swift compiler version requirements will be changing for 1.0. For example, requiring structured concurrency support.

We're on Swift 5.7, but minimum deployment target is still just 14.4, so no structured concurrency support in Foundation/UIKit/etc. We're planning on bumping that to 15.(5/6?) soonish, but it would help our planning in this regard to know what the plans are here. Thanks!

[stephencelis]

Since the bones of structured concurrency are available in iOS 13+, you should still be able to use the minimum required for Effect. The current thought is that you may just need to restructure things a bit by pushing existing Combine logic into an effect and iterating over the publisher.values there. This could probably be done with a helper, and we could chat about providing such a helper from the library if it makes sense to!

I think we'll try to support Swift 5.6 still, but if there's a compelling reason to switch to 5.7, we'll consider it!

[Jeehut]

I just migrated my app RemafoX to the 1.0 branch (including Navigation) and shared the whole experience on my blog here:
https://www.fline.dev/migrating-to-tca-1-0/

Mostly, the migration went smoothly, although I still have a couple of warnings to fix – thanks to great migration documentation!

But maybe it's worth noting that I wasn't really happy with how the files were structured with the new Reducer protocol style in your videos and in sample code within the library. I used a slightly different (in my opinion "improved") approach in my app. Would love to hear your thoughts on the ideas that I shared in the article with code examples and my rationale.

Quick summary of my style:

1. I don't make the Feature conform to Reducer, instead I use it as a namespace.
2. I put Reducer and even View inside this namespace, so calling them is done via Feature.Reducer() or Feature.View().
3. I extract the Reducer and View protocol implementations (the body property) to their own files, so I end up with 3 similarly long files rather than a single very long file or many files of different lengths (like I did before).

More details in the article.

What do you think? Any comments, suggestions or thoughts?

[mbrandonw]

Hi @Jeehut, thanks for giving prerelease/1.0 a spin and letting us know it was mostly smooth!

As for file structure, that is something the library has no opinions on and so we think each team should do what makes most sense for them. We personally like to keep domain, logic and behavior of our features in the same file, but we know that isn't for everyone and so we do not want to force or encourage our style on others.

[ghost]

Hello folks, quick question.

How "production-ready" is prerelease/1.0 compared to 0.53.0?

By that I mean that 0.51.0, 0.52.0, 0.53.0, etc are tagged official releases that people may be already using to ship apps with while prerelease/1.0 is, for now, just another branch you're maintaining. Do you consider prerelease/1.0 as stable as 0.53.0? Is it any riskier to use prerelease/1.0 in production now (mid-May 2023) than it is to use 0.53.0?

As always, many thanks for the awesome work you guys are doing.

[stephencelis]

While we do our best to keep navigation-beta and prerelease/1.0 in building and working order, they are definitely branches that move fast and occasionally break things, and should be treated as the "beta" and "prerelease" each is 😄

I would adopt per your comfort level. If you want a stable, less fussy experience, stick with the official release track. If you don't mind pinning to releases in a branch and are prepared to troubleshoot issues and changes as they arise, you may be OK in adopting these branches.

[ghost]

Hi @stephencelis . Thanks for the quick reply. I asked because there's some divergence of opinion in our team, regarding going ahead with pre-1.0.

[Jeehut]

@wtruppel I use prerelease/1.0 for my production apps and shipped version 1.5 of RemafoX which is based on that branch. I also wrote about my migration experience here if you're interested. I didn't run into any serious problems.

Just some more warnings get added when I update my dependencies. But you could simply pin to one commit and not update until 1.0 is officially released. As things are tested extensively, things are actually pretty stable in that branch from my experience.

[acosmicflamingo]

Although I don't have a production app, I have certainly not encountered issues whenever I update what HEAD is pointing to. The one time I did was when I immediately updated HEAD after they merged a change, and a merge conflict artifact snuck in. They fixed it a few minutes or so later, so I think you're in good hands (just wait an hour or so after they merge something) ;)

[ghost]

Thank you both, @Jeehut and @acosmicflamingo, for your input. Personally, I'm fine with it and don't need convincing but my colleague is of the opposite opinion. Maybe seeing Jeehut's app (impressive, by the way) might help to change his mind.

[Jeehut]

@stephencelis @mbrandonw The latest changes to the prerelease/1.0 branch broke my code (I'm on b177364): I had to revert uses of Reducer and Effect<Action> to ReducerProtocol and EffectTask<Action> respectively to get my builds passing again. Is this a temporary glitch (so I better depend on an older commit of that branch) or should I change my code back to ReducerProtocol and EffectTask? I thought that Reducer and Effect<Task> are the future names in 1.0, I'm a bit confused.

[iampatbrown]

You can find my full "About" feature implementation in the links I've sent you on Twitter recently.

@Jeehut Any chance on including that here as well? I'm not on Twitter but was going to take a look at this later today. Good investigation so far tracking down the commits :)

[Jeehut]

@iampatbrown I sent the Gists to them on Twitter via DMs, privately, including access to a framework that is also private right now. So, there's nothing related to this issue on Twitter you're missing out on. Soon after WWDC I'll be open-sourcing the framework anyways, maybe I can give more details in public by then.

[mbrandonw]

The code in the gists don't compile due to missing symbols (PaywallFeature, Constants, Loc, etc...), so there isn't much we can do to diagnose the problem.

[stephencelis]

@Jeehut I was able to repro with your library with some of the commits, above, but it also looks like the latest prerelease/1.0 is building just fine, so I'm not sure it's worth digging into further right now. It could have been a temporary merge/build issue that got squared away.

prerelease/1.0 has been a bit more fraught to keep up-to-date with both main and navigation-beta in-flight, but now that navigation-beta has been merged into main hopefully things will be more stable.

Please communicate any future issues you have as you encounter them, though!

[Jeehut]

Thank you, I'll keep you updated for sure!

[xavierLowmiller]

Not sure if this is the right place to ask this, but given the impending 1.0 merge (#2318), the observability changes (as teased here) probably won't be part of 1.0, right?

[Jeehut]

@xavierLowmiller I thought exactly the same when I saw the recent tweet that there will be a new "1.0" overview video series. Because the changes with macros will be huge and it kinda doesn't make sense to create videos that are watched long term, when soon after there will be big API changes. So I'm curious, too. 🤞

[akbashev]

@xavierLowmiller @Jeehut
Nope, observability is iOS 17+ atm.
Asked in Slack what are the plans, @stephencelis answered they're playing with it and thinking to introduce it somehow after iOS 17 is out.

[mbrandonw]

1.0 will not have any observability or macros because, well, all of that is still beta for the next month and a half. 🙂

There is a slight chance we can layer on new tools such as observability in a backwards compatible 1.x release, or perhaps that will be the 2.0. And things like macros can be added at any point, but significant research still needs to be done to understand how they change TCA so that we don't accidentally back ourselves into a corner with rushed decisions.

The upcoming tour will still be relevant for years to come because the majority of people will not be able to target iOS 17 anytime soon. But, we will give little teasers of how the future of TCA will look even though those tools will not be available in 1.0.