chore: Document versioning strategy #1679
Conversation
There was a problem hiding this comment.
The narrative form is nice, but it would be useful to have a more focused list of "requirements" so it's very clear what we are trying to solve. There are many issues hiding between the paragraphs of the narrative and at least for me it's hard to see the whole picture through the narrative.
Documentation and GitHub releases are related (and important), but the first major problem at hand is the issues listed under developer and maintainer experiences.
design/modular-versioning.md
Outdated
| own pace, in particular as the intention is to eventually transfer ownership of those to the service | ||
| teams. This means CDK packages need to be versioned individually (in other words: in a modular way). | ||
| Individual modules might also eventually be split out of the [awslabs/aws-cdk] mono-repo. | ||
|
|
There was a problem hiding this comment.
One thing I think we need to deconstruct is the notion of pre- and post-1.0. Maybe we can live in a world that post-1.0, there is no such thing as a major version bump of an individual module. It will obvsiouly reduce our agility to a certain degree, but it will be much easier for users and maintainers to reason about what should work with what. Now the problem is pre-1.0 modules, which we should be able to major-version bump until it's ready for prime time...
My point is that this paragraph has some hidden assumptions about requirements and we should distill those very clearly prior to our session.
There was a problem hiding this comment.
I was somewhat intentionally avoiding to make a distinction between pre- and post-1.0 packages. I don't think there's any reason why they should be treated separately unless this dramatically simplifies the problem space (and I don't think it does).
Then, I would rather not limit major version bumping individual packages post-1.0, as this basically means any new major version will have to be coordinated across the entire surface (becomes challenging when packages get migrated to their own repositories... and anyway, that kind of coordination effort...?).
There was a problem hiding this comment.
There's a very big difference in mentality between pre- and post- 1.0 modules, exactly around breaking changes. The bar for a breaking change raises dramatically and we would probably do everything we can to avoid them after 1.0. And I do think it will dramatically simplify our maintenance story, but let's leave that for our discussion.
There was a problem hiding this comment.
I actually think that the only "real" problem is the maintainer issues. As long as we adhere to semantic versioning, customers should be fine since this is basically the same as any other set of dependencies they consume.
Shall we focus on the maintainer's issue.
The order in which the sections are in the document is not innocent 😄
Kinda true, in that maintainers are also users.
I don't think it's that simple given peer dependencies, unless we have a strict "no breaking change after 1.0.0" policy, which sounds extremely limiting. |
I have a feeling that after 1.0.0 we will always major-version-bump everything in case we want to release a breaking change in one of the modules. I think that would have to be the reality of our life or otherwise it would be impossible to reason about compatibility in a decent way |
If true, I feel this should be the result of the design, and not a pre-requisite of it. |
|
Another thing I think is related is which modules do we bump to 1.0 when we GA? I think that's also related. For example, do we plan to bump the IAM library? |
RomainMuller
changed the title
Describes the versioning strategy for the CDK modules.
Designs #272