Difference between revisions of "OOo and Subversion"

From Apache OpenOffice Wiki
Jump to: navigation, search
(Rebasing a CWS)
m
 
(43 intermediate revisions by 13 users not shown)
Line 1: Line 1:
=OpenOffice.org migrates to Subversion=
+
{{Old|EN}}
 +
[[Category:SVN]][[Category:SCM]]
 +
__TOC__
  
After a long discussion and preparation time it finally happens, OpenOffice.org migrates with milestone DEV300 m31 to a new SCM (<u>S</u>oftware <u>C</u>onfiguration <u>M</u>anagement) system. The new SCM system will be Subversion (SVN) for now, which might disappoint the one or other who had hoped for a distributed SCM like Git, Bazaar or Mercurial. Please be assured that we'll keep our mind open and we'll reevaluate the fast moving SCM tooling situation periodically. We were very careful to make certain that our move now to Subversion does not preclude a move to a DSCM in the future.{{note|why}}
+
== CWS Tooling ==
 
+
==Trunk only migration==
+
 
+
Milestone DEV300 m31 is the last milestone which has been integrated via CVS and is the first milestone which is available in SVN. We did a trunk migration only. The trunk (DEV300) code line will be maintained via Subversion only starting with milestone DEV300 m32. Old code lines, '''including the OOo-3.0 release codeline(OOO300)'''  will still be maintained via CVS.
+
 
+
Please let me repeat this: we did not migrate branches and tags to SVN. There are a number of advantages (and some disadvantages as well) to this approach. A discussion of the merits of different approaches to the actual repository conversion can be found [[Scm_migration_scope|here]].
+
 
+
The most important reasons for choosing the "trunk only" approach were:
+
* No quiet time for developers
+
* The conversion of historical workspaces from CVS to SVN would be fragile at best due to some liberties we took in structuring our CVS repository. Having no historical branches and tags is preferable to having inaccurate branches and tags IMHO.
+
 
+
The "trunk only" approach enabled us to optimize the resulting SVN repository, it shrunk from 90 GBytes to about 6 GBytes overall size. The following rules have been applied during conversion
+
* Only modules which have active content in DEV300 m31 are included in the conversion.
+
* All files in "Attic" have been removed.
+
* All but the last revisions of binary files have been dropped - after all you can't diff them anyway
+
* All but the last revisions of "localize.sdf" files have been dropped - saves an incredible amount of repository space without loosing much
+
 
+
==Required tools==
+
 
+
* subversion-1.5.1 or later; [http://subversion.tigris.org/getting.html#binary-packages download...]
+
* ssh for committers, preferably OpenSSH 2.4 or later
+
 
+
We make heavy use of the new SVN merge tracking feature. So please do not use a SVN client older than subversion-1.5.1 if you work on a child workspace (CWS).
+
 
+
Windows users most certainly want to take a look at [http://tortoisesvn.tigris.org/ TortoiseSVN] and lots of documentation available at http://tortoisesvn.net/
+
 
+
==Subversion documentation==
+
 
+
The excellent Subversion documentation can be found here: http://svnbook.red-bean.com. Please use the nightly build documentation for 1.5 and later, it covers new features like merge tracking.
+
 
+
<font color=red size=5><center>Please read at least the "fundamental concepts" and "basic usage" part of the documentation!</center></font>.<center>CWS tooling is only a very thin layer around the SVN client hiding the lengthy URLs from sight plus some bookkeeping. Everything else is plain Subversion.</center>
+
 
+
==Server access methods==
+
 
+
===Read only SVN access===
+
 
+
svn checkout svn://svn.services.openoffice.org/ooo/trunk
+
 
+
or
+
 
+
svn checkout http://svn.services.openoffice.org/ooo/trunk
+
 
+
===Read only browser access===
+
 
+
Point your browser to
+
http://svn.services.openoffice.org/ooo
+
 
+
===Read/write access===
+
 
+
Write access to the repository requires a ssh setup.
+
 
+
svn co svn+ssh://svn@svn.services.openoffice.org/ooo/trunk
+
 
+
==Basic read/only SVN operations==
+
 
+
===Repository structure===
+
 
+
The OOo SVN repository is structured like this:
+
 
+
../trunk                    <= the main development line, currently master workspace DEV300 is on trunk
+
../cws                      <= child workspaces live here, names need to be unique
+
../cws/foo                  <= for example CWS ''foo''
+
../cws/...
+
../branches                  <= future master workspaces which are not on trunk
+
../branches/OOO310          <= for example MWS ''OOO310''
+
../branches/...
+
../tags                      <= milestone tags, release tags
+
../tags/DEV300_m32          <= for example milestone ''DEV300 m32''
+
../tags/..
+
../dist                      <= space for distribution specific stuff
+
../patches                  <= space for globally useful patches
+
../contrib                  <= do we need this?
+
 
+
Examples:
+
 
+
Check out a milestone ''DEV300 m32'' with:
+
 
+
svn checkout svn://svn.services.openoffice.org/ooo/tags/DEV300_m32
+
 
+
Switch from milestone ''DEV300_m32'' to ''DEV300_m35'' (safes potentially a lot of checkout time):
+
 
+
cd DEV300_m32
+
svn switch svn://svn.services.openoffice.org/ooo/tags/DEV300_m35
+
cd ..
+
mv DEV300_m32 DEV300_m35
+
 
+
Check out a child workspace ''foo'':
+
 
+
svn checkout svn://svn.services.openoffice.org/ooo/cws/foo
+
 
+
Update working copy of ''foo'':
+
 
+
cd foo
+
svn update
+
 
+
Find out the base (milestone or cws) of working copy ''wc'':
+
 
+
cd wc
+
svn info
+
 
+
List all available milestone and release tags:
+
 
+
svn list svn://svn.services.openoffice.org/ooo/tags
+
 
+
List all available child workspaces:
+
 
+
svn list svn://svn.services.openoffice.org/ooo/cws
+
 
+
View commit log on a single file:
+
 
+
svn log file.cxx
+
 
+
Include all paths affected by change sets in log command:
+
 
+
svn log --verbose file.cxx
+
 
+
Attribute blame:
+
 
+
svn annotate file.cxx
+
 
+
==SSH Setup==
+
 
+
===SSH key generation===
+
 
+
On Unix or Windows/cygwin a SSH identity (private/public key pair) is generated with:
+
 
+
ssh-keygen -t dsa
+
 
+
You'll be asked for pass phrase which protects your private key. Per default the public key is named <tt>$HOME/.ssh/id_dsa.pub</tt>.
+
 
+
Note that SSH keys created between September 2006 and May 2008 on Debian or Debian derived systems like Ubuntu may be insecure. Please use recent SSH tools.
+
 
+
If you want a dedicated identity for just OOo SVN usage, generate a specially named key pair
+
 
+
ssh-keygen -t dsa -f ~/.ssh/id_dsa_ooo_svn
+
 
+
and instruct Subversion to use this identity (key pair) with the following configuration entry in <tt>$HOME/.subversion/config</tt>:
+
 
+
[tunnels]
+
ssh = ssh -i /home/jr93709/.ssh/id_dsa_ooo_svn
+
 
+
===Initial Migration of Keys===
+
 
+
Please query IssueZilla for your issue with the attachment holding your key and add it as a dependency to [http://www.openoffice.org/issues/show_bug.cgi?id=94002 issue 94002]. If you are a new svn user, create the issue yourself.
+
 
+
We will then install those keys for DomainDevelopers for read/write access to the SVN repository.
+
 
+
Up to now only few code committers made use of the ssh key upload for the OpenOffice.org SVN repository. Please note that your key will not be migrated without your intervention.
+
 
+
===Ongoing Maintenance===
+
 
+
We will continue to use IssueZilla for managing and tracking key additions and changes.
+
Please see [http://www.openoffice.org/docs/ddSSHGuide.html#sendingkey Submitting Your Certificate (Public Key)].
+
 
+
===Windows ssh setup with putty ===
+
 
+
<p>To use ssh on Windows putty's ssh can be used. You need plink.exe, puttygen.exe and pageant.exe. All are available from [http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html]</p>
+
 
+
 
+
<p>As putty uses a different ssh key format you have to convert the private key using puttygen.exe.</p>
+
<p>Save this file for example as:</p>
+
<p><system drive>:\Documents and settings\<user name>\Application Data\id_dsa_ooo_svn.ppk</p>
+
 
+
 
+
<p>In the [tunnels] section of the file <system drive>:\Documents and settings\<user name>\Application Data\Subversion\Config</p>
+
<p>You have to add the line:</p>
+
<p>ssh = plink.exe -i <path to you converted private key file></p>
+
<p>Please note that spaces in the path have to be escaped using a backslash.</p>
+
 
+
 
+
To be able to call an svn command you need to have the pageant.exe running. Start this and import your private key file.
+
 
+
 
+
On the first connection to the server the server's host key has to be added to the registry. This doesn't work within the svn command.
+
<p>The following command helps to accept this key:</p>
+
<p>plink.exe -i <path to private pkey> svn.services.openoffice.org svnserve -t</p>
+
 
+
==CWS tooling==
+
  
 
The CWS tooling has been reworked to adapt to SVN. The basic CWS tool is now simply called <tt>cws</tt> and is invoked as <tt>cws <subcommand></tt> in the style of the SVN client, there are no longer separate tools like <tt>cwsadd</tt>, <tt>cwsresync</tt> etc etc.
 
The CWS tooling has been reworked to adapt to SVN. The basic CWS tool is now simply called <tt>cws</tt> and is invoked as <tt>cws <subcommand></tt> in the style of the SVN client, there are no longer separate tools like <tt>cwsadd</tt>, <tt>cwsresync</tt> etc etc.
  
 +
<div style="background:#888888; padding:10px>
 
Note: the <tt>cws</tt> script will probably change over time as we learn how the usage patterns evolve. If you got a problem with the <tt>cws</tt> script, it might be worthwhile to rebase it to the latest version
 
Note: the <tt>cws</tt> script will probably change over time as we learn how the usage patterns evolve. If you got a problem with the <tt>cws</tt> script, it might be worthwhile to rebase it to the latest version
 
  $ cd <your_CWS>/ooo/solenv/bin
 
  $ cd <your_CWS>/ooo/solenv/bin
Line 188: Line 13:
 
  $ cd modules
 
  $ cd modules
 
  $ svn merge svn+ssh://svn@svn.services.openoffice.org/ooo/trunk/solenv/bin/modules/CwsConfig.pm
 
  $ svn merge svn+ssh://svn@svn.services.openoffice.org/ooo/trunk/solenv/bin/modules/CwsConfig.pm
 +
</div>
  
 +
The most important change in the way CWSs are handled now is that there is no longer a need nor possibility to add modules. Well, there is still a <tt>sw</tt> and <tt>config_office</tt> but all modules of old are now just top level directories, at least as far as SVN is concerned. They still remain a concept of the build system of course.
  
The most important change in the way CWSs are handled now is that there is no longer a need nor possibility to add modules. Well, there is still a <tt>sw</tt> and <tt>config_office</tt> but all modules of old are now just top level directories, at least as far as SVN is concerned.
+
see [http://wiki.services.openoffice.org/wiki/Setting_up_Subversion_Access#CWS_Tooling_Setup|| CWS Tooling Setup] for details on the preparations needed to use the new CWS tooling.
 
+
===CWS config file===
+
 
+
Please keep all your entries in your <tt>$HOME/.cwsrc</tt> for now, you'll need them if you want to work with CWSs for OOo-3.0. Just add the following line to refer to the OpenOffice.org SVN server:
+
 
+
SVN_SERVER=svn+ssh://svn@svn.services.openoffice.org/ooo
+
 
+
Example of a complete <tt>.cwsrc</tt> file:
+
 
+
[CWS_CONFIG]
+
# Network proxy for EIS connections.
+
# Comment in if you need to access EIS via a proxy.
+
# Note: This is just for accessing the EIS database. For SVN have a look here:
+
# http://svnbook.red-bean.com/nightly/en/svn.advanced.confarea.html#svn.advanced.confarea.opts.servers
+
# Example: PROXY=http://myproxy.company.com:8080
+
# PROXY=
+
+
# CWS Database server (SOAP). It's possible specify to several backup server,
+
# currently there are none.
+
CWS_DB_SERVER_1=https://eis.services.openoffice.org/soap/servlet/rpcrouter
+
+
# Your CVS login (for authentication with the CWS database).
+
CVS_ID=<your_ooo_name>
+
+
# Your scrambled CVS password (for authentication with the CWS database).
+
# Take this one from .cvsrc
+
CVS_PASSWORD=<your_current_cvs_scrambled_ooo_password>
+
+
# OOo CVS tunnel
+
# Example: CVS_SERVER_ROOT=pserver:cvs_id@mytunnel.mydomain.de:/cvs
+
CVS_SERVER_ROOT=
+
+
# Path to the cvs binary (optional)
+
# Example: CVS_BINARY=/usr/bin/cvs
+
#CVS_BINARY=
+
+
# SVN server for OOo-3.1 child workspaces
+
# r/w access via svn+ssh pprotocol
+
SVN_SERVER=svn+ssh://svn@svn.services.openoffice.org/ooo
+
# r/o access via svn protocol
+
#SVN_SERVER=svn://svn.services.openoffice.org/ooo
+
  
===Working with the new <tt>cws</tt> tool===
+
=== Solving Common Tasks with the CWS Command ===
  
 
Help can be invoked with:
 
Help can be invoked with:
Line 260: Line 46:
 
The subcommands do more or less what their CVS predecessors did.
 
The subcommands do more or less what their CVS predecessors did.
  
====Create a CWS====
+
==== Create a CWS ====
  
 
Create a CWS with the <tt>cws create</tt> subcommand. Please note that this commands only creates a CWS branch on the OOo server and registers it with EIS. It changes nothing on your hard disk.
 
Create a CWS with the <tt>cws create</tt> subcommand. Please note that this commands only creates a CWS branch on the OOo server and registers it with EIS. It changes nothing on your hard disk.
Line 284: Line 70:
 
for check out.
 
for check out.
  
====Check out a CWS====
+
==== Checking out a CWS ====
  
 
  $ cws fetch -c foo <workspace name>
 
  $ cws fetch -c foo <workspace name>
Line 309: Line 95:
 
will fetch the differences between your working copy in <wc> and the CWS ''foo''
 
will fetch the differences between your working copy in <wc> and the CWS ''foo''
  
====Rebasing a CWS====
+
==== Rebasing a CWS ====
  
The successor of the <tt>cwsresync</tt> tool is called <tt>cws rebase</tt>. rebasing is now a two step operation:
+
===== Updating CWS Tooling =====
 +
{{Warn| If your CWS is based on a milestone earlier than DEV300_m36, please upgrade the cws utilities first before attempting to rebase. Utility revisions of m36 or later contain vital fixes.}}
  
cws rebase -m latest <workspace name>
+
To upgrade the CWS utilities issue the commands
  
merge the changes from latest milestone available on the mws into CWS. a REBASE.LOG logfile will be created for your records. After resolving possible conflicts the next step:
+
<code><pre>
 +
cd my_working_copy
 +
cd solenv/bin
 +
svn merge svn+ssh://svn@svn.services.openoffice.org/ooo/trunk/solenv/bin/cws.pl@264325
 +
cd modules
 +
svn merge svn+ssh://svn@svn.services.openoffice.org/ooo/trunk/solenv/bin/modules/Cws.pm@264325
 +
svn merge svn+ssh://svn@svn.services.openoffice.org/ooo/trunk/solenv/bin/modules/CwsConfig.pm@264325
 +
</pre></code>
  
cws rebase -C <workspace name>
+
===== Merging changes from master to working copy =====
 +
{{Warn| Always merge into a "clean" working copy:
 +
* no mixed revisions (svn update *is* mandatory)
 +
* no locally modified files}}
  
commits the merge into your cws.
+
The successor of the <tt>cwsresync</tt> tool is called <tt>cws rebase</tt>. rebasing is now a two step operation:
  
====How to migrate still active CVS based child workspaces destined for DEV300 to SVN?====
+
export CWS_WORK_STAMP=<name of the CWS>
 +
cws rebase -m latest <path to the CWS checkout>
  
Let's assume your CVS based CWS is called 'foo42'.
+
merge the changes from latest milestone available on the mws into CWS. A REBASE.LOG logfile will be created for your records in the root directory of the repository. A file named REBASE.CONFIG_DONT_DELETE will also be created after successful merging.  This file will be needed by the subsequent <code>cws rebase -C</code> command.
  
=====CVS tasks=====
+
{{Warn| If you don't see the file named REBASE.CONFIG_DONT_DELETE, that means that the merge was not successfully completed.}}
  
1) Find out the CVS branch tag and anchor tag of your CWS.
+
'' Remark: export doesn't work with all shells. Is a special shell mandatory for a rebase to run? ''
  
$ cd <added_module>
+
===== Resolving conflicts =====
$ cvs log <some_file_which_already_existed_before_your_cws> | grep -i foo42
+
SVN requires you to mark files with conflicts as 'resolved' before you can commit the result of the conflict resolution:
        CWS_SRC680_FOO42_ANCHOR: 1.36
+
        cws_src680_foo42: 1.36.0.44
+
  
The first tag (<tt>CWS_SRC680_FOO42_ANCHOR</tt>) is your anchor tag, the second tag (<tt>cws_src680_foo42</tt>) is your branch tag. Note them down.
+
svn resolve --accept=working <file_with_resolved_conflicts>
  
2) Rebase your CVS based CWS to milestone DEV300 m31 with the old CWS tools
+
Other possible conflict resolutions are:
  
  $ cwsresync -m m31 all
+
  svn resolve --accept=theirs_full <file_with_conflicts>
  ... solve conflicts ...
+
  svn resolve --accept=mine_full <file_with_conflicts>
$ cwsresync -c all
+
  
3) Create a patch containing all modules. It is recommend to use the "rdiff" CVS command. A "rdiff" is quite handy for this purpose, because it allows the creation of one patch for all "added" modules. Use the "-u" switch for creating a so called "unified context patch".
+
for taking the un-merged MWS version resp. the un-merged CWS version of the file as conflict resolution.
  
  $ cvs -d <your_tunnel_setup> rdiff -u -rCWS_SRC680_FOO42_ANCHOR -rcws_src680_foo42 `cwsquery modules` > foo42.patch
+
===== Commiting merged changes =====
 +
After resolving possible conflicts, the next step:
 +
  svn up
 +
cws rebase -C <path to the CWS checkout>
  
4) Check the patch for consistency. It should contain only stuff you did on your CWS. Throw out trivial changes.
+
commits the merge into your cws.
  
5) Search the patch for lines which starts with
+
== Subversion Usage Examples ==
  
diff -u /dev/null <some_file>:<some_revision>
+
=== Checking out a milestone ===
 +
Check out a milestone ''DEV300 m32'' with:
  
These files have been added to your CWS. Note the filenames down, you'll need them later.
+
svn checkout svn://svn.services.openoffice.org/ooo/tags/DEV300_m32
  
6) Search the patch for lines which end with <tt>:removed</tt>
+
=== Switching between milestones ===
 +
Switch from milestone ''DEV300_m32'' to ''DEV300_m35'' (saves potentially a lot of checkout time):
  
  diff -u <some_file>:<some_revision> <some_file>:removed
+
  cd DEV300_m32
 +
svn switch svn://svn.services.openoffice.org/ooo/tags/DEV300_m35
 +
cd ..
 +
mv DEV300_m32 DEV300_m35
  
These files have been removed in your CWS. Note the filenames down, you'll need them later.
+
You should then:
  
=====SVN tasks=====
+
dmake clean
  
7) Check out the OOo trunk with
+
before trying to build &mdash; some directory names are hard-coded into the generated build data, and you just changed the name of the directory!
  
$ svn checkout svn+ssh://svn@svn.services.openoffice.org/ooo/trunk my_working_copy
+
=== Checking out a cws ===
 +
Check out a child workspace ''foo'':
  
8) Configure and source the configured script as usual
+
svn checkout svn://svn.services.openoffice.org/ooo/cws/foo
  
$ cd my_working_copy/config_office
+
=== Updating a working copy ===
$ configure
+
Update working copy of ''foo'':
...
+
$ cd ..
+
$ source LinuxX86Env.Set.sh  # YMMV
+
  
9) Create the CWS branch in SVN
+
cd foo
 +
svn update
  
$ cws create --migration -m m32 DEV300 foo42
+
'' Remark: doesn't work. returns the following line: ''
 +
Skipped '.'
  
This command creates the CWS branch in Subversion based on milestone DEV300 m32 and updates the "current milestone" information in EIS. Milestone DEV300 m32 is essentially the same as DEV300 m31 (just a few fixes for SVN and CWS tooling).
+
=== Find out where a working copy originated ===
 +
Find out the base (milestone or cws) of working copy ''wc'':
  
The <tt>--migration</tt> switch tells the <tt>cws create</tt> command that an existing CWS is migrated. Without the switch, EIS will complain that your CWS already exists.
+
cd wc
 +
svn info
  
10) Switch your working copy to your CWS branch
+
=== List milestones/cws ===
 +
List all available milestone and release tags:
  
  $ cd my_working_copy
+
  svn list svn://svn.services.openoffice.org/ooo/tags
$ svn switch svn+ssh://svn@svn.services.openoffice.org/ooo/cws/foo42
+
...
+
$ svn info
+
Path: .
+
URL: svn+ssh://svn@svn.services.openoffice.org/ooo/cws/foo42
+
Repository Root: svn+ssh://svn@svn.services.openoffice.org/ooo
+
Repository UUID: 8da58560-a4e7-4996-a0c2-a735b94b261c
+
...
+
  
Check the URL: line of the output of <tt>svn info</tt>. It should point to your CWS branch. '''Please be extra certain that you never commit anything on trunk.''' You can always check the branch on which you are working with <tt>svn info</tt>.
+
List all available child workspaces:
  
11) Apply the patch
+
svn list svn://svn.services.openoffice.org/ooo/cws
  
$ cd my_working_copy
+
(Probably EIS is better suited for these tasks.)
$ patch -p1 < foo42.diff
+
  
Since DEV300 m31 and DEV300 m32 are almost identical, your patch should apply cleanly. If you get rejects you'll need to fix them manually. The patch tool handles added and removed files quite nicely, the first ones are created by <tt>patch</tt>, the latter ones appear as zero byte sized files in the tree.
+
=== Logs ===
 +
View commit log on a single file:
  
12) Handle added and removed files
+
svn log file.cxx
  
This is pretty straight forward. You need to tell SVN which files have been added or removed by your patch.
+
View only changes on a branch (for example a cws)
$ svn add <list_of_added_files>
+
$ rm <list_of_removed_files>
+
$ svn remove <list_of_removed_files>
+
  
13) Commit the changes to your CWS branch
+
svn log --stop-on-copy file.cxx
  
Review all changes with
+
Include all paths affected by change sets in log command:
$ svn status
+
$ svn diff
+
  
and if everything is OK, commit them to your branch
+
  svn log --verbose file.cxx
  $ svn commit -m"#iXXXXX#: migrate CWS foo42 to SVN."
+
  
Remember, always check that your working copy has been switched to the CWS branch before committing.
+
Attribute blame:
  
=====Do I really need to resync first to DEV300 m31 in CVS? Can I use a later milestone than DEV300 m32 in SVN?=====
+
svn annotate file.cxx
 
+
No and yes resp. If you are certain that your patch applies cleanly or you are prepared to handle the rejects, you can skip the resync part of the recipe or/and start of from a newer SVN based milestone. Working with DEV300 m31 (CVS) and DEV300 m32 (SVN) almost ensures that the patch applies cleanly which is why we recommend to work with them.
+
 
+
== Using plain SVN ==
+
 
=== Showing the differences between a milestone on the master and a cws ===
 
=== Showing the differences between a milestone on the master and a cws ===
 
  $ svn diff http://svn.services.openoffice.org/ooo/tags/DEV300_m32/ http://svn.services.openoffice.org/ooo/cws/os120/
 
  $ svn diff http://svn.services.openoffice.org/ooo/tags/DEV300_m32/ http://svn.services.openoffice.org/ooo/cws/os120/
Line 435: Line 223:
 
  $ svn diff http://svn.services.openoffice.org/ooo/tags/DEV300_m32/sw/source/core  http://svn.services.openoffice.org/ooo/cws/swrefactormarks2/sw/source/core@4711
 
  $ svn diff http://svn.services.openoffice.org/ooo/tags/DEV300_m32/sw/source/core  http://svn.services.openoffice.org/ooo/cws/swrefactormarks2/sw/source/core@4711
 
This compares the cws at revision 4711 to the milestone m32
 
This compares the cws at revision 4711 to the milestone m32
 
+
=== Viewing files modified and changelog entries for all commits to a cws ===
==Tips and tricks==
+
  $ svn log -v --stop-on-copy http://svn.services.openoffice.org/ooo/cws/swrefactormarks2
 
+
=== View a changeset ===
 
+
  $ svn diff -c266422 svn+ssh://svn@svn.services.openoffice.org/ooo
===Ignoring output trees===
+
=== What did a changeset do to the paths in your working copy? ===
 
+
  $ svn diff -c266422
Platform output trees (<tt>unxlngi6, unxsols4, wntmsci12</tt> etc) will show up as unversioned directories marked with a "?" in the output of <tt>svn status</tt> and other SVN commands. This is inconvenient and reduces the usefulness of these commands. In principle it's possible to deal with this in two ways:
+
=== What did a changeset do to the file gtkframe.cxx in your working copy? ===
* attach and commit a <tt>svn:ignore</tt> property to every top level directory listing all possible platforms
+
$ svn diff -c266422 gtkframe.cxx
* add all the platforms which are usually build to the so called global ignore list
+
== Other Subversion Topics ==
 
+
* see [[Setting up Subversion Access]]
Actually the global ignore list is more of a kind of "personal" ignore list which is applied to all svn commandos which access your personal subversion configuration.
+
* see [[SVNMigration|Subversion Migration]]
 
+
Since maintaing <tt>svn:ignore</tt> properties in about 200 directories for about 20 platforms is pretty clumsy, I suggest that we use the global ignore list for this purpose. Here is my personal ignore list, YMMV.
+
 
+
  $ cat $HOME/.subversion/config
+
+
...
+
[miscellany]
+
...
+
global-ignores = common common.pro unxsoli4* unxsols4* unxlngi6* unxlngx6* unxubti8* wntmsci12* unxlngi6* unxmacxi*
+
...
+
 
+
Detailed instructions on how to use ignore lists can be found [http://svnbook.red-bean.com/en/1.5/svn.advanced.props.special.ignore.html here].
+
 
+
===Ignoring contents of .svn when using grep===
+
 
+
To avoid being driven insane by getting grep hits on the .svn dirs contents you can use
+
 
+
  $ export GREP_OPTIONS="--exclude=\*.svn\*"
+
 
+
===Speeding up svn+ssh: access by caching ssh connections===
+
 
+
You might have notice that nearly all SVN operations are somewhat slower via svn+ssh: access than via plain (and read-only) svn: access. This is due to the ssh handshake, some SVN operations even suffer several times from the handshake overhead.
+
 
+
There is an easy and convenient way to get rid of this overhead by using a ssh connection cache.
+
 
+
The following description is taken more or less verbose from the the GCC [http://gcc.gnu.org/wiki/SSH_connection_caching wiki]:
+
 
+
SSH connection caching works with OpenSSH 4.0 on all Unix look alikes, but not on Windows/cygwin. You can check your OpenSSH version with
+
 
+
$ ssh -V
+
OpenSSH_4.6p1, OpenSSL 0.9.8e 23 Feb 2007
+
 
+
Create a <tt>ControlPath</tt> entry for <tt>svn.services.openoffice.org</tt> in <tt>$HOME/.ssh/config</tt>
+
 
+
$ cat $HOME/.ssh/config
+
...
+
Host svn.services.openoffice.org
+
      ControlPath /tmp/ssh_ooo_control
+
...
+
 
+
Set the permissions <tt>0600</tt> on <tt>$HOME/.ssh/config</tt>, otherwise SSH refuses to work.
+
+
$ chmod 0600 $HOME/.ssh/config
+
 
+
Set up up a permanent connection to the ooo SVN server, for example right after login:
+
+
$ ssh -fMN svn@svn.services.openoffice.org
+
 
+
Subsequent svn commands will use the already established connection, resulting in noticeably less lag for short commands. It's also an alternative to using <tt>ssh-agent</tt> if you have protected your private key with a pass phrase.
+
 
+
===Create a OOo repository mirror===
+
 
+
The repository can be replicated with the svnsync tool. No special server side setup is necessary (read-only access is sufficient, please use either the svn: or http: method), but you need to make certain that the target repository can't be modified by other means than svnsync.
+
 
+
* First create an empty target repository:
+
$ svnadmin create /absolute/path/to/rep
+
* Implement the pre-revprop-change and start-commit hooks
+
$ cat /absolute/path/to/rep/hooks/pre-revprop-change
+
<pre>
+
#!/bin/sh
+
 
+
USER="$3"
+
 
+
if [ "$USER" = "syncuser" ]; then exit 0; fi
+
 
+
echo "Only the syncuser user may change revision properties" >&2
+
exit 1
+
</pre>
+
$ cat /absolute/path/to/rep/hooks/start-commit
+
<pre>
+
#!/bin/sh
+
 
+
USER="$2"
+
 
+
if [ "$USER" = "syncuser" ]; then exit 0; fi
+
 
+
echo "Only the syncuser user may commit new revisions" >&2
+
exit 1
+
</pre>
+
 
+
* Initialize the target repository:
+
 
+
  $ svnsync init --username syncuser file:///absolute/path/to/rep svn://svn.services.openoffice.org/ooo
+
 
+
* And finally synchronize the target repository with the source repository
+
 
+
$ svnsync synchronize file:///absolute/path/to/rep
+
 
+
The full details for replicating SVN repositories can be found [[http://svnbook.red-bean.com/en/1.4/svn.reposadmin.maint.html#svn.reposadmin.maint.replication here]].
+
 
+
===Reporting Problems with the Repository===
+
 
+
The list [mailto:dev@tools.openoffice.org dev@tools.openoffice.org] is used to coordinate the initial migration and ongoing work on the repository and related tools. Please raise problems there first.
+
Issues which need the attention of repository administrators should be filed in IssueZilla against the component [http://www.openoffice.org/issues/enter_bug.cgi?component=www&version=current&subcomponent=openoffice.org%20SVN www/openoffice.org SVN].
+
 
+
===Read/Write access with TortoiseSVN===
+
 
+
Please have a look [[Tortoisesvn|at this page]].
+
 
+
[More SVN Tips and tricks will appear here]
+
 
+
==Notes==
+
# {{note|why}}Why not just wait until one of the DSCM systems emerges as a clear front runner? Well, first, this might never happen because each of the mentioned DSCM system emphasizes certain strength, leaving no one clear winner in all categories (ease of use, performance, integration possibilities and platform support). Second, and this is way more important, the OpenOffice.org CWS/CVS system is crumbling under the heavy weight of 8 years worth of OOo coding.
+
 
+
[[Category:SVN]]
+

Latest revision as of 14:03, 17 November 2018

Book-old.png    This article is outdated.    

CWS Tooling

The CWS tooling has been reworked to adapt to SVN. The basic CWS tool is now simply called cws and is invoked as cws <subcommand> in the style of the SVN client, there are no longer separate tools like cwsadd, cwsresync etc etc.

Note: the cws script will probably change over time as we learn how the usage patterns evolve. If you got a problem with the cws script, it might be worthwhile to rebase it to the latest version

$ cd <your_CWS>/ooo/solenv/bin
$ svn merge svn+ssh://svn@svn.services.openoffice.org/ooo/trunk/solenv/bin/cws.pl
$ cd modules
$ svn merge svn+ssh://svn@svn.services.openoffice.org/ooo/trunk/solenv/bin/modules/CwsConfig.pm

The most important change in the way CWSs are handled now is that there is no longer a need nor possibility to add modules. Well, there is still a sw and config_office but all modules of old are now just top level directories, at least as far as SVN is concerned. They still remain a concept of the build system of course.

see CWS Tooling Setup for details on the preparations needed to use the new CWS tooling.

Solving Common Tasks with the CWS Command

Help can be invoked with:

cws help

which yields

cws -- version: 1.1.2.10
usage: cws <subcommand> [options] [args]
Type 'cws help <subcommand>' for help on a specific subcommand.

Available subcommands:
        help (h,?)
        create
        fetch (f)
        rebase (rb)
        analyze (an)
        query (q)
        task (t)
        integrate *** release engineers only ***
        eisclone *** release engineers only ***
help (h, ?): Describe the usage of this script or its subcommands
usage: help [subcommand]

The subcommands do more or less what their CVS predecessors did.

Create a CWS

Create a CWS with the cws create subcommand. Please note that this commands only creates a CWS branch on the OOo server and registers it with EIS. It changes nothing on your hard disk.

Example: create CWS foo on the latest published milestone of master DEV300.

cws create DEV300 foo

Of course you can specify which milestone you want to use, here is the complete command reference:

cws -- version: 1.1.2.10
create: Create a new child workspace
usage: create [-m milestone] <master workspace> <child workspace>
       -m milestone:          Milestone to base the child workspace on. If ommitted the
                              last published milestone will be used.
       --milestone milestone: Same as -m milestone.

Your CWS branch is then available as

svn://svn.services.openoffice.org/ooo/cws/foo


for check out.

Checking out a CWS

$ cws fetch -c foo <workspace name>

Currently this simply checks out your cws foo just as if you had issued the command. <workspace name> specifies the name of the folder where the cws shall be created in.

$ svn checkout svn+ssh://svn@svn.services.openoffice.org/ooo/cws/foo

A milestone can be fetched with

$ cws fetch -m DEV300_m32

this is equivalent to

$ svn checkout svn+ssh://svn@svn.services.openoffice.org/ooo/tags/DEV300_m32

Over time I'll add a number of convenience functions to cws fetch, like configurable partial checkouts, use of prebuild solvers, switching CWSs etc etc.

Please note that if you have already a OOo SVN working copy lying around, you can save considerable checkout time with the svn switch command.

cd <wc>
svn switch svn+ssh://svn@svn.services.openoffice.org/ooo/cws/foo

will fetch the differences between your working copy in <wc> and the CWS foo

Rebasing a CWS

Updating CWS Tooling
Documentation caution.png If your CWS is based on a milestone earlier than DEV300_m36, please upgrade the cws utilities first before attempting to rebase. Utility revisions of m36 or later contain vital fixes.

To upgrade the CWS utilities issue the commands

cd my_working_copy
cd solenv/bin
svn merge svn+ssh://svn@svn.services.openoffice.org/ooo/trunk/solenv/bin/cws.pl@264325
cd modules
svn merge svn+ssh://svn@svn.services.openoffice.org/ooo/trunk/solenv/bin/modules/Cws.pm@264325
svn merge svn+ssh://svn@svn.services.openoffice.org/ooo/trunk/solenv/bin/modules/CwsConfig.pm@264325
Merging changes from master to working copy
Documentation caution.png Always merge into a "clean" working copy:
  • no mixed revisions (svn update *is* mandatory)
  • no locally modified files

The successor of the cwsresync tool is called cws rebase. rebasing is now a two step operation:

export CWS_WORK_STAMP=<name of the CWS>
cws rebase -m latest <path to the CWS checkout>

merge the changes from latest milestone available on the mws into CWS. A REBASE.LOG logfile will be created for your records in the root directory of the repository. A file named REBASE.CONFIG_DONT_DELETE will also be created after successful merging. This file will be needed by the subsequent cws rebase -C command.

Documentation caution.png If you don't see the file named REBASE.CONFIG_DONT_DELETE, that means that the merge was not successfully completed.

Remark: export doesn't work with all shells. Is a special shell mandatory for a rebase to run?

Resolving conflicts

SVN requires you to mark files with conflicts as 'resolved' before you can commit the result of the conflict resolution:

svn resolve --accept=working <file_with_resolved_conflicts>

Other possible conflict resolutions are:

svn resolve --accept=theirs_full <file_with_conflicts>
svn resolve --accept=mine_full <file_with_conflicts>

for taking the un-merged MWS version resp. the un-merged CWS version of the file as conflict resolution.

Commiting merged changes

After resolving possible conflicts, the next step:

svn up
cws rebase -C <path to the CWS checkout>

commits the merge into your cws.

Subversion Usage Examples

Checking out a milestone

Check out a milestone DEV300 m32 with:

svn checkout svn://svn.services.openoffice.org/ooo/tags/DEV300_m32

Switching between milestones

Switch from milestone DEV300_m32 to DEV300_m35 (saves potentially a lot of checkout time):

cd DEV300_m32
svn switch svn://svn.services.openoffice.org/ooo/tags/DEV300_m35
cd ..
mv DEV300_m32 DEV300_m35

You should then:

dmake clean

before trying to build — some directory names are hard-coded into the generated build data, and you just changed the name of the directory!

Checking out a cws

Check out a child workspace foo:

svn checkout svn://svn.services.openoffice.org/ooo/cws/foo

Updating a working copy

Update working copy of foo:

cd foo
svn update

Remark: doesn't work. returns the following line: Skipped '.'

Find out where a working copy originated

Find out the base (milestone or cws) of working copy wc:

cd wc
svn info

List milestones/cws

List all available milestone and release tags:

svn list svn://svn.services.openoffice.org/ooo/tags

List all available child workspaces:

svn list svn://svn.services.openoffice.org/ooo/cws

(Probably EIS is better suited for these tasks.)

Logs

View commit log on a single file:

svn log file.cxx

View only changes on a branch (for example a cws)

svn log --stop-on-copy file.cxx

Include all paths affected by change sets in log command:

svn log --verbose file.cxx

Attribute blame:

svn annotate file.cxx

Showing the differences between a milestone on the master and a cws

$ svn diff http://svn.services.openoffice.org/ooo/tags/DEV300_m32/ http://svn.services.openoffice.org/ooo/cws/os120/

Showing the differences in a module or directory between a milestone on the master and a cws

$ svn diff http://svn.services.openoffice.org/ooo/tags/DEV300_m32/sw  http://svn.services.openoffice.org/ooo/cws/swrefactormarks2/sw

This shows the differences in module sw between the milestone DEV300_m32 (a tagged version in svn-speech) and the most current checkin on cws swrefactormarks2. Since modules are only directories in svn (not in any way special as they where with CVS), this can be used to compare any directory too. For example:

$ svn diff http://svn.services.openoffice.org/ooo/tags/DEV300_m32/sw/source/core  http://svn.services.openoffice.org/ooo/cws/swrefactormarks2/sw/source/core

A specific revision can be compared to the master like this:

$ svn diff http://svn.services.openoffice.org/ooo/tags/DEV300_m32/sw/source/core  http://svn.services.openoffice.org/ooo/cws/swrefactormarks2/sw/source/core@4711

This compares the cws at revision 4711 to the milestone m32

Viewing files modified and changelog entries for all commits to a cws

$ svn log -v --stop-on-copy http://svn.services.openoffice.org/ooo/cws/swrefactormarks2

View a changeset

$ svn diff -c266422 svn+ssh://svn@svn.services.openoffice.org/ooo

What did a changeset do to the paths in your working copy?

$ svn diff -c266422

What did a changeset do to the file gtkframe.cxx in your working copy?

$ svn diff -c266422 gtkframe.cxx

Other Subversion Topics

Personal tools