Difference between revisions of "Committing policies"

From Gramps
Jump to: navigation, search
(Log Messages)
(Log messages)
(31 intermediate revisions by 8 users not shown)
Line 1: Line 1:
==Log Messages==
+
==Branches==
Every commit to Subversion 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:
+
* Only new features should be committed to the master branch.
 +
* Only bug fixes should be committed to maintenance branches.
 +
* The current maintenance branch should be merged regularly into the master branch.
 +
* Translations may be committed to any active branch.
  
* Messages should attempt to describe how the change affects the functionality from the user's perspective.
+
==Merging==
* It is not necessary to describe minute details about the change nor the files that are affected because that information is already stored by Subversion.
+
* Most changes should be squashed and fast-forwarded.
* If the commit fixes a bug on the [http://bugs.gramps-project.org bug tracker], the log message shall include the bug ID and summary from the tracker.
+
* Major new features should be merged no-ff to maintain their development identity.
* When committing contributed code, the log message shall list the contributor's name and email.
+
* This applies both to pull requests and to work by developers with write permission to the repository.
  
You can see the last changes with the svn log command, an example usage of this command:
+
==Pull requests==
svn log -r BASE:10240 | head -n 40
+
* Pull requests must be code-reviewed and tested by a developer.
Change 10240 to a more recent version to have the command take less time.
+
* 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.
  
You can also limit the number of entries shown by passing in the '''--limit''' flag to svn:
+
==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:
  
svn log --limit 5
+
===Summary===
 +
* The first line of the commit message should consist of a short summary of the change.
 +
* Maximum 70 characters.
  
==Adding New Files==
+
===Description===
All the files with the translatable strings '''must''' be listed in the po/POTFILES.in file. This means that most new files must have their names added to that file.
+
* The description should be separated from the summary by a single blank line.
 +
* 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 :-(
  
All the files that need to be released '''must''' be listed in the Makefile.am in the same directory. Please remember to do this for new files that you add to SVN.
+
===Bug tracker integration===
 +
Special keywords can be used to either link to, or resolve, bug reports. They should be separated from the description by a single blank line.
  
You'll also need to set several properties for new files.  For .py files, try the following:
+
To resolve a bug or bugs use:
svn propset svn:mime-type text/plain src/somefile.py
 
svn propset svn:eol-style native src/somefile.py
 
svn propset svn:keywords 'Id' src/somefile.py
 
  
==Bugfixes In Branches==
+
* Fixes #12345
Whenever a bug is fixed in a branch, it is the committer's responsibility to make sure the fix is also committed to the trunk. This can be accomplished using one of three methods. All methods require a working copy of trunk and the branch.
+
* Fixed #12345
 +
* Resolves #12345
 +
* Resolved #12345
 +
* Fixes #12345, #67890
 +
* Fixed #12345, #67890
 +
* Resolves #12345, #67890
 +
* Resolved #12345, #67890
  
;Using svn merge
+
To link to a bug or bugs use:
The most common way to move changes between branches is by using the svn merge command. Assuming you have a working copy of trunk in ~/gramps/trunk and a working copy of the 3.0 branch in ~gramps/gramp30:
 
gramps30$ svn commit
 
gramps30$ cd ../trunk
 
trunk$ svn merge -c REVISION https://gramps.svn.sourceforge.net/svnroot/gramps/branches/gramps30
 
trunk$ svn commit
 
  
;Using svn diff
+
* Bug #12345
You can also create a patch on gramps30 branch and apply it to trunk:
+
* Issue #12345
gramps30$  svn diff -r PREV > ~/mypatch.patch
+
* Report #12345
gramps30$  cd ../trunk
+
* Bugs #12345, #67890
trunk$  patch -p0 < ~/mypatch.patch
+
* Issues #12345, #67890
 +
* Reports #12345, #67890
  
Then you may have to fix things that could not be applied due to conflicts. The patch program would mark the conflicts with the <<<<<<, ======, and >>>>>> signs. You will then need to commit your changes:
+
For this to work, either the author or committer will need to be a developer on the Mantis bug tracker. The Git name must match either the Mantis username or real name, or the Git email must match the Mantis email.
trunk$  ./svnci
 
  
;Manually
+
===Useful commands===
Make the change in the branch. Commit the change to the branch.
+
You can see the last changes with the git log command, an example usage of this command:
 +
git log --oneline
  
Make the change in trunk. Commit the change to trunk.
+
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:
  
More info: http://svnbook.red-bean.com/
+
git log -5
 +
 
 +
To credit the contributor of a patch, use:
 +
 
 +
git commit --author='A U Thor <[email protected]>'
 +
 
 +
==Adding new 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.
 +
 
 +
===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 <code>po/POTFILES.in</code> and <code>po/POTFILES.skip</code> files.
 +
 
 +
 
 +
[[Category:Developers/General]]

Revision as of 15:38, 17 June 2017

Branches

  • Only new features should be committed to the master branch.
  • Only bug fixes should be committed to maintenance branches.
  • The current maintenance branch should be merged regularly into the master branch.
  • Translations may be committed to any active branch.

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:

Summary

  • The first line of the commit message should consist of a short summary of the change.
  • Maximum 70 characters.

Description

  • The description should be separated from the summary by a single blank line.
  • 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 :-(

Bug tracker integration

Special keywords can be used to either link to, or resolve, bug reports. They should be separated from the description by a single blank line.

To resolve a bug or bugs use:

  • Fixes #12345
  • Fixed #12345
  • Resolves #12345
  • Resolved #12345
  • Fixes #12345, #67890
  • Fixed #12345, #67890
  • Resolves #12345, #67890
  • Resolved #12345, #67890

To link to a bug or bugs use:

  • Bug #12345
  • Issue #12345
  • Report #12345
  • Bugs #12345, #67890
  • Issues #12345, #67890
  • Reports #12345, #67890

For this to work, either the author or committer will need to be a developer on the Mantis bug tracker. The Git name must match either the Mantis username or real name, or the Git email must match the Mantis email.

Useful commands

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 --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.