9

I've adopted a tagging system of x.x.x.x, and this works fine. However, you also need to leave a comment with your git tag. I've been using descriptions such as "fixes bug Y" or "feature X", but is this the best sort of comment to be leaving? Particularly, what if a tag encompasses several fixes, it seems not to make sense to have a very long tag comment. Does this mean that I should be creating a tag for every bug fix or feature, or should the tag comments be reflective of something else? I have a few ideas that may be good, but I'd love some advice from seasoned git tagging veterans :)

For those who prefer specific examples:

1.0.0.0 - initial release
1.0.0.1 - bug fix for issue X
1.0.0.2 - (what if this is a bug fix for multiple issues, the comment would be too long, no?)

Another example, in this example, the comments are more or less the same as the tags, it seems redundant. Is there something else we could be describing?

https://github.com/osCommerce/oscommerce2/tags

Improve this question
7
  • 6
    You shouldn't be tagging every little thing. What you're showing here is what commit messages were made for. Tags should be used for milestones, releases and the like.
    – Martin Green
    Commented May 29, 2013 at 5:50
  • I'm not sure I follow - each of these bug fixes may contain multiple commits (not necessarily for bug fixes, but certainly for features). Bug fixes need to be pushed to production, and thus it seems necessary to tag them, no?
    – Eva
    Commented May 29, 2013 at 5:54
  • What is the perceived benefit of doing that?
    – Martin Green
    Commented May 29, 2013 at 6:07
  • It keeps all releases well documented; it's easy to compare changes between tags as opposed to having to dig through commits that do not always represent releases. It also makes it easy to "roll back" to the last release if necessary. An example of this can be found here: github.com/osCommerce/oscommerce2/tags but in this example, the comments are more or less the same as the tags. I'm looking for a better system to fully maximise the utility of the comments
    – Eva
    Commented May 29, 2013 at 6:14
  • 1
    It looks like you're trying to use the tags as a "release notes" document; Instead, you can keep a release notes doc in the repository, and update it with each (relevant) commit. Or, easier, just use git-log.
    – aviv
    Commented May 29, 2013 at 6:56

1 Answer 1

Reset to default
4

A tag should be created for significant commits — something meaningful. This is a bit open-ended, but most times a tag corresponds to a release, and this is why you tend to see tags like v1.3.5.X or 1.4.0.X. You should not be creating release tags for commits that are not actually releases.

Comments on release tags should give you a short description of what is included in that release, like an "elevator pitch" or "executive summary." You can optionally include a link to the release notes for that release, but this can be risky if your project ever changes its URL. This can happen frequently with open source projects.

If the repository has a text file for the release notes, then your tag comments can refer people to that text file, which is a much more stable way to refer to this information.

An example release tag comment with new features and bug fixes:

New features and bug fixes, including a high priority security fix for issue #285.

See ReleaseNotes.md for more information.

An example release tag comment with just bug fixes:

Maintenance release to resolve defects with feature A (see ReleaseNotes.md)

Another example release tag comment outlining new features:

Added comments to blog posts and new content moderation features

Short and sweet.

You can tag other significant commits that do not correspond to a release. If the tag name is descriptive enough, then don't add a comment:

  • before_framework_migration
  • js_to_typescript_rewrite

If the tag name is not sufficient to explain why the tag exists, then add whatever comments are required in order to give team members come context. For example, let's say you created the before_framework_migration tag and added comments:

Last good commit before starting migration from .NET Framework to .NET Core

We are expected to deliver new features along with this framework upgrade prior to the November reporting deadline. See Epic 2986 (https://example.com/workItems/2986) for more info.

Improve this answer

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.