Difference between revisions of "OOo and Subversion"

From Apache OpenOffice Wiki
Jump to: navigation, search
(→‎Server, access methods)
m
 
(102 intermediate revisions by 20 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 mxx 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==
+
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.
  
−
Milestone DEV300 mxx 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 mxx+1. Old code lines, '''including the OOo-3.0 release codeline(OOO300)''' will still be maintained via CVS.
+
<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
 +
$ 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
 +
</div>
  
−
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 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 reasons for choosing the "trunk only" approach were:
+
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.
−
* 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
+
=== Solving Common Tasks with the CWS Command ===
−
* Only modules which have active content in DEV300 mxx 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==
+
Help can be invoked with:
  
−
* subversion-1.5.1 or later
+
cws help
−
* 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
+
which yields
  
−
==Server access methods==
+
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]
  
−
===Read only access===
+
The subcommands do more or less what their CVS predecessors did.
  
−
svn co svn://svn.services.openoffice.org/ooo/trunk
+
==== Create a CWS ====
  
−
or
+
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.
  
−
svn co http://svn.services.openoffice.org/ooo/trunk
+
Example: create CWS ''foo'' on the latest published milestone of master DEV300.
  
−
===Read/write access===
+
cws create DEV300 foo
  
−
Write access to the repository requires a ssh setup.
+
Of course you can specify which milestone you want to use, here is the complete command reference:
  
−
  svn co svn+ssh://svn@svn.services.openoffice.org/ooo/trunk
+
  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.
  
−
==Ssh setup==
+
Your CWS branch is then available as
  
−
==CWS tooling==
+
svn://svn.services.openoffice.org/ooo/cws/foo
  
−
==Tips and tricks==
 
  
−
==Notes==
+
for check out.
−
# {{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.
+
 
 +
==== 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 <tt>cws fetch</tt>, 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 =====
 +
{{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.}}
 +
 
 +
To upgrade the CWS utilities issue the commands
 +
 
 +
<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>
 +
 
 +
===== 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}}
 +
 
 +
The successor of the <tt>cwsresync</tt> tool is called <tt>cws rebase</tt>. 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 <code>cws rebase -C</code> command.
 +
 
 +
{{Warn| 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 &mdash; 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 ==
 +
* see [[Setting up Subversion Access]]
 +
* see [[SVNMigration|Subversion Migration]]

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

Retrieved from "https://wiki.openoffice.org/w/index.php?title=OOo_and_Subversion&oldid=244370"
Personal tools