Rename ExecutionResult to ExecutionOutcome; rename CollectedResult to ExecutionRecord

[iCharlesHu]

This PR renames ExecutionResult to ExecutionOutcome and renames CollectedResult to ExecutionRecord according to the new Subprocess 1.0 Proposal.

[iCharlesHu]

Resolves #146

[allevato]

Would there be any objection to adding deprecated typealiases for the old names, for ease of migration to the next release? We've adopted swift-subprocess pretty heavily and these type names surface in our APIs in quite a few places.

[iCharlesHu]

Would there be any objection to adding deprecated typealiases for the old names, for ease of migration to the next release? We've adopted swift-subprocess pretty heavily and these type names surface in our APIs in quite a few places.

You could add the typealias in your own project. If subprocess adds it, the typealias itself would become part of the API which we don't want.

[allevato]

You could add the typealias in your own project.

Usage is spread across at least ten projects, so adding the typealias to each of them would be about the same amount of effort as just searching and replacing the use sites.

Fortunately all of these projects use Bazel in our monorepo instead of SwiftPM, so I can just inject my own source file int swift-subprocess and put the typealiases there instead, I guess. The key point is that it's much nicer to be able to update our copy of the library and then migrate to the new API as a separate change instead of having to land both as a single atomic change.

[iCharlesHu]

The key point is that it's much nicer to be able to update our copy of the library and then migrate to the new API as a separate change instead of having to land both as a single atomic change.

I'm sorry I don't quite understand this part. Could you elaborate on how typealias would help?

Given your situation (wide adoption across different projects), IMO the best way is to pin your dependency to 0.3 until we release 1.0. You can then update your projects to the final 1.0 API when you are ready once so you won't have to worry about more API changes.

Subprocess was launched as a beta to give us a chance to fix mistakes and change our minds without having to commit to a particular API design; therefore, it is expected that every new 0.x tag will contain breaking changes. We are actively working on 1.0 now, and this PR is us removing old design to get the API surface ready for 1.0.

[allevato]

I'll grant that our use case isn't the common one since our code is in a monorepo. swift-subprocess (currently 0.3) is part of that monorepo and all ten or so projects depend on that single copy of swift-subprocess.

When the next release comes out (let's call it 1.0), we'll create a change to import that into our monorepo. Those ten projects will fail to build with that change, because the names of the APIs have changed. So I will have to find all the uses of the API and update them as part of the same atomic change. This isn't unheard of, but it's nice to avoid it when possible.

If we had typealiases for the old names, then I could bring in the new version, submit it without having to update all of the client projects simultaneously, and then migrate them independently to the new names. It's cleaner change management.

It totally makes sense that you don't want the old names to be part of the 1.0 API. The way I would handle that would be to add deprecated typealiases that say "these will be removed in 1.0" and then cut a 0.4 release for those names, and then remove them for 1.0. That gives early adopters a better opportunity to upgrade more gracefully without committing to APIs that you don't want.

[iCharlesHu]

If we had type aliases for the old names, then I could bring in the new version, submit it without having to update all of the client projects simultaneously.

Ahh, I see. Thanks for the explanation! I do plan on tagging at least one more release before 1.0. I can add these type aliases back with a deprecation warning, and remove them in the 1.0 release.

[allevato]

Ahh, I see. Thanks for the explanation! I do plan on tagging at least one more release before 1.0. I can add these type aliases back with a deprecation warning, and remove them in the 1.0 release.

Wonderful, thank you! 🙏🏻