Difference between revisions of "Mercurial/Cws"

From Apache OpenOffice Wiki
Jump to: navigation, search
(Method A)
 
(18 intermediate revisions by 7 users not shown)
Line 1: Line 1:
 
{{Mercurial}}
 
{{Mercurial}}
This page discusses the Mercurial part of handling child workspaces (CWSs). It assumes some basic Mercurial knowledge which you can find [[OOo and Mercurial|here]].
+
This page discusses the Mercurial part of handling child workspaces (CWSs). It assumes some basic Mercurial knowledge which you can find at the [[Mercurial/Getting Started|Getting Started Page]].
  
 
= The OpenOffice.org repository setup =
 
= The OpenOffice.org repository setup =
Line 14: Line 14:
 
== Creating the child workspace in EIS ==
 
== Creating the child workspace in EIS ==
  
Create child workspace with name foo42, latest available milestone:
+
You need to have the Perl <tt>SOAP::Lite</tt> module installed for <code>cws create</code> to work.  See [[CPAN install]] page for how to install Perl modules.
  
  $ cws create --hg DEV300 foo42
+
{{Note|On a Debian/Ubuntu based distribution install the <tt>libsoap-lite-perl</tt> package:
 +
  sudo aptitude install libsoap-lite-perl
 +
}}
 +
Create a CWS config file <code>$HOME/.cwsrc</code> following [[.cwsrc| these instructions]]
  
This command will register CWS ''foo42'' with EIS and set its SCM property to Mercurial. An 'outgoing' repository will be created (this may take up to one hour) on the SCM server where you can publish your changes.
+
Create child workspace with name <code>foo42</code>, latest available milestone:
  
{{Template:Documentation/Note| ''cws create'' will in future default to hg, obsoleting the ''--hg'' switch - as soon as we get rid of SVN for the OOO310 and OOO320 codelines.}}
+
$ cws create DEV300 foo42
 +
 
 +
This command will register CWS ''foo42'' with EIS and set its SCM property to Mercurial. An 'outgoing' repository will be created (this may take up to one hour) on the SCM server where you can publish your changes.
  
 
As an alternative way you can use the EIS web fronted to create the CWS and set it to status 'new'. Don't forget to set the SCM property to 'HG'.
 
As an alternative way you can use the EIS web fronted to create the CWS and set it to status 'new'. Don't forget to set the SCM property to 'HG'.
Line 35: Line 40:
 
Clone your working tree from the pristine local copy
 
Clone your working tree from the pristine local copy
 
   
 
   
  $ hg clone -r <current_cws_milestone> <local_pristine_copy> foo42
+
  $ hg clone <local_pristine_copy> foo42
 +
 
 +
{{Warn|''' Note the above is valid only for a new created cws, not for older cws!''' This is because the above command will clone the cws up to the current head of the master. This might not be what you want when you want to work on an existing cws currently based on an older milestone, because in that case you would need to merge changes from the master immediately (what once was a "cws rebase"). So when you need a working copy of an older cws and dont want to merge the newest changes on the master use:
 +
 
 +
<code>$ hg clone -r <current_cws_milestone> <local_pristine_copy> foo42</code>.
 +
 
 +
For more information see the [[Mercurial/Tips And Tricks|Tips And Tricks Section]].}}
  
 
Change the default push location to the OOo SCM server
 
Change the default push location to the OOo SCM server
Line 50: Line 61:
 
If there is a proper ''$HOME/.cwsrc'' configuration (see below), you can use the ''cws fetch'' command.
 
If there is a proper ''$HOME/.cwsrc'' configuration (see below), you can use the ''cws fetch'' command.
  
{{Template:Documentation/Note| Use the version of ''cws fetch'' which comes with DEV300 m63 or later. }}
+
{{Note| Use the version of ''cws fetch'' which comes with DEV300 m63 or later. }}
  
 
  $ cws fetch -c foo42 foo42
 
  $ cws fetch -c foo42 foo42
  
{{Template:Documentation/Caution| Make sure that either your local source contains the used milestone *or* the 'outgoing' repository is already available on the server. Otherwise you might base your working tree on an older milestone. If this happened, just do a pull/update from http://hg.services.openoffice.org/DEV300}}
+
{{Warn| Make sure that either your local source contains the used milestone *or* the 'outgoing' repository is already available on the server. Otherwise you might base your working tree on an older milestone. If this happened, just do a pull/update from http://hg.services.openoffice.org/DEV300}}
  
 
The ''cws fetch'' command adds the default-push location and a hook (prevents the commit of CR/LF in changed files), no need to configure this by hand.
 
The ''cws fetch'' command adds the default-push location and a hook (prevents the commit of CR/LF in changed files), no need to configure this by hand.
Line 64: Line 75:
 
  $ hg commit -m"foo42: #i4711#: implement feature foo" foo.cxx
 
  $ hg commit -m"foo42: #i4711#: implement feature foo" foo.cxx
  
{{Template:Documentation/Caution| Remember, ''hg commit'' will search the whole tree for to be committed changes if no file/directory is specified.}}
+
{{Warn| Remember, ''hg commit'' will search the whole tree for to be committed changes if no file/directory is specified.}}
  
{{Template:Documentation/Note| Why the name of the CWS in front of the first commit message line? This way we can immediately see which CWS was the origin of a changeset when browsing the history.}}
+
{{Note| Why the name of the CWS in front of the first commit message line? This way we can immediately see which CWS was the origin of a changeset when browsing the history.}}
  
{{Template:Documentation/Tip| Make the first line of your commit message concise and stand alone (like an email subject). This will make for a far better browseable history in the long run. See [http://mercurial.selenic.com/wiki/ChangeSetComments] why.}}
+
{{Tip| Make the first line of your commit message concise and stand alone (like an email subject). This will make for a far better browseable history in the long run. See [http://mercurial.selenic.com/wiki/ChangeSetComments] why.}}
  
 
== Publishing changes ==
 
== Publishing changes ==
Line 78: Line 89:
 
If the repository ''hgrc'' has the correct "default-push" entry, the URL can be omitted.
 
If the repository ''hgrc'' has the correct "default-push" entry, the URL can be omitted.
  
{{Template:Documentation/Caution| If someone else pushed changes to the outgoing repository, ''hg push'' might tell you that your push would create a new head and abort. It's possible to override the abort with the'' -f (--force)'' switch. '''Never''' do this. Just pull the changesets in question, merge them and than push the combined result.}}
+
{{Warn| If someone else pushed changes to the outgoing repository, ''hg push'' might tell you that your push would create a new head and abort. It's possible to override the abort with the'' -f (--force)'' switch. '''Never''' do this. Just pull the changesets in question, merge them and then push the combined result.}}
  
{{Template:Documentation/Note| If you are inclined to fake^H^H^H^Hbeautify the commit history, do it before pushing your changesets to the outgoing repository. Once there, your changesets are published and thus should never be meddled with.}}
+
{{Note| If you are inclined to fake^H^H^H^Hbeautify the commit history, do it before pushing your changesets to the outgoing repository. Once there, your changesets are published and thus should never be meddled with.}}
  
 
==Merge changes from the latest milestone in to the CWS==
 
==Merge changes from the latest milestone in to the CWS==
Line 139: Line 150:
 
HG_REMOTE_SOURCE=http://hg.services.openoffice.org
 
HG_REMOTE_SOURCE=http://hg.services.openoffice.org
 
</pre>
 
</pre>
 +
 +
See [[.cwsrc]] for a complete configuration file.
 +
 
[[Category:CWSTooling]]
 
[[Category:CWSTooling]]

Latest revision as of 09:01, 16 July 2018

Mercurial.png

Mercurial

Quick Navigation

About this template


This page discusses the Mercurial part of handling child workspaces (CWSs). It assumes some basic Mercurial knowledge which you can find at the Getting Started Page.

The OpenOffice.org repository setup

The OpenOffice.org Mercurial repository is huge, it contains more than 260000 changesets and exceeds 1 GiB in size. Repeatably exchanging this vast numbers of changesets over the Net is prohibitive and wasteful. It's also not necessary. We were careful to employ a setup which is designed to minimize the number of changesets exchanged over the Net. The basic idea is to create a so called 'outgoing' repository for each CWS on the main OOo SCM server. The 'outgoing' repository already has each changeset up to and including the milestone the CWS was created on. It is meant as the main collaboration point around the child workspace and is also the place where release engineering will fetch a child workspace when it's ready for integration.

OpenOffice.org repository setup

Workflow

The workflow is best explained with an example:

Creating the child workspace in EIS

You need to have the Perl SOAP::Lite module installed for cws create to work. See CPAN install page for how to install Perl modules.

Documentation note.png On a Debian/Ubuntu based distribution install the libsoap-lite-perl package:
sudo aptitude install libsoap-lite-perl

Create a CWS config file $HOME/.cwsrc following these instructions

Create child workspace with name foo42, latest available milestone:

$ cws create DEV300 foo42

This command will register CWS foo42 with EIS and set its SCM property to Mercurial. An 'outgoing' repository will be created (this may take up to one hour) on the SCM server where you can publish your changes.

As an alternative way you can use the EIS web fronted to create the CWS and set it to status 'new'. Don't forget to set the SCM property to 'HG'.

Preparing the working tree

Method A

Make sure that your local pristine copy contains the latest milestone.

$ cd <local_pristine_copy>
$ hg pull http://hg.services.openoffice.org/DEV300

Clone your working tree from the pristine local copy

$ hg clone <local_pristine_copy> foo42
Documentation caution.png Note the above is valid only for a new created cws, not for older cws! This is because the above command will clone the cws up to the current head of the master. This might not be what you want when you want to work on an existing cws currently based on an older milestone, because in that case you would need to merge changes from the master immediately (what once was a "cws rebase"). So when you need a working copy of an older cws and dont want to merge the newest changes on the master use:
$ hg clone -r <current_cws_milestone> <local_pristine_copy> foo42.

For more information see the Tips And Tricks Section.

Change the default push location to the OOo SCM server

$ echo 'default-push=ssh://hg@hg.services.openoffice.org/cws/foo42' >> foo42/.hg/hgrc

If there are already changes in the outgoing repository pull them into your working tree

$ cd foo42
$ hg pull -u http://hg.services.openoffice.org/cws/foo42

Method B

If there is a proper $HOME/.cwsrc configuration (see below), you can use the cws fetch command.

Documentation note.png Use the version of cws fetch which comes with DEV300 m63 or later.
$ cws fetch -c foo42 foo42
Documentation caution.png Make sure that either your local source contains the used milestone *or* the 'outgoing' repository is already available on the server. Otherwise you might base your working tree on an older milestone. If this happened, just do a pull/update from http://hg.services.openoffice.org/DEV300

The cws fetch command adds the default-push location and a hook (prevents the commit of CR/LF in changed files), no need to configure this by hand.

Commit changes

Not much to be said here. Please format the first line of the commit message according to the example below:

$ hg commit -m"foo42: #i4711#: implement feature foo" foo.cxx
Documentation caution.png Remember, hg commit will search the whole tree for to be committed changes if no file/directory is specified.
Documentation note.png Why the name of the CWS in front of the first commit message line? This way we can immediately see which CWS was the origin of a changeset when browsing the history.
Tip.png Make the first line of your commit message concise and stand alone (like an email subject). This will make for a far better browseable history in the long run. See [1] why.


Publishing changes

Committing changes just does add them to your local repository. For publishing your changes to the OOo developer community just push them to the 'outgoing' repository.

$ hg push ssh://hg@hg.services.openoffice.org/cws/foo42

If the repository hgrc has the correct "default-push" entry, the URL can be omitted.

Documentation caution.png If someone else pushed changes to the outgoing repository, hg push might tell you that your push would create a new head and abort. It's possible to override the abort with the -f (--force) switch. Never do this. Just pull the changesets in question, merge them and then push the combined result.
Documentation note.png If you are inclined to fake^H^H^H^Hbeautify the commit history, do it before pushing your changesets to the outgoing repository. Once there, your changesets are published and thus should never be meddled with.

Merge changes from the latest milestone in to the CWS

Updating your CWS to the latest milestone is easier and by *far* faster than with CVS and SVN.

First pull the latest changes from DEV300 into your CWS

$ cd foo42
$ hg pull http://hg.services.openoffice.org/DEV300
$ hg merge

Often enough the merge might result in conflicts. You can list the merged files with and without conflicts with

$ hg resolve -l

Once a conflict is fixed mark the corresponding file as resolved

$ hg resolve -m <conflicted_file>

To start over with the merge process (this will loose all your conflict resolutions up to now!!!)

$ hg resolve -a

When every conflict is resolved commit the result of the merge

$ hg commit -m"foo42: merge with DEV300 m60"

When you are satisfied with merge don't forget to bump up the milestone in EIS

$ hg push ssh://hg@hg.services.openoffice.org/cws/foo42
$ cws setcurrent -m m60

The milestone can also be changed via EIS web front end.

Don't know which was the latest milestone? Find out with

$ cws query latest

Integration

When the CWS is nominated, RE will take the changesets from the 'outgoing' repository. Obviously at this point in time latest your changesets must be published there.

RE might ask you to update your CWS again if there are to many conflicts. Just do another pull/merge/resolve/commit/push cycle then.

Configuring cws fetch

cws fetch can be configured to make use of LOCAL (means: on the same disk) and LAN resources for fast clone operations.

Simply add and configure the following entries in your $HOME/.cwsrc

# Directory where pristine copies of OOo master workspaces (ie. DEV300) are kept on the local disk
# HG_LOCAL_SOURCE=
# Example:
HG_LOCAL_SOURCE=/export/hg_clean

# URL where pristine copies of OOo master workspaces (ie. DEV300) are available in a LAN
# HG_LAN_SOURCE=
# Example:
HG_LAN_SOURCE=http://myserver.example.com:8000/

# The OOo SCM server
HG_REMOTE_SOURCE=http://hg.services.openoffice.org

See .cwsrc for a complete configuration file.

Personal tools