Consider sticking to semantic versioning

[jozuas]

While it is not my business managing this project, I think it would be nice to consider sticking to semantic versioning scheme.

Today I got a bit surprised when I did mix deps.update --all :

And found out that a minor bandit version 1.4.1 introduced breaking changes:

[mtrudel]

Thanks for the note. I appreciate the perspective; these changes were ones that I thought long and hard about, and that we had a number of internal discussions about as well. The answer basically amounts to 'maintenance burden'. Allow me to explain:

If we were to have honoured semver for this change, we'd have had to cut a 2.0.0 release, which would have meant that anyone pinning to ~> 1.0 would have had to take explicit action to pull in this new version. At the same time, the vast majority of our usage is within Phoenix projects. The way Phoenix generates applications means that essentially all of our users are in fact pinned to ~> 1.0 in this exact way.

Experience seems to suggest that the majority of users never do anything to upgrade most of their dependencies. Since Phoenix generates mix.exs files that pin to ~> 1.0 as above, the likelihood is that the majority of our users will stay on the 1.0 release tree 'forever'. This being the case, we'd be in a position where we'd have two options:

1. Let the 1.0 release tree rot and deny the vast majority of our user base any future improvements, or;
2. Backport all new work against to the 1.0 tree for the rest of time

Neither of these make any sense, especially for something as small as a config option & a few telemetry changes (not to mention, the config option in question was only introduced in a minor release a few months prior). Cargo-cult style blind adherence to semver just for the sake of it is not something I'm interested in; I do this for fun, not to get burnt out.

Moreover, we maintain a ruthlessly detailed CHANGELOG that is updated on every release, and is literally the first thing I point to when I publicize releases (if you're not already a member, you should join the #bandit Elixir slack channel where we announce every release, alongside such a link). Breaking changes (which, to be clear, we go to great lengths to avoid) are always called out prominently in the changelog.

It's also worth noting that the project has never claimed to conform to semver; there has never been a mention of it in the README or elsewhere, and even personally I've never felt a need to bound myself to such a restrictive yoke. To be clear, I cannot and will not promise to not violate semver in the future, though I will continue to do my level best to avoid breaking changes except where absolutely necessary.

But ultimately (and with the utmost respect) I think you're expecting too much of maintainers. None of us work for you, and there isn't a project in the world that owes you conformance to semver as a matter of course. The reality of this or any endeavour (technological or otherwise) is compromise. Semver is, in many real and tangible ways, a bit of a prison for maintainers; it doesn't magically solve problems so much as it moves burden onto the shoulders of maintainers. It presumes a world where users (and other package maintainers with transitive dependencies) move fast, are hyper aware of their dependencies, and know the pedigree and development direction of everything in their deps folder. This, unfortunately, does not map to reality in any meaningful way. If we as a community are going to make this grand experiment work in a sustainable manner, there needs to be some concession and adaptability on the part of users.

Turning back to the prescriptive aspects of your situation, you may want to look at the changes that just came out in 1.5.3 with the log_protocol_errors option. It now provides (and defaults to) a value of :short, which will cause one-line summaries of protocol errors to be logged. Moreover, I'll note that this is actually one of the more actively developed corners of the project at this point (a lot of people have a lot of opinions on how logging should work), so I can't promise it won't change again in the future (though I have no open plans for it to do so). If there are future changes, they will of course continue to be called out prominently in the changelog.

Thanks again for the discussion.

[ryanwinchester]

RomVer best versioning

https://github.com/romversioning/romver

(it’s how most projects actually version anyway)

[jozuas]

Thank you for such an insightful and detailed answer.

And thank you for such a great project.