Stuff:Votorola/revision control system

From Wiki
Jump to: navigation, search

Contents

Votorola's revision control system is Mercurial. It stores the source code for the pollserver, trustserver, difference bridge, and so forth. This page explains how to use it. If you only want to browse the project files, please use either the repository web interface (with revision history), or the snapshot source directory (without).

Quick Start

To obtain a working copy of the project files:

  1. Ensure you have Mercurial installed.

  2. Create a new working copy from the release trunk:

    hg clone http://reluk.ca/var/db/repo/votorola/ WORK

    This creates a directory named WORK. You can freely rename it or move it.

  3. (programmers only) Test build the code.

  4. You may then proceed to modify the files. When you are done, always do a clean build before committing:

    votorola/b/build clean release

    Then ‘hg commit’ to permanently record your changes in the working copy's repository.1

You may then share your work, either by publishing it to the Web using ‘hg serve’ or ‘hgweb.cgi’; or by email using ‘hg bundle’. If you make improvements, please send your repo URI (or bundle) to the maintainer for inclusion in the next release.

Mercurial on Windows

This is a walkthrough for Windows users. It explains how to set up and use the revision control system. It was last tested with TortoiseHg, installer version TortoiseHg-0.8.1-hg-1.3.1.exe.

For Unix users, there is no separate walkthrough. please skip the setup section, and continue from there.

Setting up for Windows

Install TortoiseHg and restart Windows as prompted. Verify that Mercurial is correctly installed by opening a command window (DOS box), and typing hg version:

C:\tmp>hg version
Mercurial Distributed SCM (version 1.3.1)

Copyright (C) 2005-2009 Matt Mackall <mpm@selenic.com> and others
This is free software; see the source for copying conditions. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
    

Use your favourite editor to create a user configuration file for Mercurial.

 C:\tmp>notepad %UserProfile%\Mercurial.ini

Paste in the content below, substituting an appropriate username for "MY NAME":

; User Mercurial config file.  The developer warns:
;
;   Note: do not change the encode or decode filter settings 
;   while you have files checked out - use hg update null 
;   to remove any working files first. [Or just delete the
;   working copies - MCA]
;
;   http://mercurial.selenic.com/wiki/Win32TextExtension

[ui]

; editor used to enter commit logs, etc.  Most any text editor
; will suffice.
editor = notepad
username = MY NAME <me@somewhere.com>


[extensions]

; For more information about mercurial extensions, start here
; http://www.selenic.com/mercurial/wiki/index.cgi/UsingExtensions

; To use cleverencode/cleverdecode or dumbencode/dumbdecode,
; you must enable win32text extension.  Without this you will
; not see the proper line breaks in the files (Votorola's files
; are in Unix format).
win32text =

; By default, we try to encode and decode all files that do not
; contain ASCII NUL characters.  What this means is that we try to set
; line endings to Windows style on update, and to Unix style on
; commit.  This lets us cooperate with Linux and Unix users, so
; everybody sees files with their native line endings.

[encode]
; Encode files that don't contain NUL characters.

** = cleverencode:

; Alternatively, you can explicitly specify each file extension that
; you want encoded (any you omit will be left untouched), like this:

; *.txt = dumbencode:


[decode]
; Decode files that don't contain NUL characters.

** = cleverdecode:

; Alternatively, you can explicitly specify each file extension that
; you want decoded (any you omit will be left untouched), like this:

; **.txt = dumbdecode:

[patch]
; If you enable win32text filtering, you will want to enable this
; line as well to allow patching to work correctly.

eol = crlf
    

Save the file, and use hg showconfig to verify that Mercurial is now configured for cleverencode/decode:

 C:\tmp>hg showconfig
 decode.**=cleverdecode:
 encode.**=cleverencode:
 extdiff.cmd.vdiff=C:\Program Files\TortoiseHg\kdiff3
 extensions.extdiff=
 extensions.win32text=
 merge-tools.kdiff3.priority=-1
 merge-tools.kdiff3.args=-L1 base --L2 local --L3 other $base $local $other -o $output
 merge-tools.kdiff3.regkey=Software\KDiff3
 merge-tools.kdiff3.regappend=\kdiff3.exe
 merge-tools.kdiff3.fixeol=True
 merge-tools.kdiff3.gui=True
 merge-tools.beyondcompare3.priority=-2
 merge-tools.beyondcompare3.args=$local $other $base $output /ro /lefttitle=local /centertitle=base /righttitle=other /au
 tomerge /reviewconflicts /solo
 merge-tools.beyondcompare3.regkey=Software\Scooter Software\Beyond Compare 3
 merge-tools.beyondcompare3.regname=ExePath
 merge-tools.beyondcompare3.gui=True
 merge-tools.diffmerge.priority=-7
 merge-tools.diffmerge.args=--nosplash --merge --title1=base --title2=local --title3=other $base $local $other
 merge-tools.diffmerge.checkchanged=True
 merge-tools.diffmerge.gui=True
 merge-tools.p4merge.priority=-8
 merge-tools.p4merge.args=$base $local $other $output
 merge-tools.p4merge.regkey=Software\Perforce\Environment
 merge-tools.p4merge.regname=P4INSTROOT
 merge-tools.p4merge.regappend=\p4merge.exe
 merge-tools.p4merge.gui=True
 merge-tools.tortoisemerge.priority=-9
 merge-tools.tortoisemerge.args=/base:$output /mine:$local /theirs:$other /merged:$output
 merge-tools.tortoisemerge.regkey=Software\TortoiseSVN
 merge-tools.tortoisemerge.gui=True
 merge-tools.winmergeu.regkey=Software\Thingamahoochie\WinMerge\
 merge-tools.winmergeu.regname=Executable
 merge-tools.winmergeu.priority=-10
 merge-tools.winmergeu.args=/e /ub /dl other /dr local $other $local $output
 merge-tools.winmergeu.fixeol=True
 merge-tools.winmergeu.gui=True
 patch.eol=crlf
 ui.ssh="C:\Program Files\TortoiseHg\TortoisePlink.exe" -ssh -2
 ui.editor=notepad
 ui.username=MY NAME <me@somewhere.com>

Working with the source files

Obtain a working copy by cloning another repository. For example, clone the maintainer's repository:

C:\tmp>hg clone http://reluk.ca/var/db/repo/votorola/ WORK
requesting all changes
adding changesets
adding manifests
adding file changes
added 252 changesets with 4708 changes to 1056 files
updating working directory
602 files updated, 0 files merged, 0 files removed, 0 files unresolved
    

You now have a directory named WORK, which you may freely move or rename.

C:\tmp>dir
 Volume in drive C has no label.
 Volume Serial Number is 3014-F2FA

 Directory of C:\tmp

2009-09-06  09:16 PM    <DIR>          .
2009-09-06  09:16 PM    <DIR>          ..
2009-09-06  02:32 AM    <DIR>          WORK
               0 File(s)              0 bytes
               3 Dir(s)  24,424,587,264 bytes free

Change to that directory.

 C:\tmp>cd WORK

Verify that the files are unmodified. You should see no output from the following command:

 C:\tmp\WORK>hg status

Modify one of the source files, and try again:

C:\tmp\WORK>notepad votorola\a\locale\A.properties

C:\tmp\WORK>hg status
M votorola\a\locale\A.properties
    

This says that a single file A.properties was modified. Use the hg diff command to see the details:

C:\tmp\WORK>hg diff
diff -r d479e1f89910 votorola/a/locale/A.properties
--- a/votorola/a/locale/A.properties    Sat Sep 05 22:44:24 2009 -0400
+++ b/votorola/a/locale/A.properties    Sun Sep 06 01:51:27 2009 -0400
@@ -153,6 +153,8 @@
     a.register.trust.edgeBarPredictionNone = OK, no bar is likely.  The trust edge \
         appears to be acceptable for inclusion in the voter list, whenever it is next compiled.

+# test mod from Windows - MCA
+
     a.register.trust.edgeBarPredictionUnknown(1) = Bar unknown.  \
         Whether or not this trust edge (to voter %s) is acceptable for inclusion in the voter list \
         cannot be predicted at this time.  The problem is as follows.
    

Continue working until you are happy with the changes, and wish to commit them permanently.

Committing and sharing changes

When you are finished, use hg commit to record a new changeset:

 C:\tmp\WORK>hg commit

The editor window opens. Enter a brief description of the changes. For example:

Test mod from Windows.

HG: Enter commit message.  Lines beginning with 'HG:' are removed.
HG: Leave message empty to abort commit.
HG: --
HG: user: MY NAME <me@somewhere.com>
HG: branch 'default'
HG: changed votorola/a/locale/A.properties
  

Don't worry about the HG lines, they won't be part of the description. Save the editor window, and your changes are recorded. Your working copy is now considered unmodified, and there should be no output from the following command:

 C:\tmp\WORK>hg status

Create a changeset bundle. This is one way to share changes, and it works regardless of setup. Specify the name of the bundle file, and the intended destination:

    C:\tmp\WORK>hg bundle \tmp\changes.hg http://reluk.ca/var/db/repo/votorola/
    searching for changes
    1 changesets found
    

In this case, the bundle is intended for the maintainer's repository. Mercurial figures out that the maintainer's repository is missing only 1 changeset, so that's all it puts into the bundle. You can now use Windows file explorer to right-click on the bundle file, and choose:

 Send to | Mail Recipient

The email address of the repository owner is usually shown in the Web interface of the repository:

 http://reluk.ca/var/db/repo/votorola/

Keeping in sync with others

To keep in sync with other contributors, you pull changesets from their repositories. The simplest way to keep in sync with the overall project is to pull from the maintainer's repository:

C:\tmp\WORK>hg pull http://reluk.ca/var/db/repo/votorola/
pulling from http://reluk.ca/var/db/repo/votorola/
searching for changes
adding changesets
adding manifests
adding file changes
added 1 changesets with 1 changes to 1 files
(run 'hg update' to get a working copy)

C:\tmp\WORK>hg update
1 files updated, 0 files merged, 0 files removed, 0 files unresolved
    

The changes are automatically merged with any uncommitted modifications in your own working copy.

Ordinarily that's all there is to it. Occasionally there may be a conflict that prevents an automatic merge, and the hg update will fail. In that case, see: http://mercurial.selenic.com/wiki/TutorialConflict

Notes

  1. ^ You are prompted for a commit message. Use a short, stand-alone summary for the first line because it will be extracted for the logs.