semver etiquette not clear enough


(Christopher J Brody) #1

I think that semver etiquette, which is basically to not publish breaking changes without increasing the MAJOR version number, is not emphasized enough and has caused needless aggravation to some major project maintainers. I already raised https://github.com/semver/semver/issues/461 to improve the documentation there; I think this should also be more prominent in the npm documentation.


(Nikki Everett) #2

Agreed – I’m in the middle of rewriting most of our documentation (and re-architecting the docs site) right now, so this is timely feedback. In particular:

I would like to see a quick, easy-to-read description of npm semver etiquette that we can point some less experienced maintainers to.

I’ll keep this use case in mind when rewriting https://docs.npmjs.com/getting-started/semantic-versioning – in general, I’m aiming for our docs to speak to the newer / less experienced maintainer and contributor audience more than they do at present.

The new docs site should be live in a few weeks, but in the meantime, let me know if there are other places you think we could nudge people in the right direction.