Commit cheat sheet

Revision as of 10:30, 5 April 2011 by David Mudrak (talk | contribs) (Initial version of the page)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

This is a list to check before you submit a patch for inclusion into Moodle.

Split your work into a logical set of patches 
Keep in mind that your commits will be reviewed before they are accepted. If the patch does one clear thing and does it well, the review process is fun. Git allows you to prepare patches on your branch into a sequence of logical steps. For example, when changing some API, divide the change into two steps. In the first commit, change the API. In the following commit, change all places that use the API.
Provide clear commit message 
Consider the commit message as an email for the developer who would explore the change in the future. We recommend to follow common Git guidelines for formatting. Include the MDL issue number and eventually the area/component at the beginning of the subject line.
   MDL-xxxxx code area: short description of the patch
The subject line is followed by an empty line and then a paragraph or two of a longer description follows. This longer description is useful for issues with longer history of comments in the linked MDL so that it summarizes the patch without the need to go through the whole discussion.
Obviously, avoid messages like "as agreed in the chat" as they will become useless after a relatively short time.
Most of Git tools are optimised for this format and they can display the log of commits best then.
Retain the authorship of the patch 
If the patch was submitted by someone else - for example a community member who published it in the tracker or in a forum - use the --author parameter.
Make sure that your real name and email are recorded in patch 
We use real names written in capital letters like "John Smith". Please do not use names like "john smith", "John S", "johnny7887". If you use --author parameter, apply the same rules for the name of the author. See almost any Git tutorial on how to set your name and email in the global Git configuration.
If you change the identifier of a string or split a string into two forks, provide a script for AMOS in the commit message 
Since Moodle 2.0, the translations are kept on separated branches again. The AMOS plugin at tracks the changes in string files and automatically records modifications, additions and removals of strings. Therefore strings can be re-worded freely on stable branches and should be removed from the master branch if they are not needed any more.
If you change the identifier of the string (that is the key in the $string array), move the string from one file to another or you are introducing a new string as a copy of some current one, you should provide instructions for AMOS so that the action can be applied in all language packs. That will save valuable translators' time. Instructions for AMOS are being put into the commit message of a commit that modifies the original English string files. The commit message containing such a script may look like this:
   MDL-xxxxx code area: short description of the patch
It is recommended to leave a blank line between the commit message and the script block.
AMOS BEGIN MOV [configfoobar,core_admin],[foobar_desc,core_admin] CPY [submission,mod_assignment],[submission,mod_workshop] AMOS END
See Languages/AMOS#AMOS_script for more details of the syntax. See the log history real examples of usage.