Developers' side bar
<< | Page list | >>
Developing LyX using Subversion. Various tips, recommendations and suggestions for a better workflow.
This page was created after Richard1 asked for suggestions on how to work with branches more efficiently, or more specifically: How to merge the work back into trunk.
A lot of this information is of course available in the SVN book. The purpose of this page is not to duplicate that information, but to give concrete and applicable examples for working with the LyX repository.
In addition, the recommendations will also relate to a workflow in the LyX development when using Subversion.
The following commands assume you have commit permissions to the repository, i.e. in practice an account on the server (svn.lyx.org aka aussie.lyx.org). Ideally the commands should be useful as copy'n'paste, i.e. actually useful, so please use real URIs.
Use svn help for help via the command line, or read the SVN Book (see the links at the end).
You an use TRAC to browse the repository and find the desired path this way.
svn co svn://svn.lyx.org/lyx/lyx-devel/branches/BRANCH_1_5_X lyx-1.5.x
svn co svn://svn.lyx.org/lyx/lyx-devel/branches/personal/larsbj/xml lyx-XML
Use one branch for a single purpose in order to later simplify a merge with trunk.
Location of branches
Personal branches for LyX development should be located as follows:
that for Lars' XML branch translates to the follwing URI:
Creating a branch
There are several ways to create a branch. Below is a way to create a branch without having to check out anything locally:
svn copy svn://svn.lyx.org/lyx/lyx-devel/trunk \ svn://svn.lyx.org/lyx/lyx-devel/branches/personal/user/branch \ -m "Creating a private branch for XML development based on /lyx-devel/trunk."
Here is how you can update your branch with respect to trunk.
First, commit whatever changes you've made locally. Then, if there's a mistake, you can always revert to that revision.
It's a bit of a weakness of Subversion that you need to know when your branch was last updated with respect to trunk. Subversion has no way of keeping such information for you. It's a good idea to write this down, but you can find it by examining your commit logs: You should always commit as soon as you've merged from trunk and gotten things working again. That said, use:
svn log svn://svn.lyx.org/lyx/lyx-devel/branches/personal/user/branch
to examine your commit logs. If you make a point of starting all and only the commits following merges with the word "Sync", then try this:
svn log --limit 1 svn://svn.lyx.org/lyx/lyx-devel/branches/personal/user/branch | \ grep -B2 Sync
With a little more cleverness, you could actually extract the revision number:
svn log --limit 1 svn://svn.lyx.org/lyx/lyx-devel/branches/personal/user/branch | \ grep -B2 Sync | head -n1 | cut -d' ' -f1 | | sed -e's/r\(.*\)/\1/'
See below for something to do with it.
So let's say you last merged from trunk at revision 19245. Then you can merge new changes since then as follows:
svn merge [--dry-run] -r 19245:HEAD svn://svn.lyx.org/lyx/lyx-devel/trunk
where this command is run from your own local copy of your branch. It's a good idea to use the --dry-run argument the first time before you do this for real.
So now try this, if you have bash (though it should work with trivial modifications with other shells):
#!/bin/bash REV=`svn log --limit 1 svn://svn.lyx.org/lyx/lyx-devel/branches/personal/user/branch | \ grep -B2 Sync | head -n1 | cut -d' ' -f1 | | sed -e's/r\(.*\)/\1/'`; svn merge -r $REV:HEAD svn://svn.lyx.org/lyx/lyx-devel/trunk
We wouldn't recommend using it in that form, but you get the idea.
See Ch. 4, sec 3 and later sections in the SVN book for more on merging branches.
Here is how you can compare two branches (do a
svn diff svn://svn.lyx.org/lyx/lyx-devel/trunk \ svn://svn.lyx.org/lyx/lyx-devel/branches/BRANCH_1_5_X
If you want to compare at a particular revision, you can add the revision number to the end of the name of the working copy, thus:
svn diff svn://svn.lyx.org/lyx/lyx-devel/trunk@19251 \ svn://svn.lyx.org/lyx/lyx-devel/branches/BRANCH_1_5_X@19278
You can also refer to a local copy:
svn diff svn://svn.lyx.org/lyx/lyx-devel/trunk \ /cvs/lyx-devel/branches/BRANCH_1_5_X
And any path is acceptable, including one that specifies a particular file:
svn diff svn://svn.lyx.org/lyx/lyx-devel/trunk/src/callback.cpp \ svn://svn.lyx.org/lyx/lyx-devel/branches/BRANCH_1_5_X/src/callback.cpp
Tips on how to backport changes from a branch to trunk. On the overall, you should proceed as follows:
Backporting a set of changes
There are probably tools out there that can help with this process.
Merging a whole branch to another
You want to merge your branch to a working copy of trunk. How do you do it?
svn log --stop-on-copy \ svn://svn.lyx.org/lyx/lyx-devel/branches/personal/larsbj/xml
svn merge -r 19477:19500 \ svn://svn.lyx.org/lyx/lyx-devel/branches/personal/larsbj/xml
The result is a locally changed working copy of trunk that now contains the work from the branch. Use svn status to see what's changed.
One example for deleting advsearch branch:
svn delete svn://firstname.lastname@example.org/lyx/lyx-devel/branches/advsearch
Please gather your comments about how to work with branches in this section.
In order to have correct EOLNs you should use:
svn propset svn:eol-style native FILE
when adding file to the project tree.
svn propset svn:executable ON SCRIPT_FILE
svn propset svn:needs-lock ON FILE
1 There was also a ruccus with Abdel. (↑)
2 The prefix