Proposal for adding semantic-release to Hubot 🤖

[espy]

semantic-release makes releasing faster, simpler and safer by automating the entire release workflow and removing human decision making from versioning. All of this is valuable if we want to increase public participation in the project and increase momentum and motivation.

👉 Check out the proposal 👀

Steps to complete:

• An admin/owner sets up semantic-release
• Update CONTRIBUTING.md with commit message guidelines and new release process
• Remove CHANGELOG.md, in this release’s notes, link the file in the last tag that still has it, for future reference

More details for these steps in the proposal.

[bkeepers]

👍 I'm excited to see this in action.

[gr2m]

we use semantic-release at all our Hoodie repos and I also use it at all node modules I maintain myself. I could not imagine to ever look back again. It makes accepting fixes / features trough pull requests a breeze, because once merged into master (making sure the commit messages follow the correct standard) the release is automated, which is great for both maintainers and contributors

[gr2m]

I would like to add to the todo list that we should release one last version manually [email protected] and enable semantic-release afterwards

[bkeepers]

Actually, one other thing I think we should change in this PR… update the README to remove Hubot 3.0.

[gr2m]

@bkeepers you mean to rename the Hubot 3.0 milestone to something like Hubot Workflow Edition? I would do that with another PR maybe?

[bkeepers]

@gr2m I'd just drop the 3.0. I can open another PR for it.

[technicalpickles]

This looks really exciting, thanks for putting it together!

I added some line-item questions that I was hoping to have answered before approving & merging.

[technicalpickles]

I see there's links to semantic-release further down, but could you make sure there's a link the first time it's mentioned?

[gr2m]

e47868b

[technicalpickles]

It also does away with the concept of intentional, manual releases: whenever something lands in master and passes all the tests, semantic-release will package an npm release

This is really cool. This is pretty close to how I worked previously when making changes, basically timeboxing a day to see how much I could merge and then release that with whatever semantically appropriate version.

[gr2m]

if you want to release bug fixes / features from multiple PRs, you can merge them first into a release branch, and then merge that into master.

[technicalpickles]

I think this detail is worth discussing a bit. I am not familiar with this expected commit message formatting, but it seems like it would impact possible contributors, as well as maintainers. I know personally, I don't have a good habit of well formed commit messages 😅

What kind of learning curve do you think there is getting started with this? Are there tools or helpers with getting going with expected commit message format? Does it assume that pull requests are going to be rebased and squashed with the right format?

[timkinnane]

I use commitizen with another project that I use semantic-release with. It's a cli wizard (like npm init) to build commit messages in the standard format, which I gather is the convention used by the Angular team and widely adopted since.
https://github.com/commitizen/cz-cli

It's a global module, so I don't know how you'd encourage others to use it, but maybe that's good because you can just make a suggestion for those that need help, otherwise you're still free to write you're own.

The most opaque aspect for me is choosing the "scope". I find it hard to apply consistent semantics for my commits.

[gr2m]

I would suggest we put the most common commit messages into our CONTRIBUTING.md files. fix: ..., feat: ... and BREAKING CHANGE: are the only three that really matter for semantic-release as only they have impact on the calculated version and only these commit messages will be parsed for changes added to a GitHub release.

We have a short summary in Hoodie’s CONTRIBUTING.md file

[technicalpickles]

@timkinnane's suggestion of https://github.com/commitizen/cz-cli to help with formatting the commit messages correctly. I suspect that I personally will struggle with getting this right to start 😅

One question I didn't see an answer to:

Does it (semantic-release) assume that pull requests are going to be rebased and squashed with the right format?

[gr2m]

Does it (semantic-release) assume that pull requests are going to be rebased and squashed with the right format?

Merging is fine, but the commit messages should be cleaned up first, either by the people who started the PR or the people who reviewed it. Squash and merge is a nice shortcut, but I understand that we don’t want to enable that option at Hubot.

A nice little project could be a service which sets a PR status based on its commit messages. It could set status to failure if one of the commits doesn’t follow the convention. And it could set the description to the version number it calculated based on the currently released version and the commit messages of a PR. I’d love that to exist :) I can help spec it out but don’t have the time myself to build it right now.

[technicalpickles]

Merging is fine, but the commit messages should be cleaned up first, either by the people who started the PR or the people who reviewed it. Squash and merge is a nice shortcut, but I understand that we don’t want to enable that option at Hubot.

The reason for not enabling squash and merge is that we tend to not work that way with internal projects, and I will say I have not done that on hubot. In particular, it preserves the original commit history, so it's easier to interact with other branches, cherry-picking, and merging other branches into it.

If we are encouraging contributors or maintainers to be cleaning up commits before merging, then it is kind of functionally equivalent to allowing squash and merge, since it'd involve rewriting the history.

Not saying no, but making sure this is clearly understood to be a change in how the project operates on pull requests.

[gr2m]

I think a best practise we can agree on is to keep pull requests as small as possible. When you do that, there won’t be a need of cherry-picking because things just get merged much faster and automatically released all the time. I do squash a lot in other projects, especially the ones that use semantic-release, it helps greatly with the workflow of accepting contributions because it’s a "Let me fix this for you" instead of "Read the CONTRIBUTING manual".

If the cause problem of you only allowing merges internally is long-standing pull requests, than I’d invest into avoiding that, and I think semantic-release helps with it because it adds additional incentives to merge & release often, as it takes away a lot of the manual overhaed

[technicalpickles]

@gr2m thanks for the context! I am on board, but I'd like to see an item in the detailed description to update release documentation to mention release branches & commit cleanup a maintainer might need to do.

[technicalpickles]

Instead of manual release documentation, might be worth talking about about the idea of a release branch to merge feature branches into, and also the work a maintainer might have to do to cleanup the commits of an incoming branch.