Difference between revisions of "Subversion"

From GnuCash
Jump to: navigation, search
(Prevent new contributors from starting with svn. Forward them to the git page instead.)
m (Removve obsolete page from the Development category)
 
(One intermediate revision by the same user not shown)
Line 2: Line 2:
  
 
GnuCash has switched to git to manage its source code. Please refer to the [[git]] page if you want to check out the source code. Do not start from svn anymore.
 
GnuCash has switched to git to manage its source code. Please refer to the [[git]] page if you want to check out the source code. Do not start from svn anymore.
 
=Introduction=
 
Our source code is hosted on the Subversion server svn.gnucash.org. For accessing the repository, you can choose many methods. The most direct method is using subversion as a client (also called svn). This is explained on this page.
 
 
Alternative access methods:
 
* As a strongly suggested alternative (and used by several of the developers), you can use [[git]] and ''git-svn'' as a method of accessing the source code.
 
* Or you can use the since 2010 discontinued svn-svk [http://en.wikipedia.org/wiki/SVK SVK].
 
* There is also a branch available via [[bazaar]] which is very quick to check out.
 
 
=Repository URLs=
 
 
The various base URLs look like:
 
 
  anonymous:  <nowiki>http://svn.gnucash.org/repo/gnucash/trunk</nowiki>
 
  developer:  svn+ssh://username@svn.gnucash.org/repo/gnucash/trunk
 
      trac:  http://svn.gnucash.org/trac
 
 
'''Note:''' If you are having problems with the http:// anonymous access, make sure your subversion is compiled with [http://www.webdav.org/neon/ neon] support.
 
 
'''Note:''' If you are behind a proxy (http firewall), you need to manually set the proxy name and authentication information in one of your local svn configuration file, namely in <tt>$HOME/.subversion/servers</tt> . Just open that file with a text editor and scroll to the end; you will find instructions there on how to set the variables. See also http://subversion.tigris.org/faq.html#proxy
 
 
'''Warning:''' Somebody working also on the documentation and/or the web page could try to use <tt><nowiki>http://svn.gnucash.org/repo/</nowiki></tt>, but that would produce ~10 GiB mostly of dead branches and <tt>svn up</tt> would become very slow.
 
 
== SVN and Microsoft Windows™ ==
 
 
There are two ways to use Subversion with Microsoft Windows™:
 
* One is the subversion client built with [http://www.mingw.org/ MinGW] (not provided as part of MSYS, but the Windows build script will build it as part of the process.
 
* The other is  [http://tortoisesvn.net/ TortoiseSVN].
 
 
The client built by the install script is a command line client that works only in the MSYS command shell. It is exactly the same client used on Linux and MacOSX systems, and its use is summarized below.
 
 
TortoiseSVN is a Windows™-native implementation with a nice GUI that integrates into the context menu of Windows™ Explorer. Users without commit privileges can simply create a folder, select it in Explorer, right-click, and select "TortoiseSVN Checkout..." from the context menu. A dialog box will open into which one can type the anonymous URL (committers have a bit more involved [[#Microsoft Windows™|setup]]) and click OK. Once you've checked out the repository, you can use the TortoiseSVN context menu to view logs and history.
 
 
=Common Commands=
 
 
To get what used to be CVS HEAD, you will need to get the svn TRUNK:
 
 
    svn checkout <nowiki>http://svn.gnucash.org/repo/gnucash/trunk</nowiki> gnucash
 
 
The argument "gnucash" above can be whatever you want your local directory to be called, and is optional. If you leave it out, you'll have a directory called "trunk" created containing all the source code.
 
 
If you want the latest 2.4.x code, you'd need to pull from the 2.4 branch, as follows:
 
 
    svn checkout <nowiki>http://svn.gnucash.org/repo/gnucash/branches/2.4</nowiki> gnucash-2.4
 
 
And if you want the released code for a specific release (or tag), you'd use:
 
 
    svn checkout <nowiki>http://svn.gnucash.org/repo/gnucash/tags/2.4.3</nowiki> gnucash-2.4.3
 
 
And to update, just cd into the directory containing the sources you want updated and execute a simple
 
 
    svn update
 
 
To switch a TRUNK working copy to the 2.4 branch, cd into the directory containing the sources you want updated and do this:
 
 
    svn switch <nowiki>http://svn.gnucash.org/repo/gnucash/branches/2.4</nowiki>
 
 
If you get an error message like <tt>svn: E155036: Working copy '/PATH/TO/YOUR/WORKSPACE' is too old ...'</tt> e.g. while running make, you should convert that directory with:
 
cd /PATH/TO/YOUR/WORKSPACE
 
svn upgrade
 
 
You probably want to continue reading at the [[Building]] page. Otherwise, continue on below for information on how to use subversion.
 
 
= SVN tutorial =
 
 
Now that the gnucash repository is using svn for version control (since 2005-11-04), the need for a quick tutorial on how to get the sources might be in order. There was some introduction about SVN in an [http://lists.gnucash.org/pipermail/gnucash-devel/2005-October/014333.html e-mail] on gnucash-devel:
 
 
The excellent "[http://svnbook.red-bean.com/ Version Control with Subversion] is a very good resource for information about subversion. 
 
 
Specifically, [http://svnbook.red-bean.com/en/1.1/ch03.html Chapter 3. Guided Tour]
 
and [http://svnbook.red-bean.com/en/1.1/apa.html Appendix A. Subversion for CVS Users] are relevant.
 
 
The command-line client `<tt>svn</tt>` has a nice integrated help system; `<tt>svn help</tt>`
 
will provide the top-level command list, and `<tt>svn help <command></tt>` detailed
 
help for the specific command.
 
 
The bottom line is that getting the source via svn isn't altogether different from getting it using cvs.
 
 
=CVS to SVN cross reference=
 
{| cellpadding="2" cellspacing="0" border="1"
 
! CVS command
 
! SVN command
 
! Notes
 
|-
 
| cvs checkout
 
| svn checkout
 
|
 
|-
 
| cvs commit
 
| svn commit
 
|
 
|-
 
| cvs status
 
| svn status
 
| ...but the svn one is actually useful :)
 
|-
 
| cvs log
 
| svn log
 
|
 
|-
 
| cvs annotate
 
| svn blame
 
|
 
|-
 
| cvs diff
 
| svn diff
 
|
 
|-
 
| cvs diff -D 2006-01-01
 
| svn diff -r {2006-01-01}:HEAD
 
|
 
|-
 
| cvs update
 
| svn update, svn switch
 
|
 
|-
 
| cvs update -C
 
| svn revert
 
|
 
|-
 
| cvs update -j [...]
 
| svn merge
 
|
 
|-
 
| <nowiki> ---- </nowiki>
 
| svn resolved [conflicting merges must be explicitly resolved]
 
|
 
|-
 
| cvs add
 
| svn add, svn mkdir
 
|
 
|-
 
| cvs remove
 
| svn delete
 
|
 
|-
 
|<nowiki>  ----  </nowiki>
 
| svn move
 
|
 
|-
 
| cvs [r]tag [-b]
 
| svn copy
 
|
 
|}
 
 
 
Enjoy!
 
 
=Maintain a local copy of the repository=
 
 
Note: For keeping track of the various branches in SVN and have patch creation made much much easier, it might be very helpful to use one of the many tools to maintain a ''local copy'' of the SVN repository. Some of these options are:
 
* [[git]] with ''git-svn''
 
* Maintaining a SVN repository on your own: How to maintain your own local subversion branch of someone else's repository, keep it synced with changes upstream, and generate patches: http://www.parit.ca/Weblog/archive/2008/07/05/keeping-up-with-the-joneses-svn-repo
 
* Bazaar with ''bzr-svn''
 
 
=SVN write access=
 
 
FAQ: Is it possible to get SVN write access?
 
 
A: In principle yes, but we are quite conservative with giving out new SVN write accounts. For occasional changes people are encouraged to submit patches. We do add people as developers if they stick around, supply lots of patches, become highly involved in the project, hang out on IRC, and generally show some level of clue and prove some level of trust. But in the meantime, patches in Bugzilla are the suggested route, as has been stated at other places. --[[User:Cstim|Cstim]] 08:00, 8 January 2006 (EST)
 
 
=Subversion for Committers=
 
 
==Preparations==
 
When you are granted committer privileges, the repository administrator will arrange with you to create a username and to transfer to him a public key to use with subversion. You'll use subversion the same way, except that the URL will be <tt>svn+ssh://username@svn.gnucash.org/repo</tt>. The key should be a 1024-bit or larger RSA key in openssl format. Openssl is provided by most Linux distributions and is built in to MacOSX. To generate a key:
 
  ssh-keygen -b 1024 -t rsa
 
You will be prompted for a filename, with a default of <tt>~/.ssh/id_rsa</tt>. That is the correct filename to use if you have only one key -- and if you have more than one, you already know enough about SSL that you don't need these instructions.
 
 
You will also be prompted for a passphrase, with the option to leave it blank. If you provide a passphrase, you will be prompted to provide it every time you use your key. If you don't, anyone who gains access to your key can connect to whatever servers you protect with it.
 
 
Once you have the key configured correctly, try to ssh to svn.gnucash.org. If everything is set up correctly, you'll get a message <tt>Shell login to CVS server not permitted</tt> and the connection will drop. You're ready to connect with subversion. If not, you'll have to contact the repository administrator for help.
 
 
=== Microsoft Windows™ ===
 
 
To set up ssh with the MSYS client, proceed exactly as above.
 
 
For [[http://tortoisesvn.net/ TortoiseSVN]], you'll also need PuttyGen and Putty from [[http://www.chiark.greenend.org.uk/~sgtatham/putty/ PuTTY]].
 
Setting up Pageant to work with TortoiseSVN is a bit involved, so we'll go through it step-by-step:
 
 
1. Use PuttyGen to convert your private key into Putty format. Launch puttygen, click the "load" button and select your private key file, then click the "save private key" button to save it in putty format.
 
 
2. Set up a Putty profile: Start Putty.
 
* Set the Host URL to svn.gnucash.org, port 22 on the Session page
 
* Open Connection:SSH:Auth and at the bottom of the panel, for "Private key file for authentication" browse for the converted keyfile you made in the previous step.
 
* Open Connection:Data and enter your username in the "Autologin username" text entry.
 
* Return to the Session panel, enter a name (if you use <tt>svn.gnucash.org</tt> configuring TortoiseSVN will be less confusing) in the text entry named "Saved Sessions" and click the "save" button.
 
* Click "open". If everything is done correctly, a command window will open and you'll see that message about terminal sessions not being allowed. If you are instead prompted for a password, you have messed up the username or key somehow and will need to contact the server admin to get your IP address unblocked.
 
 
3. Set up TortoiseSVN:
 
* Right-click a folder in Windows™ Explorer and select TortoiseSVN:Settings. At the bottom of the Network panel of the resulting dialog box, click the "Browse" button for SSH Client and navigate to <tt>C:\Program Files\TortoiseSVN\bin\TortoisePlink.exe</tt>, click "open" in the file chooser, the "OK" to dismiss the Settings box.
 
* Right-click on a folder into which you want to check out (or already have checked out) Gnucash. If it's a fresh checkout, select TortoiseSVN Checkout; otherwise select TortoiseSVN:Relocate. Enter the URL as <tt>ssh+svn://the-putty-session-name/repo/gnucash/trunk</tt>. (Remember earlier where we said it would be less confusing if you use <tt>svn.gnucash.org</tt> for the session name? That's because if you did the URL will be <tt>svn+ssh://svn.gnucash.org/repo/gnucash/trunk</tt>.)
 
 
You should now be able to commit changes via TortoiseSVN.
 
 
== Commit Conventions ==
 
 
Your commit should have a comment explaining your change.
 
 
=== Link Bugzilla Entries ===
 
 
Often commits are related to [[Bugzilla]] entries. In this case the first line should contain
 
* '''<tt>Bug #</tt>''<bug number>''<tt>:</tt>''<bug title>''''' or
 
* '''<tt>Bug #</tt>''<bug number>''<tt> - </tt>''<bug title>'''''.
 
If ''trac'' sees the hash sign (#), it should create a link to that bugzilla entry.
 
 
=== Backport Rules ===
 
 
While usually commits will be applied to ''trunk'', sometimes it is desired to '''backport''' them on the ''stable branch'', currently 2.4. There are a few rules to decide, if a commit should be backported:
 
* If the commit fixes a bug[[#Note|(1)]] that was reported in ''bugzilla'' against the ''stable branch'', the changeset should be backported, but:
 
* The backporting effort should be trivial. If complicated manual intervention is required, backporting should be skipped to maintain stability.
 
* Backports should not require new or stronger ''dependencies.''
 
* If the changeset modifies the ''data model'', it should be split in 2 parts:
 
** The part to ''read'' the modified data model should be backported.
 
** The part to ''write'' the modified data model should only be applied on trunk.
 
:: This would allow a user to test a new main release on one computer while still using the older version on another computer or later on the same computer again without data loss.
 
 
If you wish to backport your commit on trunk should contain the mark '''BP''' in a separate line of the comment. That would trigger the prefix '''AUDIT''' to the mails sent to the ''gnucash-patches'' and ''gnucash-changes'' lists.
 
 
====Note====
 
* Backporting only applies for true bugs, meaning errors in the existing functionality or intended use. New features, additions to current functionality, enhancement requests etc. are not considered for backporting, even if the enhancement request was registered in bugzilla against the stable branch.
 
 
=== Current Backport Policy ===
 
 
While it would be better new patches would be committed on trunk and only backported at release date, the current [[Release Process|release]] manager does not have the resources to do that. So it is up to the committer to backport his commits where required. On merging/branching the [[Translation Status]] should be adjusted in consultation with the [[user:Cstim|translation manager]].
 
 
=== Backport comment format ===
 
 
This section is adapted from Geert Janssens'
 
email [http://lists.gnucash.org/pipermail/gnucash-devel/2012-October/034404.html] to the gnucash-devel list.
 
 
The commit message for trunk should contain, somewhere within the body
 
of the message, a line with only &ldquo;BP&rdquo; on it to indicate this
 
commit is meant to be backported. That helps to check later if all the
 
relevant commits are really backported. It also alters the commit
 
messages that are sent to gnucash-patches and gnucash-changes to begin
 
with &ldquo;AUDIT&rdquo;. The AUDIT/BP marks don&rsquo;t trigger any
 
automatic backporting tasks within the source code management system,
 
but they&rsquo;re still useful for other developers to follow what gets
 
backported and what not.
 
 
The commit message on the commit that goes into the stable branch
 
essentially uses the same text with two small changes: the line
 
containing the &ldquo;BP&rdquo; mark is removed, and the revision number
 
of the trunk commit is prepended to the message, surrounded with square
 
brackets.
 
 
An example will probably make it much clearer.  The commit to trunk
 
would have this message:
 
 
<pre>
 
My latest changes
 
BP
 
</pre>
 
 
Let&rsquo;s assume this got committed in r22445 and now has to be
 
backported. The message to use on the stable branch will now be:
 
 
<pre>
 
[22445] My latest changes
 
</pre>
 
 
That&rsquo;s it.
 
 
----
 
 
Other options exists as well; feel free to edit this wiki page.
 
 
[[Development_Process|Back to Development Process]]
 
 
[[Category:Development]]
 

Latest revision as of 15:48, 1 October 2021

This page is obsolete

GnuCash has switched to git to manage its source code. Please refer to the git page if you want to check out the source code. Do not start from svn anymore.