# Better commit messages for the changelog
**URL:** https://meta.discourse.org/t/better-commit-messages-for-the-changelog/39107
**Category:** Development
**Created:** [February 5, 2016, 5:37pm UTC](https://meta.discourse.org/t/better-commit-messages-for-the-changelog/39107 "2016-02-05T17:37:44Z")
**Posts on this page:** 17
**Page:** 1
### Author:  [@oblio](https://meta.discourse.org/u/oblio)
#### Post date: [February 5, 2016, 5:37pm UTC](https://meta.discourse.org/t/better-commit-messages-for-the-changelog/39107/1 "2016-02-05T17:37:44Z")
Hi guys,
I like Discourse a lot and I appreciate having such awesome Open Source software available for free (ignoring the cost of hosting it myself). So I hope you guys don’t think that I’m bashing the great work you’re doing with this post.
But I think there are some improvements which could be made to help users. Some of them are quite tedious and possibly annoying for developers but are quite useful for Discourse users.
I’ll make separate topics for each of the improvements I’m thinking of, this is the first one.
Discourse has a helpful message telling you that the instance is out of date and recommending to the latest version. There is an even more helpful link pointing to the changelog. And this is where things get blurry, since the link is always [Commits · discourse/discourse · GitHub](https://github.com/discourse/discourse/commits/master). Which is fine, since you can see the changes.
However… that’s the full list of changes. So you have to scroll quite a bit to find the things you want (such as: first commit included in v1.5.0.beta10, last commit included in v1.5.0.beta10). The commit messages format is not standardized and is also quite hard to parse at a glance.
I recommend adding some sort of tags at the start of the message, with a limited set of tags available: fix, improvement, doc, release, etc.
And a format which makes the tag stand one. Some examples I’ve seen and used in the past:
- FIX - … IMPROVEMENT - … DOC - … RELEASE - …
- [FIX] … [IMPROVEMENT] … [DOC] … [RELEASE] …
- FIX: … IMPROVEMENT: … DOC: … RELEASE: …
Extra style points awarded if bugfixes point to issue tracker IDs ([FIX-182323] - …) or if the changelog is automatically transformed into a human readable version such as this one: [https://www.jfrog.com/jira/secure/ReleaseNote.jspa?projectId=10070&version=15683](https://www.jfrog.com/jira/secure/ReleaseNote.jspa?projectId=10070&version=15683)
Thank you for bearing with me 🙂
---
### Author:  [@jomaxro](https://meta.discourse.org/u/jomaxro)
#### Post date: [February 5, 2016, 5:41pm UTC](https://meta.discourse.org/t/better-commit-messages-for-the-changelog/39107/2 "2016-02-05T17:41:47Z")
Did you check out the pinned #Development topic?
> [@Discourse GitHub commit prefix convention](https://meta.discourse.org/t/new-github-checkin-prefix-convention/19392):
>
> For those who want to bring changes to Discourse’s code, we require that each GitHub commit have one of the following prefixes: Prefix Definition FIX A bug fix [[1]](#footnote-70985-1) PERF A performance improvement UX A user interface change SECURITY A security problem fix FEATURE An added feature A11Y An accessibility improvement I18N Translation updates MT Changes to migrations tooling DEV A Discourse internals change that doesn’t belong in the above categories It makes it e…
There already is a convention in place. Whether it is used…that’s a different issue.
---
### Author:  [@oblio](https://meta.discourse.org/u/oblio)
#### Post date: [February 5, 2016, 5:45pm UTC](https://meta.discourse.org/t/better-commit-messages-for-the-changelog/39107/3 "2016-02-05T17:45:49Z")
Oh, sorry I missed the pinned topic. I can delete my topic since it seems to be redundant now.
I just went by what I saw on Github… and only a handful of commit messages follow that convention, as far as I can see.
---
### Author:  [@jomaxro](https://meta.discourse.org/u/jomaxro)
#### Post date: [February 5, 2016, 5:48pm UTC](https://meta.discourse.org/t/better-commit-messages-for-the-changelog/39107/4 "2016-02-05T17:48:25Z")
I’ll leave it up to [@team](https://meta.discourse.org/groups/team) to decide whether to delete, merge, or let this topic remain, as I do think you bring up a good point. While there is a convention in place, it isn’t used at all times by those who commit to the project, and I would agree that makes it much harder to follow when looking through the log.
---
### Author:  [@codinghorror](https://meta.discourse.org/u/codinghorror)
#### Post date: [February 5, 2016, 6:08pm UTC](https://meta.discourse.org/t/better-commit-messages-for-the-changelog/39107/5 "2016-02-05T18:08:03Z")
The checkin prefix conventions _are_ used – no idea what you two are on about.
If the change is trivial, we don’t feel obligated to add a prefix. **The prefix is for larger changes.** For example, if I copyedit a single sentence changing it from
> The quick brown fox jumps over the lazy dog
to
> The quick brown fox jumped quickly over the lazy dog
That is not gonna be prefixed with FIX: or anything of the sort.
---
### Author:  [@oblio](https://meta.discourse.org/u/oblio)
#### Post date: [February 5, 2016, 6:46pm UTC](https://meta.discourse.org/t/better-commit-messages-for-the-changelog/39107/6 "2016-02-05T18:46:16Z")
Hmmm… the thing is, let’s say I’m a Discourse admin. Going through all the commits is no fun.
There should be a more professional-looking changelog somewhere, IMO.
As a Discourse admin I’d like to be able to make an informed decision on updating and all the noise in the git log is not helping with that.
My 2 euro cents 🙂
---
### Author:  [@wesochuck](https://meta.discourse.org/u/wesochuck)
#### Post date: [February 5, 2016, 6:55pm UTC](https://meta.discourse.org/t/better-commit-messages-for-the-changelog/39107/7 "2016-02-05T18:55:44Z")
Discourse is in very active development so the changelogs are going to be quite long. If you want something less granular than the resources that have already been pointed out, you might want to keep an eye on the #releases category.
---
### Author:  [@oblio](https://meta.discourse.org/u/oblio)
#### Post date: [February 5, 2016, 7:10pm UTC](https://meta.discourse.org/t/better-commit-messages-for-the-changelog/39107/8 "2016-02-05T19:10:56Z")
Thanks @wesochuck for the great pointer!
I have a follow-up question: what happens then with the point updates? Should I bother with them? Especially since their naming makes me a bit worried (“beta”).
---
### Author:  [@wesochuck](https://meta.discourse.org/u/wesochuck)
#### Post date: [February 5, 2016, 7:21pm UTC](https://meta.discourse.org/t/better-commit-messages-for-the-changelog/39107/9 "2016-02-05T19:21:34Z")
You may want to consider [switching to the stable branch](https://meta.discourse.org/t/how-to-upgrade-from-a-beta-version-to-a-stable-release/29627/6). Note, I don’t think that it is possible to go from stable back to beta, so make sure this really what you want to do before proceeding.
---
### Author:  [@oblio](https://meta.discourse.org/u/oblio)
#### Post date: [February 5, 2016, 7:22pm UTC](https://meta.discourse.org/t/better-commit-messages-for-the-changelog/39107/10 "2016-02-05T19:22:38Z")
Assuming security fixes are merged into stable as well, I think I’ll switch to stable.
---
### Author:  [@cpradio](https://meta.discourse.org/u/cpradio)
#### Post date: [February 5, 2016, 7:23pm UTC](https://meta.discourse.org/t/better-commit-messages-for-the-changelog/39107/11 "2016-02-05T19:23:56Z")
They are. High security items are backported to stable, otherwise, it occurs every 3 months (roughly)
---
### Author:  [@wesochuck](https://meta.discourse.org/u/wesochuck)
#### Post date: [February 5, 2016, 7:24pm UTC](https://meta.discourse.org/t/better-commit-messages-for-the-changelog/39107/12 "2016-02-05T19:24:27Z")
It’s possible that you may have to wait until the next major point release before you can switch to stable. If you’re beta version _currently_ ahead of the latest stable version, I don’t know what happens if you attempt to make that switch. You may want to dig around a bit more before attempting the move and make sure that you have a good backup before proceeding.
---
### Author:  [@oblio](https://meta.discourse.org/u/oblio)
#### Post date: [February 5, 2016, 7:25pm UTC](https://meta.discourse.org/t/better-commit-messages-for-the-changelog/39107/13 "2016-02-05T19:25:52Z")
Is there any reason why the default installation instructions for Discourse do not lead you to stable?
The only reason I can think of is that Discourse is still developing so fast that you want users to get the latest fixes, but IMO this would warrant the use of a sub-1.0 version.
Or it’s just that no one got around to switching the default installation to stable?
---
### Author:  [@wesochuck](https://meta.discourse.org/u/wesochuck)
#### Post date: [February 5, 2016, 7:27pm UTC](https://meta.discourse.org/t/better-commit-messages-for-the-changelog/39107/14 "2016-02-05T19:27:25Z")
> [@wesochuck](#):
>
> It’s possible that you may have to wait until the next major point release before you can switch to stable.
Confirmed that it looks like you need to wait till the stable release that would put you ahead of your current beta release:
> [@Downgrade to stable?](https://meta.discourse.org/t/downgrade-to-stable/33729/4):
>
> To move between channels you got to ensure you are running forward. So… you are safe to move to “tests-passed” to “stable” just as we release a new “stable” release. Meaning, if you are on “tests-passed” now, all you can do is move to “beta” next time we cut a beta. Process for moving channels is the same… Stop upgrading Discourse Wait for a new release on channel Amend app.yml to point at channel Rebuild We cut new betas weekly, so its easy to get on that train. To get on stable you are …
---
### Author:  [@cpradio](https://meta.discourse.org/u/cpradio)
#### Post date: [February 5, 2016, 7:28pm UTC](https://meta.discourse.org/t/better-commit-messages-for-the-changelog/39107/15 "2016-02-05T19:28:36Z")
> [@oblio](#):
>
> Or it’s just that no one got around to switching the default installation to stable?
It used to be tests-passed, which is/was much more volatile. They switched it to beta to give it more stability.
The idea is beta should be fairly safe, yes it gets a lot of changes (weekly merges, etc), but most of the time is is complete new features.
Stable is for those who really do not want any regular updates (except for security).
Plus by having a lot of customers run on beta they can vet out some edge case issues with new features, like tag auto-complete, et al.
---
### Author:  [@oblio](https://meta.discourse.org/u/oblio)
#### Post date: [February 5, 2016, 7:29pm UTC](https://meta.discourse.org/t/better-commit-messages-for-the-changelog/39107/16 "2016-02-05T19:29:30Z")
> [@cpradio](#):
>
> Plus by having a lot of customers run on beta they can vet out some edge case issues with new features, like tag auto-complete, et al.
It seems fair that free users are used as beta-testers, but they should be warned about it 😛
---
### Author:  [@codinghorror](https://meta.discourse.org/u/codinghorror)
#### Post date: [February 5, 2016, 8:54pm UTC](https://meta.discourse.org/t/better-commit-messages-for-the-changelog/39107/17 "2016-02-05T20:54:17Z")
Stable is not really all that “stable”, it’s just not changing. Change = risk.