Hm. In that case, smaller more frequent breaking changes may also not be ideal. It sounds like no matter how small the breaking change, everyone who uses the library is going to have to update their code… and if it’s happening frequently, that could get annoying.

This may be completely off-base, but just going off of what you said about data traversal, would it be completely out of scope for your library to provide a consistent interface for getting/traversing the data it is responsible for? Or do the consumers all use/traverse the returned data in very unique ways such that you couldn’t really develop a “general” API of sorts.

Context:

I’m a dev that consumes company wide libraries, not an author of such libraries. So the following comes from that perspective.

A couple questions:

1. Is development and consumption of your library happening in parallel? It sounds like you use the users to vet new features or major changes… is that correct? (They are iterating with you and reporting back on issues or desired changes)
2. Is your library made up of a group of isolated components? Or is it a library that does one or two major things and so a breaking change literally changes the whole of what the library does?
3. How are the consumers of your library when it comes to adopting changes? Do they readily do it? Is there a good bit of inertia?

My thoughts:

First off, SemVer is definitely going to be important. Also, it sounds like you’re working toward API stabilization which is going help iterating in the future.

My idea 1:

If your library is made up of several isolated components, what about doing major releases (ex 2.x.x -> 3.x.x) more frequently? Only include a small subset of breaking changes for one or two components rather than jamming a whole bunch in there just because it’s a “major version release”. The result is you could move quickly and iterate while also minimizing the impact on ALL of your users every release. Some of your users may be able to upgrade to the latest without having to touch much or any of their code.

My idea 2:

Do frequent major release (ex 2.x.x - 3.x.x) but always start with an “alpha” release that early adopters could implement and provide feedback on. This would shield the majority of your consumer’s code from having to iterate frequently but would also require you to enlist a group of committed early adopters that are diligent about iterating their code as often as you release.

Feedback on the original option 1 and 2

Option 1

This could work if your users are excited about your releases. But, it could result in people NEVER upgrading because it’s too much work to do so. (I’ve seen this happen. No one upgrades until they absolutely have to.)

Option 2

Depending on the size of your company, this will be a lot of work for you and will slow you down. If you’re using your users to vet out new features, then everyone is going to have to iterate frequently (like you said) if experimental changes don’t work out.

What did it for me is I stubbornly refused to use Git via VSCode and stuck with the terminal. I also stubbornly refused to change my default text editor for GIT to something other than VIM. One light bulb moment I had, funnily enough, was when I finally read the VIM docs and learned how to save and close rather than panicking when it popped up (this was early on… but not THAT early on … so still funny). That sparked my curiosity to truly learn VIM.

After that, I realized command line tools could be learned and advantageous and so it just went up from there.

Honestly, I’ve noticed a difference in the confidence level of peers using command line tools based on whether or not they learned GIT using command line or jumped straight to just clicking the buttons in VSCode.