Git commit messages

[billw2015]

As you maybe noticed I added automatic changelog generation for the SVN commits.
To help with this I have added a system that can improve these logs if we follow some simple rules in our commit messages.
If you want your commit to appear in a particular section of the generated log then you should use this format:

section(scope): message​

section should be one of these (we can add more if we want):

• feat - a new feature
• fix - a fix for a bug
• balance - balance changes
• perf - performance improvements

scope is an optional extra piece of information that further categorizes the change.

Some examples should clarify:

feat(Units): Added new crossbow wielding ninja stealth unit
feat(Buildings): Added missing building descriptions
feat: Added new production popup
fix(Events): Tornadoes no longer spawn in space
balance(Buildings): Pharmacy gold generation more inline with the buildings it replaces
perf: AI building evaluation optimized
Improved changelog generation

These will show up something like:

v40.0.400-alpha - 2019-09-08

Features

• Units: Added new crossbow wielding ninja stealth unit
• Buildings: Removed obsolete building texts
• Added new production popup

Fixes

• Events: Tornadoes no longer spawn in space

Balance

• Buildings: Pharmacy gold generation more inline with the buildings it replaces

Performance Improvements

• AI building evaluation optimized

All Changes

• feat(Units): Added new crossbow wielding ninja stealth unit
• feat(Buildings): Removed obsolete building texts
  
• feat: Added new production popup
  
• fix(Events): Tornadoes no longer spawn in space
• balance(Buildings): Pharmacy gold generation more inline with the buildings it replaces
• perf: AI building evaluation optimized
• Improved changelog generation

Following this pattern isn't required to get your message into the change log, as you can see there is the All Changes section listing everything. It DOES however make it a lot easier for players to see if bugs etc. that they are interested in are fixed, what game play changes to expect etc.
Also as you can imagine when it comes to making a major release like v40 this is going to make it a lot easier (not that we shouldn't also manually tweak the changelog for a full release, but this will help a lot)!

You can change commit messages on commits you have not yet pushed to github (in GK just select the commit and click on the message), but after they go to github changing them is quite difficult.

 

[olduser]

Would it be possible to add the section(scope) statements anywhere in the commit message or do they need to start with that.

Browsing the commit log with every commit starting with these statements seems not like something i would want.

Edit:
I mean something like how it works with the keywords to close issues on github.
https://help.github.com/en/articles/closing-issues-using-keywords#closing-multiple-issues

 

[billw2015]

Would it be possible to add the section(scope) statements anywhere in the commit message or do they need to start with that.

It uses a regex to parse the three parts out, so it would only work at the beginning or end of the commit summary.

Browsing the commit log with every commit starting with these statements seems not like something i would want.

I don't really see why, they make the log clearer, they add easy search terms, and allow you to visually filter by what you are interested in.
I can imagine it takes a bit to get used to, but its designed to be human readable, and this is not something I came up with my self, it is a fairly popular convention:
https://www.conventionalcommits.org/en/v1.0.0-beta.4/#summary
https://github.com/conventional-changelog/conventional-changelog

/edit Also of course it wouldn't be every commit, only those we want to call out to players specifically.

 

[olduser]

Does this also apply to pull requests and issues?

 

[billw2015]

No I don't think so, neither of those are recognized by the generator (it just generates a URL from the #number).

The Pull Request merge commit could use this if you want to call out the whole pull request, but the merge would include the commits that were in the merged branch anyway so it probably isn't necessary.

 

[billw2015]

No one except me and alberts are going to do this then? I see a bunch of commits that players would probably care about, if you put "fix:" or "balance:" at the start of the commit message then they will see them easily. If you don't then they will be in a sea of unordered commits that nobody is going to read. Its useful for the SVN commit messages, but really its main use is going to be in major release changelog where there is 1000+ commit messages (already there is 350 since we started on git).

 

[JosEPh_II]

No one except me and alberts are going to do this then?

Don't expect it anytime soon from me. And when I am ready to do a commit I may have to give the file to someone that is familiar with How to do a proper Commit.

 

[billw2015]

Don't worry I'm certain you will be able to manage it, if you got the game running from git! Committing is a lot easier:

1. Make sure you are up to date (hit fetch/pull/update)
2. Check the check boxes next to the files you want to commit (or more like uncheck any you don't want to commit)
3. Type a message in the commit message box (start it with fix:, feat: or balance: if you want players to notice it)
4. Click commit, then click push

I will make a quick video/gif of the whole thing when I get home.

 

[KaTiON_PT]

I will, just need to get used to writing that on the summary.

 

[Thunderbrd]

I'll make sure to have this manual open when I try to commit next time and see if I can't start trying to adapt to the approach.

 

[Thunderbrd]

Sorry I didn't use this on my latest... no issues were generated first that this last push would interact with and I wanted to get these in before I leave the house here so there's a little pinch in time on this.

 

[billw2015]

No issues are required, apparently I didn't explain this well: You literally just type 'fix:', 'feat:', or 'balance:' at the start of the commit description and *that's it*.
It doesn't need to correspond with an existing issue or whatever, just type those few letters and it lets the changelog generator lay them out better.

 

[Thunderbrd]

I didn't have time to reread the post at that moment was the thing. But that simplifies the explanation. I suppose this would've been a balance: item based on these categories. And it goes in the headline rather than as items in the description? So what if it's more than one of the 3?

 

[billw2015]

We can add whatever ones we want, there is actually fix, feat. balance and perf currently. You can add context as I described like balance(tech) or fix(units). If you want other categories we can add them but then it becomes more difficult to remember. "feat" is pretty general, anything that isn't a fix can pretty much always be classified as a feature (either a new one, or an update to one that isn't already covered by balance).