Changes between Version 8 and Version 9 of Submitting/General

Timestamp:

Jun 27, 2014, 7:35:15 AM (10 years ago)

Author:

wenzeslaus

Comment:

add info about Commit Messages (wiki:Submitting/General#Commitmessages)

Submitting/General

@@ -9 +9 @@
 
 Such diffs should be made from the top-level directory, e.g. `svn diff display/d.vect/main.c`; that way, the diff will include the pathname rather than just an ambiguous `main.c`.
+
+=== Commit messages ===
+
+General pattern:
+
+{{{
+module or library: description (possible Trac ticket, merge commit or related commit)
+}}}
+
+Examples (of single line commit messages):
+
+{{{
+r.to.vect: corrected x in the crowded message
+g.mremove: Changed the interface to that of g.mlist and added exclude= (ticket #2228)
+libraster: Added raster name and row info to get/put_row error messages
+vlib/pg: column check must be case-insensitive 
+wxGUI/lmgr: add measuring of distances also to Layer Manager
+wxGUI: workaround for not visible toolbars on Mac with wxPython 3
+}}}
+
+Include ticket using hash mark and ticket number, e.g. `#2228`, and another commit (revision) using letter r and revision number, e.g. `r60975`. This will allow Trac (and perhaps other systems) to create a link to the ticket or commit (or revision). However, do not rely on this and always include the information about what and why the commit is changing and how (consider browsing commit messages in command line). 
+
+It is possible and allowed to do multiline commit messages but you should consider the following. First, multiline commit messages should be used to provide further details about the commit. They should not be used to describe large changes of code. Instead, these large changes should be split into the separate commits with shorted commit messages. Note that this not only simplifies writing of good, simple and readable commit messages but it also makes code review and regression testing easier. Second, if you have a lot to say about the commit you should perhaps include this in the comments or documentation (you can refer there to tickets or other commits too in the same way as in commit messages, although they will not be automatically linked).
+
+Write the commit messages in the way that they can be used to create/update change logs, wiki:Release pages and news in general.
+
+Don't include your name (or id) to commit message, this is stored separately and automatically. However, if you are committing someone's code (e.g. path) or you are writing the code together with someone, include his or her name.
+
+Include the module, library or component name as a prefix separated by colon, e.g. `libraster:`. You don't have to include file names in the commit message, they are managed by SVN itself.
+
+If you are not sure if your style is correct, ask on mailing list.
+
+Some bad examples (of single line commit messages):
+{{{
+wxGUI/render: attempt to fix #560
+(missing information what is #560 and how we are trying to fix it)
+
+Add tests for Table and Columns classes
+(we don't know where the classes belongs to, prefix pygrass: or pythonlib/pygrass would tell us in this case)
+
+fix bug introduced in r60216
+(missing information how the bug was fixed and which bug it was)
+
+fix r60216 (i18n)
+(it should probably say something like: wxGUI: fix insufficient handling of i18n (introduced in r60216))
+
+libraster:Added raster name and row info to get/put_row error messages
+(missing space after colon)
+}}}
+
 
 === SVN Properties ===