Implement Git Commits Convention (w/ Emoji)

[chrisjsewell]

Just a bit of fun, but I quite like the idea of consolidating our commit "protocol" to use an emoji based system:
(a) its just more visually appealing, but also (b) it would standardise commits in a way that could allow for automated changelog creation

https://github.com/carloscuesta/gitmoji has lots of stars, but actually I quite like https://github.com/ahmadawais/Emoji-Log for its simplicity. Although basically we just agree on some commit categories + emojis and stick to them across the organisation.

Thoughts?

[choldgraf]

I don't have super strong opinions on this - is it something that people have to manually install first, or remember to type when they make a commit?

cc also @rowanc1 who has an impressive git-emoji-practice in his repos https://github.com/iooxa/editor

[rowanc1]

Ha, I have seen this on a few repos. Beyond it actually helping to visually separate out packaging and readme commits etc. I think it makes the package seem more approachable/fun?

It is nice to see that there are actually standards/suggestions out there for this, I challenge myself to find a emoji that represents my (mood + commit) % rockets which probably won't scale. ...

👍 from me!

[chrisjsewell]

No theres no installs or anything, its just a convention we agree on. Even if we didn't do it with emojis it just feels better practice to categorise commits (FIX, DOCS, NEW, IMPROVE, ...)

@rowanc1 one thing I wanted to clarify actually; do you directly use the emojis, or write in the github shorthands e.g. :smile: (😄)

[rowanc1]

Yep, I just use an emoji picker (cmd-ctrl-space on a mac) -- all though a real life, emoji keyboard is tempting. :)

[chrisjsewell]

yeh thats what I do... use the emoji keyboard 😆 🤣 🙃 👍 🍻

[chrisjsewell]

I am going to start using this convention; <EMOJI> <KEYWORD>: <HEADING>, with the following:

Loosely from emoji-log:

• ✨ NEW: <msg>: emoji :sparkles: — to introduce a new feature(s).
• 👌 IMPROVE: <msg>: emoji :ok_hand: — to improve an existing code/feature (with no breaking changes).
• 🐛 FIX: <msg>: emoji :bug: — to fix a code bug.
• 📖 DOCS: <msg>: emoji :book: — to add new documentation.
• ‼️ BREAKING: <msg>: emoji :bangbang:— to introduce a breaking change (and removing deprecated code).
• 🧪 TEST: <msg>: emoji :testube: — to add additional testing only.
• 🚀 RELEASE: <msg>: emoji :rocket: — to bump package version for release.

Additional (loosely from gitmoji):

• ✏️ REWRITE: <msg>: emoji :pencil2: — to apply fixes (like correcting typos) to existing documentation.
• ⬆️ UPGRADE: <msg>: emoji :arrow_up: — for upgrading a dependency pinning.
• ♻️ REFACTOR: <msg>: emoji :recycle: — for refactoring existing code (with no specific improvements).
• 🗑️ DEPRECATE: <msg>: emoji :wastebasket: — mark some code as deprecated (for removal in a later release).
• 🔀 MERGE: <msg> emoji :twisted_rightwards_arrows: — for a merge commit (then all commits within the merge should be categorised, but generally you should just use squash+commit or rebase commit)
• ❓ OTHER: <msg>: emoji :question: — anything not covered above (use as a last resort!).

I think this captures just about everything, as concisely as possible?
This would then essentially be used to sort the changelog of a release into sub-headings, something like:

• Added: NEW
• Improved: IMPROVE
• Fixed: FIX
• Breaking: BREAKING + UPGRADE
• Deprecated: DEPRECATE
• Documented: DOCS

(other categories would not be included)
As well as visuals, this is the main thing here: to get you to think up front about how commits will be transposed into the changelog

If so, it would be nice if others could agree and also do the same 😁

[choldgraf]

I like all of those icons for sure - I'm also +1 on having this be a convention but not a hard rule (e.g. I don't want to block somebody's PR saying 'you can't merge this until you push a new commit that has a smiley emoji in it :-)")

That said - I just realized: we'd only be doing this on the squash commit, right? So this is something that a maintainer to could choose to add?

[chrisjsewell]

So this is something that a maintainer to could choose to add?

Yep exactly, as I've moaned about before lol (and now everyone is generally following 😄):

• Commits to the main branch of a repo should generally be the result of a Squash and merge PR; at which time the maintainer can enact this convention.
• If it is a particularly big PR, with more than one feature/category, you may want to Rebase and merge (or obviously just split the PR into separate PRs). At this point, I would definitely recommend doing yourself (if it's your PR) or at least asking the contributor if it would be possible to do an "interactive rebase" (see https://thoughtbot.com/blog/git-interactive-rebase-squash-amend-rewriting-history). At this point you can squash consecutive commits together (using "fixup") and also rewrite commit messages (using "reword") to create a compliant history.
• Very rarely, if merging branches with many contributions, you would use a merge commit In this case ideally each contribution has already been a result of a Squash and merge PR to that branch.

[choldgraf]

I'll try to start using this convention for the PRs that I merge 👍 . @chrisjsewell wanna make a PR to the executablebooks.org repository that has a little table of emojis -> their meaning like you shared above? Otherwise I will definitely forget haha

[chrisjsewell]

cheers yeh will do, then just give any feedback here as you use it, e.g. suggestions for adding/removing/renaming categories

then at some point we can probably find/write a script to auto-generate release/changelog sections, by parsing the commit history (since the last release) and sorting/filtering commit messages (identified by regex) into the sub-headings I mention above

[chrisjsewell]

For future reference: executablebooks/sphinx-copybutton#88 (comment)