Difference between revisions of "Committing policies"

From Gramps
Jump to: navigation, search
(Log messages)
(6 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 +
==Merging==
 +
* Most changes should be squashed and fast-forwarded.
 +
* Major new features should be merged no-ff to maintain their development identity.
 +
* This applies both to pull requests and to work by developers with write permission to the repository.
 +
 +
==Pull requests==
 +
* Pull requests must be code-reviewed and tested by a developer.
 +
* PR authors should not be assumed to be Git experts, so it's up to the Gramps developer doing the merge to ensure that the PR is clean and won’t make a mess of history.
 +
* The GitHub "Squash and merge" button can be used for most small changes.
 +
* A no-ff merge outside of GitHub should be used when it is useful to keep the commit history.
 +
* Bug fixes must be committed to the current stable branch and cherry-picked to master.
 +
* Only new features should be committed to master directly.
 +
 
==Log messages==
 
==Log messages==
 
Every commit to Git must be accompanied by a log message. These messages will be generated into a ChangeLog when a release is made and should conform to the following guidelines:
 
Every commit to Git must be accompanied by a log message. These messages will be generated into a ChangeLog when a release is made and should conform to the following guidelines:
  
* The first line of the commit message should consist of a short summary of the change.
+
* The first line of the commit message should consist of a short summary of the change.  Maximum 70 characters.
 
* If the commit fixes a bug on the [http://bugs.gramps-project.org bug tracker], the summary shall include the bug ID and summary from the tracker.
 
* If the commit fixes a bug on the [http://bugs.gramps-project.org bug tracker], the summary shall include the bug ID and summary from the tracker.
 
* The summary should be separated from the body of the message by a single blank line.
 
* The summary should be separated from the body of the message by a single blank line.
Line 9: Line 22:
 
* It is not necessary to describe minute details about the change nor the files that are affected because that information is already stored by Git and can be viewed with "git diff".
 
* It is not necessary to describe minute details about the change nor the files that are affected because that information is already stored by Git and can be viewed with "git diff".
 
* When committing contributed code, the author should be credited using the --author option.
 
* When committing contributed code, the author should be credited using the --author option.
* If you want to refer to another commit, use the commit short hash (6 hexa digits) in square brackets. It will automatically be expanded to a hyperlink by the SourceForge web interface to the repository, e.g.: [http://sourceforge.net/p/gramps/source/ci/d8acf8e875a06cf89b2cc4d59ed63730539244af/ [d8acf8]]. Note: the default short hash in git is 7 hexa digits (as produced by `git log --oneline' command), and that WILL NOT WORK with auto-hyperlinking of sourceforge :-(
+
* If you want to refer to another commit, use the full commit hash. It will automatically be converted into a hyperlink by the GitHub web interface. Note: a 6 hexa digit hash enclosed in brackets WILL NOT WORK with GitHub auto-hyperlinking :-(
  
 
You can see the last changes with the git log command, an example usage of this command:
 
You can see the last changes with the git log command, an example usage of this command:
 
  git log --oneline
 
  git log --oneline
  
You can also limit the number of entries shown by passing in the '''-n''' flag to svn. Add '''--stat''' to see the files affected by the commit:
+
You can also limit the number of entries shown by passing in the '''-n''' flag to git. Add '''--stat''' to see the files affected by the commit:
  
 
  git log -5
 
  git log -5
Line 23: Line 36:
  
 
==Adding new files==
 
==Adding new files==
All the files with the translatable strings '''must''' be listed in the po/POTFILES.in or po/POTFILES.skip files. This means that most new files must have their names added to these files.
+
All the files with the translatable strings '''must''' be listed in the <code>po/POTFILES.in</code> or <code>po/POTFILES.skip</code> files. This means that most new files must have their names added to these files.
  
 
Please remember to do this for new files that you add to Git.
 
Please remember to do this for new files that you add to Git.
Line 30: Line 43:
  
 
You can make a test on a local copy:
 
You can make a test on a local copy:
./autogen.sh
+
  PYTHONPATH=../../gramps python po/test/po_test.py
  PYTHONPATH=../../trunk/src python po/test/po_test.py
 
  
 
where ../.. is the path to your local copy
 
where ../.. is the path to your local copy
  
 
==Removing files==
 
==Removing files==
Remember to remove references to the file from the po/POTFILES.in and po/POTFILES.skip files.
+
Remember to remove references to the file from the <code>po/POTFILES.in</code> and <code>po/POTFILES.skip</code> files.
  
 
==Bugfixes in branches==
 
==Bugfixes in branches==
Whenever a bug is fixed in a maintenance branch, it is the committer's responsibility to make sure the fix is also committed to the master branch. See the [[Brief introduction to Git#Applying a fix to another branch|Brief introduction to Git]] for details.
+
Whenever a bug is fixed in a maintenance branch, it is the committers responsibility to make sure the fix is also committed to the master branch. See the [[Brief introduction to Git#Applying a fix to another branch|Brief introduction to Git]] for details.
  
 
[[Category:Developers/General]]
 
[[Category:Developers/General]]

Revision as of 04:39, 12 April 2017

Merging

  • Most changes should be squashed and fast-forwarded.
  • Major new features should be merged no-ff to maintain their development identity.
  • This applies both to pull requests and to work by developers with write permission to the repository.

Pull requests

  • Pull requests must be code-reviewed and tested by a developer.
  • PR authors should not be assumed to be Git experts, so it's up to the Gramps developer doing the merge to ensure that the PR is clean and won’t make a mess of history.
  • The GitHub "Squash and merge" button can be used for most small changes.
  • A no-ff merge outside of GitHub should be used when it is useful to keep the commit history.
  • Bug fixes must be committed to the current stable branch and cherry-picked to master.
  • Only new features should be committed to master directly.

Log messages

Every commit to Git must be accompanied by a log message. These messages will be generated into a ChangeLog when a release is made and should conform to the following guidelines:

  • The first line of the commit message should consist of a short summary of the change. Maximum 70 characters.
  • If the commit fixes a bug on the bug tracker, the summary shall include the bug ID and summary from the tracker.
  • The summary should be separated from the body of the message by a single blank line.
  • Messages should attempt to describe how the change affects the functionality from the user's perspective.
  • Use complete sentences when possible.
  • It is not necessary to describe minute details about the change nor the files that are affected because that information is already stored by Git and can be viewed with "git diff".
  • When committing contributed code, the author should be credited using the --author option.
  • If you want to refer to another commit, use the full commit hash. It will automatically be converted into a hyperlink by the GitHub web interface. Note: a 6 hexa digit hash enclosed in brackets WILL NOT WORK with GitHub auto-hyperlinking :-(

You can see the last changes with the git log command, an example usage of this command:

git log --oneline

You can also limit the number of entries shown by passing in the -n flag to git. Add --stat to see the files affected by the commit:

git log -5

To credit the contributor of a patch, use:

git commit -m 'Commit message' --author='A U Thor <[email protected]>'

Adding new files

All the files with the translatable strings must be listed in the po/POTFILES.in or po/POTFILES.skip files. This means that most new files must have their names added to these files.

Please remember to do this for new files that you add to Git.

Check

You can make a test on a local copy:

PYTHONPATH=../../gramps python po/test/po_test.py

where ../.. is the path to your local copy

Removing files

Remember to remove references to the file from the po/POTFILES.in and po/POTFILES.skip files.

Bugfixes in branches

Whenever a bug is fixed in a maintenance branch, it is the committers responsibility to make sure the fix is also committed to the master branch. See the Brief introduction to Git for details.