Jump to: navigation, search

Brief introduction to SVN

4,940 bytes added, 05:12, 22 February 2021
no edit summary
{{man warn|{{man menu|Development has moved to using Git}} please read a [[Brief introduction to Git]]|The development source code of GRAMPS is Gramps '''was''' stored in the SVN (Subversion) repository at sourceforge .}} ;<s>[]</s>. No longer available see Github for code.  This helps synchronizing changes from various developers, tracking changes, managing releases, etc. If you are reading this, you probablywant to do one of two thingswith SVN: either download the latest source or the development version,or else upload your changes (if you have write access to the repository)or [[Brief_introduction_to_SVN#Making_a_patchfile|make a patchfile ]] (if you don't have write access). * All developers should read Gramps [[Committing policies]]
== Types of branches ==
There are four kinds of branches in the Subversion Repository:
* ''trunk'' - There is only one trunk. All new feature development happens in the trunk. New releases never come from the trunk. The trunk for GRAMPS Gramps can be found here:
* ''maintenance'' - There are many maintenance branches. A maintenance branch is created from the trunk when all the features for a release are complete. New features are not committed to maintenance branch. 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 trunk. Maintenance branches can be found here:
* ''geps'' - These are meant for development of [[Portal:Enhancement_Proposals|Gramps Enhancement Proposals]]. Most of the time GEPS are developed in the ''trunk''. Occassionally Occasionally a GEP will require extensive reworking or long periods when the code base is ususableunusable. 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. ''greps'' 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.
* ''sandbox'' - These are meant for experimentation purposes. If you want to explore some ideas or try out some changes that would break the ''trunk'' or prototype something that has not made it to a GEP you can create a ''sandbox'' branch. These should be short lived. As soon as you have finished please remove the branch. We reserve the right to remove any ''sandbox'' branch that has not been touched for 12 months. ''sandbox'' branches should use the following naming convention ''<username>-<descriptive text>'' e.g. ''hippy-prototype-rss-idea''. Please read the [[#Working with development branches]] section for help with managing these branches.
Release tags are created in the ''tags'' directory. The first two digits of the GRAMPS 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 Gramps is 8.3.2. A new series of features has been added in trunk and are ready for release. A new maintenance branch is created from trunk named 8.4 (or possibly 9.0 depending on the nature of the new features). New features continue to be added in trunk 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 ==
* To download the source to a ~/gramps{{stable_branch}} gramps41 directory, you can use two methods to access the SVN repository:
# An http frontend to gramps SVN
# SVN access
The second method requires that svn be installed on your system (Debian/Ubuntu: <code>apt-get install subversion</code>; Fedora: <code>yum install subversion</code>).
With the SVN method, type the following in the command lineif you '''don't have a sourceforge account''':  <code>svn co <nowiki></nowiki>41 gramps41</code> You should see the downloading progress reported in your terminal. If you have a sourceforge account, use https instead: <code>svn co <nowiki></nowiki>{{stable_branch}} gramps{{stable_branch}}41 gramps41</code> You will in this case be requested for your root keyring password which will store your sourceforge credentials, and next your password. If the user on your PC is not the same one as on sourceforge, leave password empty and press enter, you will then receive the option to enter a username first, and then the sourceforge password for that username.
You should see the downloading progress reported in your terminal. If you would like to update your source tree after some time, execute the following command in the top directory of the gramps{{stable_branch}} gramps41 source tree:
<code> svn update</code>
To commit your changes, you need to have checked out the gramps code with https, and have commit access to the Gramps repository (the Gramps admin can give you this, [[Contact|Brian Matherly or Benny Malengier]]). Commit happens if execute: <code>svn commit -m "message describing the nature of the change"</code> Since uploading is a potentially dangerous operation, most people do not obtain write access to the SVN repository. In this case, create a patch, and commit this on the [ ticket tracker]. You can do this in the top gramps directory as follows: <code>svn diff > mychanges.patch</code>
<code> svn commit -m "message describing A developer can apply this patch then with the nature of the change"</code>command:
Since uploading is a potentially dangerous operation, you have to explicitly obtain write access to the SVN repository from [[Contact|Brian Matherly or Benny Malengier]]<code>patch -p0 < mychanges.patch</code>
== Unstable development: "trunk" ==
:Also see: [[Getting started with GRAMPS Gramps Trunk]].
=== Obtain it===
There are several versions of the gramps code in SVN.  The development branch for small changes and bug fixes is ''gramps{{stable_branch}}gramps41'' and ''trunk'' has been created for the ongoing unstable version.  If this talk of ''branch'' and ''trunk'' sounds confusing you might like to read the list message [http://articlesourceforge.gmane.orgnet/mailarchive/gmanemessage.comp.genealogy.gramps.devel/8678 php?msg_id=19238907 explaining branch and trunk]. '''Replace in the commands here ''https'' by ''http'' if you do not have a sourceforge account.
To checkout a copy of the possibly unstable trunk to ./trunk:
svn co <nowiki> trunk</nowiki>
<code>svn co <nowiki> trunk</nowiki></code> To checkout a copy of the last branch GRAMPS Gramps 4.0 ./gramps40: <code>svn co <nowiki> gramps40</nowiki></code> To checkout a copy of the last branch Gramps 3.4 ./gramps34: <code> svn co <nowiki> gramps34</nowiki></code> To checkout a copy of the last branch Gramps 3.3 ./gramps33: <code>svn co <nowiki> gramps33</nowiki></code> To checkout a copy of the last branch Gramps 3.2 ./gramps32: <code>svn co <nowiki> gramps32</nowiki></code> To checkout a copy of the last branch Gramps 3.1 ./gramps31:
To checkout a copy of the last branch GRAMPS 3.3 ./gramps33:<code> svn co <nowiki> gramps33gramps31 gramps31</nowiki></code>
To checkout a copy of the last branch GRAMPS older stable Gramps 3.2 0 ./gramps32gramps30:<code> svn co <nowiki> gramps32</nowiki></code>
To checkout a copy of the last branch GRAMPS 3.1 ./gramps31:<code> svn co <nowiki> gramps31gramps30 gramps30</nowiki></code>
To checkout a copy of the older stable GRAMPS 3Gramps 2.0 2 ./gramps30gramps22:<code> svn co <nowiki> gramps30</nowiki></code>
To checkout a copy of the older stable GRAMPS 2.2 ./gramps22:<code> svn co <nowiki> gramps22</nowiki></code>
=== Prepare gramps40 and trunk ===
Now go into the <code>trunk</code> directory and type
python build
As you should not install the development version, how can you try it out? The current Python version required to run Gramps trunk is officially python2.7 as of July 2012.
{{man note|1=Known Problems|2=Some problems are due to the migration from GTK2 to GTK3: [[GEPS_029:_GTK3-GObject_introspection_Conversion#Problems|list of known problems]]}}
==== Option 1: run from source repo ====
Copy the file created in build to your source directory if you want to use your source directory to work with Gramps:
cp build/lib.linux-x86_64$(uname -m)-2.7/gramps/gen/ gramps/gen/ # note the lib.linux path may vary depending on your system e.g. it could be lib.linux-i686-2.7
''Note'': the <code>lib.linux-$(uname -m)-2.7</code> folder name vary depending on your system (i686 or x86_64). That is it. If you installed some dependencies of Gramps in non-default positions, you need to indicate with PYTHONPATH where then they can be found, and with LD_LIBRARY_PATH where link libraries can be found. Eg, if you install GTK and spell checking from source too, you will need something like:
PYTHONPATH=/usr/local/lib/python2.7/site-packages/ LD_LIBRARY_PATH=/usr/local/lib python
==== Option 2: use the build code ====
Here, we use the code build in <code>trunk/build</code> directory to run Gramps. For compiled programs this is the only way, but for Gramps nothing is compiled. It is not bad however to keep your code separated from your execution, as deleting the build directory is easy. After a code change in your source, you then need to run however <code>python</code> again to update the build direcotry. To run Gramps from build, do
cd trunk/build/lib.linux-x86_64$(uname -m)-2.7/
python -c 'from gramps.grampsapp import main; main()'
PYTHONPATH=~/gramps-trunk/build/lib.linux-x86_64$(uname -m)-2.7/ python -c 'from gramps.grampsapp import main; main()'
So, more general:
PYTHONPATH=~/gramps-trunk/build/lib.linux-x86_64$(uname -m)-2.7/:/usr/local/lib/python2.7/site-packages/ LD_LIBRARY_PATH=/usr/local/lib python -c 'from gramps.grampsapp import main; main()'
If the build directory is in your PYTHONPATH, you can also just execute the module. So this will work too:
cd ~/gramps-trunk/build/lib.linux-x86_64$(uname -m)-2.7/gramps PYTHONPATH=~/gramps-trunk/build/lib.linux-x86_64$(uname -m)-2.7/ python
or again more generally
PYTHONPATH=~/gramps-trunk/build/lib.linux-x86_64$(uname -m)-2.7/:/usr/local/lib/python2.7/site-packages/ LD_LIBRARY_PATH=/usr/local/lib python
'''Note''': at At the time of writing, only the last, so using works, as not all imports in Gramps have been converted to relative or absolute imports. This conversion will be finished by end of 2012 however.
to modify the corresponding file.
(Who is I? - I do not know how to make a patchfile which documents
a deleted file which "patch" will then correctly delete.
(If you know how, please add it here.) When SVN version 1.7
is released (scheduled for 1Q2011 as I write this), then there
will be a "svn patch" command which should do that. (Pat SVN 1.7 is out this is the link talk about [])
== Working with development branches ==
=== Removing branches ===
It is important that branches are removed once they have been mergedinto the trunk or have been abandoned. To remove a branch:
svn remove <nowiki></nowiki>
The developers reserve the right to remove branches that have beendormant for more than 1 year. 
== Useful things to know ==
svn help log
Adding files to repositories requires you to set some properties to the files and to have a [ sourceforge account]. See <code>svn help propset</code>. You can use the <code>propget</code> on existing files to see how you should add it. A convenient way is to add common files to your <code>~/.subversion/config</code> file, eg in my config I have:
*.png = svn:mime-type=application/octet-stream
*.svg = svn:eol-style=native;svn:mime-type=text/plain
==== 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 commands in that branch directory[]:
svn status --no-ignore | awk '{print $2}' | xargs rm -rf
svn revert -R .
svn update
=== Ignore files ===
=== svn2cl ===
The GRAMPS Gramps project does not keep a ChangeLog file under source control. All change history is captured by Subversion automatically when it is committed. A ChangeLog file is generated from the SVN commit logs before each release using [[How to use svn2clBrief_introduction_to_SVN#How_to_use_svn2cl|svn2cl]]. Developers should take care to make useful commit log messages when committing changes to Subversion. Here are some guidelines:
*Try to make a descriptive message about the change.
*It is not necessary to put the names of the files you have modified in the commit message because Subversion stores that automatically.
=== Other usage tips =How to use svn2cl ==== Starting with Gramps 3.0.0, we no longer have a <tt>ChangeLog</tt> file.
* Additional tips and recommendations related to committing Instead, the list of changes: [[SVN Commit Tips]]* GRAMPS [[Committing policies]]is generated automatically using the standard <tt>svn2cl</tt> script.
Note that <tt>svn2cl</tt> is not included in the base installation of subversion. With a Debian-based distro such as Ubuntu, you can get <tt>svn2cl</tt> as follows:  sudo apt-get install subversion-toolsor sudo apt-get install svn2cl There typically are two <tt>ChangeLog</tt> files needed for releases; one in the main directory, and one in the <tt>po</tt> directory. You can generate these files with the following commands:  cd gramps30 svn2cl --reparagraph --include-rev --authors=src/data/authors.xml cd po svn2cl --reparagraph --include-rev --authors=../src/data/authors.xml = Browse ==SVN Commit Tips======= Some procedural recommendations ==== # Always do ''svn up'' before a commit, and look especially for conflicts marked 'C'. If necessary get advice about handling conflicts.# Always do ''svn st'' and look for modifications 'M' that are unexpected or unintended. This is a *very important* sanity check. Checking the '?'reports for forgotten additions is also worth remembering.# Recommeded to explicitly name commit targets via 'svn ci X Y Z ..', but if you do simply 'svn ci' (or use a utility commit script), it is especially important to:## check advisory (2)## quit (no save) your edit session if you see a filename you did not expect -- svn will prompt whether you want to abort or commit without a log entry (say 'abort'). ;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: the ideal first sentence would be short, meaningful, and suggestive. Include a tracker issue #NNNN there, if appropriate. Additional explanation is encouraged if it would be something you yourself would appreciate when reading it six months from now. If relevant, emphasize impact of change from user's point of view. ==== svn merge ==== If you do a change in a branch, you need to do the same change in trunk. You can create a patch on the branch with svn diff > mypatch.patchand then apply the same patch on trunk. patch -p0 < mypatch.patch There is a more convenient way though: use svn merge. For this you commit your changes in the branch, and write down the revision number, eg a commit in branch{{stable_branch}} : Transmitting file data .. Committed revision 12345.Now you apply this change in branch{{stable_branch}} to trunk as follows. Go into your trunk working branch, and there type the command:
An alternative to the command line tools to view the svn repository isthe [httpmerge -c 12345 online interface].code/branches/maintenance/gramps{{stable_branch}}
=== Download Tarball ===The change will then be obtained and applied, after which you can commit trunk.
You can also download a tarball for past and present sources.
* [ 3.2.x]
* [http://gramps.=== Browse 3.3.x]==
* An alternative to the command line tools to view the svn repository isthe [ 3online interface].4.x]
==External links==* [ Apache™ Subversion®]*[http://svnbook.sourceforgered-bean.netcom/viewvcVersion Control with Subversion]*[http:/gramps/ Trunksvn.html Source control in ten minutes: a Subversion tutorial]

Navigation menu