Difference between revisions of "Commit guidelines"

From Navit's Wiki
Jump to: navigation, search
(Format of the commit log)
 
(8 intermediate revisions by 7 users not shown)
Line 1: Line 1:
Here are the current guidelines if you want to commit something :
+
{{warning|1='''The content of this document has been moved to:''' https://navit.readthedocs.io/en/trunk/development/commit_guidelines.html . It is only kept here for archiving purposes.}}
 +
 
 +
 
 +
Here are the current guidelines if you want to commit something.
 +
Please also read [[Programming guidelines]]
  
 
==='Core' components changes===
 
==='Core' components changes===
Do not modify a 'core' component without discussing it first with the project leads.
+
Do not modify a 'core' component without discussing it first with the project leads (see [[team]]).
  
 
Core components include data structures, configuration handling. If you are unsure, just ask.
 
Core components include data structures, configuration handling. If you are unsure, just ask.
  
===Commit per file===
+
===Commit per feature===
Avoid committing a whole folder, especially navit's sourcecode root. It would almost always update timestamps in the translations files, and generate a lot of useless commit log entries. So, as a general guideline, commit each needed file namely.
+
When committing, try to have one commit per feature (or per meaningful part of a larger feature). The goal is to always have working code; at least make sure each commit leaves the repository in a compilable state.
 +
 
 +
Also avoid putting multiple, independent changes into one commit.
 +
Thus if you have multiple, independent changes in your local working copy, avoid committing a whole folder at once, especially Navit's Sourcecode root. Instead, explicitly select the files for each commit.
  
 
===Format of the commit log===
 
===Format of the commit log===
Since we are too lazy to maintain a changelog, we have a script which parses the commit logs and generate a changelog for us.
+
Since we are too lazy to maintain a Changelog, we have a script which parses the commit logs and generate a Changelog for us.
  
 
We have agreed about using the following syntax :
 
We have agreed about using the following syntax :
  <Action>:<component>:<log message>[|Optionnal comments]
+
  <Action>:<component>:<log message>[|Optional comments]
  
 
Examples :
 
Examples :
Line 20: Line 27:
  
 
Action can be something like:  
 
Action can be something like:  
* Fix
+
* Fix (bug fix)
* Add
+
* Add (new feature)
 
* Patch
 
* Patch
 +
* Refactoring (does not change behavior of the program)
 +
 
It allows the changes to be sorted by categories
 
It allows the changes to be sorted by categories
  
Component is the component field in the [http://trac.navit-project.org bug tracker].
+
Component is the component field in the [[trac]].
 
The most common are :
 
The most common are :
 
* core
 
* core
Line 37: Line 46:
 
...
 
...
  
The comment part is optionnal. Useful for when applying a patch for example, and giving credits.
+
The comment part is optional. Useful for when applying a patch for example, and giving credits.
 
The part after | will not appear in the wiki.
 
The part after | will not appear in the wiki.
  
Line 45: Line 54:
  
 
[[Category:Development]]
 
[[Category:Development]]
 +
[[Category:Social]]

Latest revision as of 01:20, 5 September 2019


Here are the current guidelines if you want to commit something. Please also read Programming guidelines

'Core' components changes[edit]

Do not modify a 'core' component without discussing it first with the project leads (see team).

Core components include data structures, configuration handling. If you are unsure, just ask.

Commit per feature[edit]

When committing, try to have one commit per feature (or per meaningful part of a larger feature). The goal is to always have working code; at least make sure each commit leaves the repository in a compilable state.

Also avoid putting multiple, independent changes into one commit. Thus if you have multiple, independent changes in your local working copy, avoid committing a whole folder at once, especially Navit's Sourcecode root. Instead, explicitly select the files for each commit.

Format of the commit log[edit]

Since we are too lazy to maintain a Changelog, we have a script which parses the commit logs and generate a Changelog for us.

We have agreed about using the following syntax :

<Action>:<component>:<log message>[|Optional comments]

Examples :

Fix:Core:Fixed nasty bug in ticket #134
Fix:GTK:Fixed nasty bug about destination button|Thanks someguy for the patch!

Action can be something like:

  • Fix (bug fix)
  • Add (new feature)
  • Patch
  • Refactoring (does not change behavior of the program)

It allows the changes to be sorted by categories

Component is the component field in the trac. The most common are :

  • core
  • gui/gtk
  • gui/internal
  • graphics/gtk
  • graphics/qt_qpainter
  • graphics/opengl
  • mapdriver
  • tools

...

The comment part is optional. Useful for when applying a patch for example, and giving credits. The part after | will not appear in the wiki.


About the log message, it's up to you :)