9

I am searching for a solution, to tag changesets in commit messages.

For me a "tag" is something like:

  • code clean up
  • user visible change
  • modifies database structure (ALTER TABLE)
  • Documentation change

Up to now I use SVN, but want to switch to git. If there would be standard, a lot of tools like trac, redmine, ... could use this.

I want this to answer questions like this:

  • If I update a system, what changes are visible for the customer, or is it just a maintance update?
  • Has the database schema changed between two versions?

Background:

Up to now I use unison to sync between DEV, TEST and PROD system. But unison does not know anything about the version management (which is SVN at the momement). I want to switch to git. And I want to see fast, what are the changes.

Example: I want to see changes between TEST and PROD. I don't want to see the source code changes, but the commit messages. But sometimes there are up to 100 commits. Here I want a filter, to exclude unimportant changes.

guettli
  • 26,461
  • 53
  • 224
  • 476

3 Answers3

10

I like to use the following tags:

ADD adding new feature
FIX a bug
DOC documentation only
REF refactoring that doesn't include any changes in features 
FMT formatting only (spacing...)
MAK repository related changes (e.g., changes in the ignore list)
TEST related to test code only.

This tag is always the first thing in the commit message and then followed by a brief description and/or the issue-id from the issue tracking system, if it exists.

I use those tags with svn and git and so far found them very convenient.

To answer your edit: This is why I like those commit tags. It's immediately visible if the commit changes the behavior or not. If your database scheme changes regularly or if these changes or very important for you, you could introduce a tag for that.

I also like to combine those tags in one commit message where appropriate. E.g., "TEST DOC setup of test foo".

With an additional DB tag for database, you could easily keep track of database related changes.

mort
  • 10,940
  • 14
  • 45
  • 92
  • +1 for the nice answer. But what if I need to have more info about the change using its tag? e.g. I need to more about a defect (its reporter, its criticality, its reproduction steps, etc) resolved in a FIX tag. – Gupta Jan 06 '12 at 10:10
  • Then you can just add all this information after the tag, e.g., "FIX issue foo reported by john doe;..." – mort Jan 06 '12 at 11:24
  • Sorry, I don't understand what you mean by that last comment. – mort Jan 06 '12 at 14:16
  • 1
    The [NumPy development workflow](http://docs.scipy.org/doc/numpy/dev/gitwash/development_workflow.html) lists some standard abbreviations. – Ioannis Filippidis Dec 09 '15 at 07:11
5

Most of the time I'm using the tag system from Typo3: http://wiki.typo3.org/CommitMessage_Format_(Git)

It uses tags in commit messages like this: [TAG] Short message Of course I always pop in an issue number for issue tracking. We're using JIRA so it will become something like this: [TAG] JIRA-123 Short message

Typo3 tags:

Possible tags are:

  • [FEATURE]: A new feature (also small additions). Most likely it will be an added feature, but it could also be removed. This can only happen in v4's "master" branch, because no new features are allowed in older branches. Exceptions to this have to be discussed on a case-to-case basis with the corresponding release managers.
  • [BUGFIX]: A fix for a bug.
  • [TASK]: Anything not covered by the above categories, e.g. coding style cleanup.
  • [API]: An API has changed, methods or classes have been added or removed; method signatures or return types have changed. This only refers to the public API of TYPO3.

Additionally other flags might be added under certain circumstances:

  • [!!!]: Breaking change. After this patch, something works differently than before and the user / admin / extension developer will have to change something. Should only happen on "master".
  • [WIP]: Work In Progress. This flag will be removed, once the final version of a change is available. Changes marked WIP are never merged.
  • [SECURITY]: Visualizes that a change fixes a security issue. This tag is used by the Security Team, in case you found a security issues please always follow get in contact with the Security Team first!

Example topic descriptions:

  • [BUGFIX] Throw HttpStatusExceptions in tslib_fe
  • [BUGFIX][SECURITY] SQL Injection vulnerability in prepared statements
  • [FEATURE][CONF] Add option to hide BE search box in list mod
  • [!!!][FEATURE] Move Advanced Frontend Editing to TER
  • [!!!][TASK] Remove t3lib_sqlengine
  • [!!!][API] Remove deprecated method redirect() from t3lib_userAuth
  • [API] Create an Exception hierarchy for HTTP Status Exceptions
7ochem
  • 2,035
  • 1
  • 29
  • 37
1

I prefer to assign each change set with an issue in my issue tracker. Using known issue trackers like jira, it is possible to select the issue that is resolved in a change set. After selecting an issue, the issue description is automatically placed in the message of the change set. They can be followed up in future and also be reported in your issue tracker.

Gupta
  • 7,679
  • 4
  • 29
  • 56
  • I updated the question. The tags should answer questions like this: "If I update a system, what changes are visible for the customer, or is it just a maintance update?" – guettli Jan 06 '12 at 08:01
  • How do you handle commits that are not connected to an issue? E.g., if you add or correct some documentation or refactor something? – mort Jan 06 '12 at 08:51
  • @guettli: All of these info are kept in your issue. In addition, other info such as the one requested the change, the version of the source code that this change applied on, the first release in which these change affected, ... are kept on the issues on the issue tracker. – Gupta Jan 06 '12 at 10:06
  • @mort: As a SCM (software configuration management) practice, EVERY change in the system should be made according to an issue. – Gupta Jan 06 '12 at 10:07
  • 1
    @hsalimi: I disagree. Think about the following situation: you work in your code and find some inline comments that contain spelling mistakes but are not related to any issue in your issue database. What do you do? Create an issue for a spelling mistake just to be able to connect the commit to an issue? I would simply commit the correction of the spelling mistake using a commit message like "DOC FIX spelling". This way, when scanning the commit history, one immediately sees that one doesn't have to have a closer look at this particular commit. – mort Jan 06 '12 at 11:30