Version number

I agree with you that we should have a better documented process (we should be putting out stable version updates more regularly — I would say something like once per sprint with a target version based on what we plan to add in those two weeks — so teams don't have to use prerelease packages in their projects...they should really just be for internal testing). The way I've traditionally handled versioning (semver) is:

Stable Versions:

Major: breaking (non backwards-compatible changes). Users will have to make changes in their application to use the new version.
Minor: new features added. Backwards-compatible (no code changes required in user/consumer code)
Patch: bug fixes for existing features. Backwards-compatible (no code changes needed by user)

Pre-release versions are not stable versions, so breaking changes from x.y.z-alpha.a -> x.y.z-alpha.b are acceptable and expected.

Example:

We just released version 1.0.0
We are expecting to add some new features and bug fixes for our next stable version
We implement a new feature A and put out a 1.1.0-alpha.0 to test (we target a minor version update because we have added a new feature relative to 1.0.0).
We add a bug fix and put out a 1.1.0-alpha.1 (this bug fix still falls under the umbrella of new features and fixes that we want to go out in 1.1.0, so it's not 1.1.1-alpha.0 because 1.1.0 doesn't exist yet to be patched)
We change the API of feature A (breaking change to it's initial implementation) and put out a new test version 1.1.0-alpha.2 (we don't update the major version because all of the changes thus far are still backwards compatible with the 1.0.0 stable version).
Everything looks good, so we release 1.1.0. People who were using 1.0.0 can upgrade and use the new feature without any changes in their application code.
If we jumped to 2.0.0-alpha.0 after the rewrite of feature A, that would imply that version 2.0.0 has breaking changes from version 1.0.0, but that's not true.

 

Similarly, if we had done the patch work first, our first prerelease version could have been 1.0.1-alpha.0, because the work in progress at that point is just a patch to the stable 1.0.0. Then when we did the feature work, we would have to bump the alpha to 1.1.0-alpha.0, because now there is a new feature relative to 1.0.0