Release policy

[aaronliu0130]

Moving the discussion mostly in #353 here.

@cclauss said:

Updating the version should only be done in the release process, not before. Modifying CHANGELOG.rst is always dicey because of git conflicts. My recommendation would be that new entries only pertain to the current pull request. Put a blank line before and after all new entries (to decrease the possibility of git conflicts).

At release time, we can update the version and remove the blank lines.

What is release vNEXT? Is it v2.0.2, v2.1.0, or v3.0.0? Different pull requests making different guesses is suboptimal (git conflicts). It is best to make the vNEXT version number decision at release time.
v2.0.1 is preserved at:

• https://github.com/cpplint/cpplint/tree/2.0.1
• https://github.com/cpplint/cpplint/releases/tag/2.0.1

When releasing, we will:

• Merge a new pull request that only updates the version number and updates CHANGELOG.rst.
• Go to https://github.com/cpplint/cpplint/releases/new
• Put in the NEW version number.
• Click the Generate release notes button
• Click the Save draft button and ask other maintainers to review.
• Ship it and check https://pypi.org/project/cpplint after a few minutes.

---

@aaronliu0130 said:

Updating the version should only be done in the release process, not before.

In my opinion, it is worse. It can falsely confuse users (and support agents) into thinking the trunk software is on the latest stable release, and the only "benefit" of only updating the version on release is not needing to debate the version number. Nearly every major project I know bumps the version number immediately after release. I also do not see different PRs making different guesses on the version number, and it bumps the semver feature part as I feel like we should have at least e.g. #64 in the next release. Maybe we should just put a temporary version number (e.g. 2.0.1-next for right after releasing 2.0.1) in cpplint.py and leave the new CHANGELOG header as "TBA"? I like your blank lines idea, though.

[cclauss]

Numpy and SciPy seem to use 2.0.2.dev0 which might work nicely.

[aaronliu0130]

Yeah, I also feel like the best solution may be using a temporary version suffix, though I'm hesitant to use "dev0" (which pylint also uses) over "next". dev0 seems like it's suffixed to the presumptive next version ID instead of the last stable release version ID.

[cclauss]

2.0.2.dev0

[aaronliu0130]

... sure, that seems sane. I guess we could always bump it to higher versions later if need. Thus it's decided that we'll just bump the fix part of the semver and append -dev0 (not dot, so it fits better with semver guidelines. Pylint also uses hyphen instead of dot) :D

[cclauss]

Semver micro bump + -dev0

[cclauss]

https://pypi.org/project/cpplint is now updated.

The contents of CHANGELOG.rst and the content of https://github.com/cpplint/cpplint/releases do not need to be identical.

I would prefer that the former be for end users to read and the latter be machine-generated and include ALL changes in the release. When something goes wrong with a release, it is useful for debugging to have all changes broken down by pull request, contributor, and files touched. These details are lost with our current CHANGELOG.rst, which is just fine for end users to know the key changes.

[aaronliu0130]

Sure