Add bump command

[simonpasquier]

Moving forward with release automation, I suggest to add a 'promu bump' command that updates the CHANGELOG.md file by looking at the pull requests merged since the current version. It also updates the VERSION file if it exists.

A few examples:

• promu bump updates from "X.Y.Z" to "X.<Y+1>.0-rc.0". This is identical to promu bump --level minor --pre-release rc.0 --base-branch master.
• promu bump --dry-run, the same thing but it displays the generated changelog instead of modifying CHANGELOG.md and VERSION.
• promu bump --level pre --pre-release rc.1 --base-branch release-X.Y updates from "X.Y.Z-rc.0" to "X.Y.Z-rc.1".
• promu bump --level pre --pre-release "" --base-branch release-X.Y updates from "X.Y.Z-rc.x" to "X.Y.Z".
• promu bump --level patch --base-branch release-X.Y updates from "X.Y.Z" to "X.Y.<Z+1>".
• promu bump --pre-release "" updates from "X.Y.Z" "X.<Y+1>.0". This is for projects that don't do release candidates.

To avoid rate-limiting from the GitHub API, it is possible to provide an API token using the GITHUB_TOKEN environment variable.

The command uses PR labels to classify the change (eg a PR labelled with bug will turn into * [BUGFIX] <PR title>. #<PR number>, PR labelled with kind/feature will turn into * [FEATURE] <PR title>. #<PR number>, and so on). Pull requests for which no label matches will be added as comments (useful to exclude cosmetic changes like typo fixes or dependency updates).

Here is the output when I run promu bump --pre-release "" on this repository:

diff --git a/CHANGELOG.md b/CHANGELOG.md
index bc5d98a..5f5bd66 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,3 +1,27 @@
+## 0.6.0 / 2019-10-04
+
+* [FEATURE] Add 'check changelog' command. #168
+<!-- Unclassified pull requests:
+* [] Synchronize Makefile.common from prometheus/prometheus. #155
+* [] Synchronize Makefile.common from prometheus/prometheus. #156
+* [] Synchronize Makefile.common from prometheus/prometheus. #157
+* [] improve error handling when parsing CHANGELOG. #161
+* [] Remove Travis CI. #164
+* [] updated helptext for promu build args. #163
+* [] Synchronize Makefile.common from prometheus/prometheus. #166
+* [] README.md: update required Go version. #167
+* [] Synchronize Makefile.common from prometheus/prometheus. #169
+* [] Bump golang 1.13. #171
+* [] Remove unused Quote() function. #173 -->
+
+Contributors:
+
+* @geekodour
+* @juliusv
+* @pgier
+* @prombot
+* @simonpasquier
+
 ## 0.5.0 / 2019-06-21
 
 * [CHANGE] Remove --broken from git describe. #145
diff --git a/VERSION b/VERSION
index 8f0916f..09a3acf 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-0.5.0
+0.6.0
\ No newline at end of file

[matthiasr]

I tend to curate what I write in the changelog vs. what's in the PR, because the audiences are different. For one, I don't want to litter changelogs with Synchronize Makefile.common from prometheus/prometheus. These are simply not relevant once the release is built.

But even for substantial changes, the PR often is more "what changes in the code" while I try to keep changelogs to "what changes for users/operators".

I'm not particular on how but I would like to retain the ability to do this at the time of merging the PR when I have the context on it (vs. editing an auto-populated changelog later).

[matthiasr]

Additionally, I also like to leave more detailed notes on specific (breaking) changes like "how to migrate" outside of the immediate list.

[simonpasquier]

I tend to curate what I write in the changelog vs. what's in the PR, because the audiences are different. For one, I don't want to litter changelogs with Synchronize Makefile.common from prometheus/prometheus. These are simply not relevant once the release is built.

100% agreed, it doesn't/shouldn't prevent you from adding more things like breaking changes or migrating details. The purpose of the comment isn't to commit the modifications blindly but to offer a starting point and make sure that no PR is left behind. For the automatic updates like Makefile.common, we should have the script label the PR with skip/changelog so the bump command would skip it.

But even for substantial changes, the PR often is more "what changes in the code" while I try to keep changelogs to "what changes for users/operators". I'm not particular on how but I would like to retain the ability to do this at the time of merging the PR when I have the context on it (vs. editing an auto-populated changelog later).

I don't have a good answer either. As maintainers, we could sanitize the PR description once it gets merged but it would require some discipline. Another approach I've seen is to ask contributors to update CHANGELOG.md in the PR but it can become tedious for small changes or one-time contributors.

[matthiasr]

yeah I explicitly don't ask for that because I want to keep control over the changelog. Changing the PR title/description might be an option. In Kubernetes there are also mechanisms to extract changelog entries from specially-formatted parts of the description.

[krasi-georgiev]

"changelog/bugfix"

why not use the existing labels? If a PR doesn't have an appropriate label than just skip it.

Will just need to format those to be closely tied to:

[CHANGE]
[FEATURE]
[ENHANCEMENT]
[BUGFIX]

and this will also encourage the maintainers to label PRs accordingly. Actually if you add this to the tool I will go through the PRs and will add labels and will start using it right away.

Contributors:

what is the idea with the contributors? Give some credit? I think that would be a good addition.

[simonpasquier]

what is the idea with the contributors? Give some credit? I think that would be a good addition.

yes, the goal is to acknowledge the work being done. It would be tedious to do manually but since the command already has all the data, I thought it would be nice to add.

[krasi-georgiev]

just used the tool and it saves a lot of time :) did some code changes to reuse the existing labels and uses strings.Contains to match when it has BUGFIX, FEATURE.... etc. when a PR doesn't include a matching label just adds it to the skipped PRs. works quite well

the only thing I would change is to not rely on the VERSION file . At the moment my workflow was: -> run the tool to see all PRs -> go to prometheus commits and check each one in the list to update their labels -> run the tool again with the the updated PR labels

so when it relies on the VERSION file It doesn't allows re-running the tool without reverting the changes to the changelog and the version file. maybe should just get all tags and query all commits after the latest tag and than always overwrite the VERSION file for the changelog should just append to avoid overwriting any user changes

[simonpasquier]

@krasi-georgiev I've implemented your suggestion to leverage existing labels. I've also added a --dry-run flag so it doesn't modify the files and just output the changelog entry to standard output.

@SuperQ I've tried to extract unnecessary code from the anonymous function.

@matthiasr I've looked at Kubernetes and their tool looks for patterns in the pull request's description. Implementing something similar wouldn't be complicated IMO and we could always fallback using the pull request's title (maybe as a follow-up?).

[krasi-georgiev]

https://github.com/prometheus/promu/blob/86bdcd52b3ac6180bf991e5c84564c260916decb/pkg/repository/info.go#L82

One thing that might be problematic is the at the moment it relies on the upstream repo to be called origin which wasn't in my case. I renamed it so not a big deal, but if there is another way should use that instead.

[simonpasquier]

Regarding the last comment, it isn't specific to the proposed bump command and it can be handled in a separate PR.

[krasi-georgiev]

I just tried the tool again when preparing the 2.13.1 release.

promu bump --base-branch="release-2.13"

The only problem was that it updated the VERSION file to 2.14.0-rc.0 instead of 2.13.0 and the same for the changelog.

[simonpasquier]

@krasi-georgiev you should have run promu bump --level patch --base-branch release-2.13

[brian-brazil]

yes, the goal is to acknowledge the work being done. It would be tedious to do manually but since the command already has all the data, I thought it would be nice to add.

I don't think we should include this in the changelog. Just as with the general changelog, if someone wants a blow by blow account they can look at the git logs. Let's keep it to things that affect users.

We could always mention them in the email only.

[roidelapluie]

Note: I have used this in 2.17 release and it is a really nice helper.

[roidelapluie]

We miss the commits that are on the master branch between the release branch creation and the release branch merge back, like this commit in red:

[bwplotka]

I would love to use it in Thanos, but we follow standard CHANGELOG format: http://keepachangelog.com/en/1.0.0/

Do you think it makes sense to contribute to this PR (in sep branch) to achieve this @simonpasquier and some day keep in promu or it does not make sense? 🤗 Would love to leverage your work!

[bwplotka]

Hm, now I see so many other features I would need for this, let me sum all up:

• http://keepachangelog.com/en/1.0.0/ format
• Contributors list is amazing
• Version has to be bumped in many other places depending on project (e.g Thanos vs Prometheus)

• The command uses PR labels to classify the change (eg a PR labelled with bug will turn into * [BUGFIX] <PR title>. #<PR number>, PR labelled with kind/feature will turn into * [FEATURE] <PR title>. #<PR number>

Labels can differ too, but logic is reusable!

This feels orthogonal and quite complex -> It would be easier for user to just provide new version?

Otherwise it looks perfect 🤔

[bwplotka]

Wonder if we checked https://github.com/git-chglog/git-chglog if we could reuse it 🤗