Commit comments guidelines

From Post-Apocalyptic RPG wiki

Jump to: navigation, search

Established workflow.png This article covers an established workflow.

Established workflows have been discussed among and agreed upon by the development department(s). They should serve as documentation how these workflows are successfully utilized in the project.


The following are guidelines to help our SVN comments remain consistent as well as make the commit log a helpful tool for tracking changes. It is desirable that all project members use the formats given below when making commits.

Contents

If a Commit Has an Associated Trac Ticket

Ticket #<num>: Patch by <author>:
 * <author's comment #1>
 * <author's comment #2>
 * etc.
 * <trac command>

If a Commit Does Not Have an Associated Trac Ticket

Patch by <author>:
 * <author's comment #1>
 * <author's comment #2>
 * etc.
 * <trac command>

Trac syntax

  • <num> is the associated Trac ticket number
  • <author> is the name of author of the change being made. The name should be the author's registered forum name whenever possible. May not always be the same as the person committing the change. If you're commiting a sent in patch that you've modified to a larger extend, please name both the original author of the patch as yourself as well!
  • <author's comments> is free form text describing the change made. Whenever possible these comments should come directly from the author, not the person who commits the change.
  • <trac command> is an optional string that can automatically close or comment a ticket. See list of Trac commands below.

This format will display comments as a list when viewed as a changeset in Trac. An example is here. The "Message:" section contains the comments. Note that all commits are logged in Trac as changesets even if they do not have an associated ticket.

Optional Trac Commands

  • fixes - This command will set the status of a ticket to closed and the resolution to fixed.
  • comment - This command will add the entire commit comment as a comment to the given ticket.

Syntax:

fixes[s:trac, t:<num>]
comment[s:trac, t:<num>]

Where:

  • <num> is the ticket number effected by the command given.

These commands can be added to the end of your comments to automatically change properties of a Trac ticket. Multiple commands can be given. The official help text for these commands can be found at here (you need to be logged into your codesion.com account to view the article). If you use fixes, the comment will also be added to trac and the ticket will be closed.

For code changes

Whenever possible the author's comments should include the name of Classes modified as well as a description of modified logic. The author's comments should be as descriptive as possible.

Unacceptable comments include:

  • "Fixed bug"
  • "Fixed bug described in Ticket"
  • "No comment"
Personal tools