API versioning in git

[thediamondor]

Hey, I'm working on a different NPM library and i was wondering how you guys handle breaking changes that need a major version to upload while working on minors for the current version that is out. ill give an example:
lets say you are on version 5 (coincidence I swear) and i am working on a feature that breaks API that can't be a minor because it breaks user's code and needs to be in version 6.

[HarelM]

What we did so far was the following, I'm not sure it's the best solution, but it had worked for us:
Do all the non-breaking changes until we decide to start breaking things.
Work on a branch with the breaking changes and continue pushing non-breaking changes to main.
When we decide to merge the breaking changes, we start a pre-release version publishing until we decide we have concluded all the breaking changes we wanted to do, and the version is stable.
It took us about 3 months in each major version to "stabilize" it.
We try to max the number of major versions releases to twice a year to avoid disruption to the community.
Hope that sheds some light on our process.

[HatulaPro]

thank you for responding. a follow up question if you don't mind. when you decide to work on breaking changes and start a new "next-version" branch, how do you sync those branches? if lets say you develop a non-breaking feature in main, how do you transfer that feature to the next-version branch? cherry-picks? merges?

[HarelM]

Manual merges, I usually take care of this and ask the person who did the PR to check that the new code is integrated well, usually there are tests to cover the functionality, and if they pass it means that the feature was ported successfully.