| 162 | |
| 163 | == Commit Messages == |
| 164 | {{{ |
| 165 | #!comment |
| 166 | This should probably have it's own page but putting here for now. |
| 167 | }}} |
| 168 | Mainly based on [http://git-scm.com/book/en/Distributed-Git-Contributing-to-a-Project#Commit-Guidelines git commit guidelines]. |
| 169 | |
| 170 | Example commit message: |
| 171 | |
| 172 | {{{ |
| 173 | Short summary of changes (preferably 50 characters or less) |
| 174 | |
| 175 | More detailed explanatory text, if necessary. Wrap it to about 72 |
| 176 | characters or so. The first line can be considered as the subject of an |
| 177 | email and the rest of the text as the body. The blank line separating |
| 178 | the summary from the body is critical, unless you omit the body entirely. |
| 179 | |
| 180 | Further paragraphs come after blank lines. |
| 181 | |
| 182 | - Bullet points are okay, too |
| 183 | |
| 184 | - Typically a hyphen or asterisk is used for the bullet, preceded by a |
| 185 | single space, with blank lines in between, but conventions vary here |
| 186 | }}} |
| 187 | |
| 188 | A general guideline on writing a good commit message is to provide information |
| 189 | that is not already provided from the commit diff, which in essence is "''the why, not the how''". |
| 190 | |
| 191 | * Explain why the change is necessary |
| 192 | |
| 193 | After reading the commit message it should should be apparent why the changes were made. |
| 194 | |
| 195 | * Explain how the issue is adressed in broad terms |
| 196 | |
| 197 | It is not necessary to explain how the changes are made in detail as that can be seen from the commit diff. |
| 198 | |
| 199 | |
| 200 | === Tags / Labels === |
| 201 | To differentiate commit changes at a glance, the subject of commits for specific components should be prefixed with relevant tags/labels, such as |
| 202 | |
| 203 | ''Core'', ''WebUI'', ''GTKUI'', ''Tests'', ''win32'', ''Packaging'', ''Console'', ''Blocklist'' etc. |
| 204 | |
| 205 | {{{[GTKUI] Make Add Dialog torrent name editable}}} |
| 206 | |
| 207 | If the commit fix/closes a ticket, include the number: |
| 208 | |
| 209 | {{{[#1001] Add support for magnet uris}}} |
| 210 | |
| 211 | A limited number of tags may be combined, such as |
| 212 | |
| 213 | {{{[#1002] [GTKUI] Fix the files tab context menu not being displayed}}} |
| 214 | |
| 215 | {{{[#2250] [Core] [GTKUI] Added method remove_torrents to core}}} |
| 216 | |
| 217 | |