How to deal with breaking changes?

[primeapple]

With https://github.com/okuuva/auto-save.nvim/pull/48 we have our first breaking change that is inevitable to come.

I'd love to get this fixed because now that I see the typo I can't unsee it but not sure how to deal with this. It's a breaking change and in theory we should have some grace period where both options work but old option would show a warning during plugin init. But that sounds like quite a hassle just to fix a typo...

Then again, we should have a mechanism for deprecating options, so that we could at some point get rid of execution message dimming and cleaning interval. So I think we should implement that deprecation mechanism first and apply it here before merging. By @okuuva

We have to find a way on how to deal with breaking changes. Here are some ideas, they don't exclude each other:

1. Add a small function to display a deprecation message whenever a user tries to access deprected functions/config/etc. This sounds easy, but unfortunately does not scale very well. We would have to keep a list of deprecations. We would need "safe access" wrappers for accessing the config. That sounds a bit to much for such a small plugin as we have. But maybe there is a good way.
2. Start adopting https://semver.org/lang/de/ . That at least would make it easier for the users to pin working versions. We can maintain a changelog to indicate what changes with which version. I would try to do semver via tags and not mix branches in, but this is still a good read: https://phaazon.net/blog/neovim-plugins-stability

[primeapple]

Ok, my plan is the following:

1. Tag the current state of the main branch as v0.0.0
2. Try to collect all needed breaking changes (for now) in a feature branch (first_breaking_changes)
3. When we merge the feature branch, release it with tag v1.0.0. Make sure we adjust the README here.

Are you fine with this @okuuva ? Btw. thats a nice read about versioning: https://vhyrro.github.io/posts/versioning/

[okuuva]

Hey, sorry for ignoring this for so long. Been busy with life and this issue felt much bigger than it actually is so I didn't want to touch it for a while.

I agree that including a deprecation wrapper for such a small plugin is overkill. If there was such a thing readily available in some common helper library (like plenary) then it would be viable but there's no point for us to brew one ourselves.

So semver is the way to go. Well, it would've been even with the deprecation functionality but still.

@primeapple your plan sounds great. I think that we should tag the current main as v0.0.1 instead of v0.0.0 but other than that it sounds good to me.

[primeapple]

I pushed tag v0.0.1 Thanks for your input.

[primeapple]

Awesome. Tag v1.0.0 is pushed. I'm still not very keen on writing release notes, but maybe we find something for that in the future. For now I'm happy it's over :)

[primeapple]

Ahh, maybe you could enable the Releases feature for this repo? So that the users can see the created tags: https://docs.github.com/en/repositories/releasing-projects-on-github/viewing-your-repositorys-releases-and-tags

EDIT: I realized, we see the tags already. If we do ReleasePlease, we need the releases, otherwise we might skip it :)

[primeapple]

I thought about it a little more. We could use Googles ReleasePlease Github Action to create Releases. Example: https://github.com/Robitx/gp.nvim/blob/main/.github/workflows/release-please.yml

But it also may not be needed.

[okuuva]

I'm all for automating everything that can be feasibly automated. Including creating releases and generating changelogs (Conventional Commits should make that easy). I'll try to get around these this weekend. I'll start by enabling Releases right away. Thanks!

[okuuva]

Oh. Releases are already enabled. One just have to create one manually from a tag. Or automate it with an action. Well, I'll check it out later today or tomorrow.