Mercurial/Setup

From Apache OpenOffice Wiki
Jump to: navigation, search

Mercurial.png

Mercurial

Quick Navigation

About this template


Installing Mercurial

Mercurial source and binary distributions are available at the Mercurial Wiki. Many Linux distributions, OpenSolaris and cygwin (Windows) offer Mercurial packages as well. Installing from source requires a working Python installation. Windows users have the choice between a cygwin based Mercurial and TortoiseHg, the latter one "is an all-inclusive Mercurial binary installer package for Windows".

Documentation caution.png Some cygwin versions exhibit a bug which affects hg and other tools. If your cygwin hg complains about: "*** fatal error - could not load shell32, Win32 error 487" use TortoiseHg instead.


SSH Authentication

Domain developers can publish their changes on hg.services.openoffice.org. If you are not a domain developer or do not plan to publish your changes via this way to the OOo community just skip this section. Mercurial is a distributed SCM, there are other ways to contribute your changes without having write access to this server.

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 $HOME/.ssh/id_dsa.pub.

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 

Initial Migration of Keys

All existing public keys for SVN usage have been migrated for Mercurial use as well. If you are a new domain developer please create a new issue, attach your public key to it and and add it as a dependency to issue 94002.

Ongoing Maintenance

We will continue to use IssueZilla for managing and tracking key additions and changes. Please see Submitting Your Certificate (Public Key).


Configuring Mercurial

Mercurial can be configured via system, user and repository configure files. The most interesting one is the user specific configuration file in $HOME/.hgrc. Example:

[ui]
# The user name will appear as author tag on commits.
username=Joe Developer <jdeveloper@openoffice.org>
# Domain developers only: OOo ssh authentication for pushing 
# to 'outgoing' repositories.
ssh=ssh -C -i <path_to_OOo_ssh_identity>

[extensions]
# Required if 'cws fetch' is used to fetch a CWS.
hgext.mq=
# Enables the bundled win32text extension. See [hooks] section.
hgext.win32text=

[hooks]
# Reject commits which would introduce windows-style CR/LF.
# Enabling this hook is strongly suggested for OOo development.
pretxncommit.crlf = python:hgext.win32text.forbidcrlf

Let's examine this configuration file entry for entry:

[ui]
username=Joe Developer <jdeveloper@openoffice.org>

The author tag of a changeset is set on commit, and becomes part of the history. Set this entry to identify yourself as author, common usage is to use your name and the OOo email address here.

Tip.png It's possible to use other email addresses than the OOo one, but in this case please add your OOo account in square braces. Example: "Joe Developer [jdeveloper] <joe@example.com>". It must always be possible to relate a contribution with an OOo account, the contribution will be rejected otherwise. If you are absolutely not comfortable with disclosing your real name it's possible to use a pseudonym or just your account name instead, but be reasonable.


[ui]
ssh=ssh -C -i <path_to_OOo_ssh_identity>

OOo domain developers can create "child workspaces", which are effectively public feature branches. Publishing changes on hg.services.openoffice.org requires SSH access, which is configured here. Be sure to use a compressed ssh connection (-C).

[extensions]
hgext.mq=
hgext.win32text=

Mercurial supports a huge number of useful extensions, many of them come bundled. Enable here whatever you want to use. The 'mq' extension is required if you want to use the 'cws fetch' tool since it makes use of 'hg strip' which is part of the 'mq' extension. The 'win32text' extension is strongly suggested for all OOo developers who work on windows at least occasionally, it provides a hook which prevents you from committing files with CR/LF in them.

[hooks]
pretxncommit.crlf = python:hgext.win32text.forbidcrlf

This is one of the hooks provided by 'win32text'. Disable it on the peril of aggravating the whole OOo developer community.

Personal tools