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
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:
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.