Difference between revisions of "Brief introduction to Git"
(Move "Committing policies" line) |
(→Types of branches: Remove the "sandbox" branch type: Not applicable to git.) |
||
Line 67: | Line 67: | ||
* ''geps'' - These are meant for development of [[Portal:Enhancement_Proposals|Gramps Enhancement Proposals]]. Most of the time GEPS are developed in the ''master'' branch. Occassionally a GEP will require extensive reworking or long periods when the code base is ususable. In these cases a branch in ''geps'' can be used as a temporary development area. Once the hard work is done the change should be merged into the trunk and the ''geps'' branch should be removed. ''geps'' branches should follow the naming convention ''gep-<###>-<descriptive text>'' e.g. ''gep-013-server''. Please read the [[#Working with development branches]] section for help with managing these branches. | * ''geps'' - These are meant for development of [[Portal:Enhancement_Proposals|Gramps Enhancement Proposals]]. Most of the time GEPS are developed in the ''master'' branch. Occassionally a GEP will require extensive reworking or long periods when the code base is ususable. In these cases a branch in ''geps'' can be used as a temporary development area. Once the hard work is done the change should be merged into the trunk and the ''geps'' branch should be removed. ''geps'' branches should follow the naming convention ''gep-<###>-<descriptive text>'' e.g. ''gep-013-server''. Please read the [[#Working with development branches]] section for help with managing these branches. | ||
− | |||
− | |||
Tags are created for each Gramps release. The first two digits of the Gramps version number are reserved to indicate the maintenance branch the code came from. The last digit indicates the revision from that maintenance branch. For example, 3.0.4 would indicate the 5th release from the 3.0 branch (3.0.0, 3.0.1, 3.0.2, 3.0.3, 3.0.4). | Tags are created for each Gramps release. The first two digits of the Gramps version number are reserved to indicate the maintenance branch the code came from. The last digit indicates the revision from that maintenance branch. For example, 3.0.4 would indicate the 5th release from the 3.0 branch (3.0.0, 3.0.1, 3.0.2, 3.0.3, 3.0.4). |
Revision as of 23:00, 7 November 2013
The development source code of Gramps is stored in the Git repository at SourceForge.
This helps synchronizing changes from various developers, tracking changes, managing releases, etc. If you are reading this, you probably want to do one of two things with Git: either download the latest source or the development version, or else upload your changes (if you have write access to the repository) or make a patchfile (if you don't have write access).
Contents
Obtaining a copy of the Gramps repository
Install Git on your system.
- Debian/Ubuntu:
apt-get install git
- Fedora:
yum install git-core
Git includes your name and email address in commits. To configure them, use the following commands:
git config --global user.name "John Smith" git config --global user.email [email protected]
To obtain a copy of the Gramps repository, type the following in the command line if you don't have a sourceforge account:
git clone http://git.code.sf.net/p/gramps/source Gramps
You should see the downloading progress reported in your terminal.
If you have a SourceForge account, use ssh instead:
git clone ssh://<username>@git.code.sf.net/p/gramps/source Gramps
You will need a SSH Key in order to authenticate using this method.
Basic Work Flow
The basic work flow after you've checked out the repository is update, develop, commit, update again, push. To update the current branch, run
git pull --rebase
As a general rule always use git pull --rebase to avoid creating unnecessary merge commits. Note that one must have no uncommitted edits when running git pull.
To commit your changes locally, use the following command:
git commit
Which will bring up the default $EDITOR to create a commit message. If you are fixing a bug, the first line of the commit message should be the bug number and title, otherwise a brief statement of purpose. Skip a line and describe what you did.
- All developers should read Gramps Committing policies
If the commit is a minor change that can be described entirely in the subject, you can instead use:
git commit -am "message describing the nature of the change"
Try to keep your commits digestible and understandable. A large changeset can be broken into several commits that "tell a story" about how the changeset moves the program from its old behavior to its new one.
To push your changes to the Gramps repository, you need to have cloned the Gramps source code with ssh, and have push access to the Gramps repository (the Gramps admins can give you this, Brian Matherly or Benny Malengier). First update again to make sure that you can fast-forward the repository, then push:
git pull --rebase git push
Since uploading is a potentially dangerous operation, most people do not obtain write access to the git repository. In this case, create a new bug on the bug tracker and attach a patch to it. See the make a patchfile section for details.
If someone else has made changes that interfere with yours, you will get a conflict error when you pull. You will have to resolve that conflict and re-commit (you can use git commit --amend if it affects only the last unpushed commit) before git will push successfully.
- Also see: Getting started with Gramps Trunk.
Types of branches
When you clone the Gramps repository, a branch called master will be created for you. This contains the latest development version of Gramps. Gramps maintains different branches in several categories:
- master - There is only one master branch. All new feature development happens in the master branch. New releases never come from the master branch.
- maintenance - There are many maintenance branches. A maintenance branch is created from the master branch when all the features for a release are complete. New features are not committed to maintenance branches. Releases only come from maintenance branches. The purpose of maintenance branches is to allow the line of code to stabilize while new features are added in the master branch.
- geps - These are meant for development of Gramps Enhancement Proposals. Most of the time GEPS are developed in the master branch. Occassionally a GEP will require extensive reworking or long periods when the code base is ususable. In these cases a branch in geps can be used as a temporary development area. Once the hard work is done the change should be merged into the trunk and the geps branch should be removed. geps branches should follow the naming convention gep-<###>-<descriptive text> e.g. gep-013-server. Please read the #Working with development branches section for help with managing these branches.
Tags are created for each Gramps release. The first two digits of the Gramps version number are reserved to indicate the maintenance branch the code came from. The last digit indicates the revision from that maintenance branch. For example, 3.0.4 would indicate the 5th release from the 3.0 branch (3.0.0, 3.0.1, 3.0.2, 3.0.3, 3.0.4).
Here is a hypothetical example: Imagine that the current version of Gramps is 8.3.2. A new series of features has been added in the master branch and are ready for release. A new maintenance branch is created from the master branch named 8.4 (or possibly 9.0 depending on the nature of the new features). New features continue to be added in the master branch that will not be included in the 8.4 series of releases, but will be included in the 8.5 series. Bug fixes continue to occur in the 8.4 branch until the code is deemed worthy of release. At that time, a release is tagged from the 8.4 maintenance branch and named 8.4.0. Some time after the release of 8.4.0, some bugs are found and fixed in the 8.4 maintenance branch. Those bug fixes are released as 8.4.1.
Stable version
There are several versions of the Gramps source code in Git. The development branch for small changes and bug fixes is maintenance/gramps52.
By default, the remote server you cloned the Gramps repository from is called origin.
To see a list of branches on the server, type:
git show remote origin
To create a local branch which tracks a branch on the server, use:
git checkout -b gramps40 origin/maintenance/gramps40
This is known as a "tracking" branch.
To list the available branches, type:
git branch
The current branch is marked by an asterisk.
To switch to another branch, type:
git checkout <branch>
Where for bugs?
The bug tracker has in the right top angle different projects. Choose project trunk and submit an issue.
Making a patchfile
If you do not have push access to the repository, you can make a patchfile with your changes. This is a text file which can then be sent by email to somebody, or posted/uploaded to the bug tracker (against a bug you are fixing or a feature request which you are solving for instance), etc...
These instructions tell how to make a patchfile against the master branch, so that your changes are added to the next major release of Gramps. (To make a patchfile against a branch the process is similar, with some slight changes.)
First create a new branch to work in:
git checkout -b fix
Then use your favorite editor to change whatever file(s) you want. Add the files you have changed to the staging area and commit them.
Obtain the latest changes from the server.
git checkout master git pull --rebase
Next, rebase your fix again the master branch. This will ensure that your patch will apply cleanly.
git rebase master fix
This will leave you in the fix branch.
Finally, create a patchfile, using:
git format-patch master --stdout > fix.patch
You now have a patchfile that can be sent by email, or attached to a bug report. The patch can be applied using the 'git apply' command.
Working with development branches
Creating branches with Git is quick and easy.
Here is a quick crib sheet:
Creating a branch
To create a branch from the master branch:
git checkout master git branch gep-014-fab-feature
To make this branch available on the server use:
git push origin gep-014-fab-feature
Merging changes from the branch back into the master branch
When you are ready to merge your changes back into the master branch:
git checkout master git merge gep-014-fab-feature git push
Removing branches
It is important that branches are removed once they have been merged into the trunk or have been abandoned. To remove a branch:
git branch -d gep-014-fab-feature
To remove a branch from the server, use:
git push origin :gep-014-fab-feature
The developers reserve the right to remove branches that have been dormant for more than 1 year.
Applying a fix to another branch
Workflow
Before switching to another branch it is useful to remove untracked files created by the build process. You can do this with the following command:
git clean -dxf
Useful Tips
Getting help
Git has excellent man pages. You can view the manual page for a Git command, by using one of the following:
git help <verb> git <verb> --help man git-<verb>
For example, to get help on the 'git log' command, type:
git help log
Some procedural recommendations
- Always do 'git pull' before pushing changes to the server. If necessary get advice about handling conflicts.
- Always do 'git status' and look for staged files that are unexpected or unintended. This is a *very important* sanity check.
- And here are a couple of incidental suggestions
- avoid grouping unrelated changes; better to divide into separate commits for the following reasons: a better log entry; easier troubleshooting/reverting. (and probably more).
- similar to above, it may be better to make small incremental changes than one big one (if possible). Interim changes should not introduce breakage, of course.
- logs are important -- please give some thought to the log message. All developers should read the Committing policies.
Browse Git
An alternative to the command line tools to view the Git repository is the online interface.
git2cl
The Gramps project does not keep a ChangeLog file under source control. All change history is captured by git automatically when it is committed. A ChangeLog file is generated from the git commit logs before each release using git2cl. Developers should take care to make useful commit log messages when committing changes to git. Please read the Committing policies for details.
How to use git2cl
Starting with Gramps 3.0.0, we no longer have a ChangeLog file.
Instead, the list of changes is generated automatically using the standard git2cl script.
Note that git2cl is not included in the base installation of Git. With a Debian-based distro such as Ubuntu, you can get git2cl as follows:
sudo apt-get install git2cl
There typically are two ChangeLog files needed for releases; one in the main directory, and one in the po directory. You can generate these files with the following commands:
git log gramps-4.0.1.. --pretty --numstat --summary --no-merges | git2cl > ChangeLog git log gramps-4.0.1.. --pretty --numstat --summary --no-merges -- po | git2cl > po/ChangeLog