Jump to: navigation, search

Brief introduction to SVN

914 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 '''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 things with 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 ==
* ''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.
== 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 line if you '''don't have a sourceforge account''':  <code> svn co <nowiki></nowiki>{{stable_branch}} gramps{{stable_branch}}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.
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>
A developer can apply this patch then with the command:
 <code> patch -p0 < mychanges.patch</code>
== Unstable development: "trunk" ==
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/gmane.comp.genealogymessage.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:
 <code> svn co <nowiki> trunk</nowiki></code>
To checkout a copy of the last branch 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:
 <code> svn co <nowiki> gramps31</nowiki></code>
To checkout a copy of the older stable Gramps 3.0 ./gramps30:
 <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 ===
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 ==
=== svn2cl ===
The 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 tips = How to use svn2cl ====
==SVN Commit Tips==Starting with Gramps 3.0.0, we no longer have a <tt>ChangeLog</tt> file. ==== Some procedural recommendations ====Instead, the list of changes 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:
1. Always do ''svn up'' before a commit, and look especially for conflicts marked 'C'. If necessary sudo apt-get advice about handling conflicts.install subversion-toolsor sudo apt-get install svn2cl
2. Always do ''svn st'' There typically are two <tt>ChangeLog</tt> files needed for releases; one in the main directory, and look for modifications 'M' that are unexpected or unintendedone in the <tt>po</tt> directory. This is a *very important* sanity check. Checking You can generate these files with the '?'reports for forgotten additions is also worth remembering.following commands:
3 cd gramps30 svn2cl --reparagraph --include-rev --authors=src/data/authors. I personally prefer to explicitly name my commit targets via 'svn ci X Y Z xml cd po svn2cl --reparagraph --include-rev --authors=..', but if you do simply 'svn ci' (or use a utility commit script), it is especially important to:/src/data/authors.xml
(a) check advisory (2)===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' (bor 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).
* 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.
..jgsack: well, those are my self-reminders anyway. Others may have other ways of saying it or other things to emphasize.
==== svn merge ====
==Gramps commiting policies==
* Gramps [[Committing policies]]
=== Browse svn ===
the [ online interface].
=== Download Tarball =External links==*[ Apache™ Subversion®]You can also download a tarball for past and present sources*[ com/ Version Control with Subversion] '' This feature is no longer present *[ Source control in the new sourceforge platform ''ten minutes: a Subversion tutorial]

Navigation menu