View source for Stuff:Votorola/revision control system

{| align='right'
| __TOC__
|}
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 [http://reluk.ca/var/db/repo/votorola/ repository web interface] (with revision history), or the snapshot [http://reluk.ca/project/votorola/ source directory] (without).

==Quick Start==

To obtain a working copy of the project files:
<ol>
    <li>
        <p>
            Ensure you have [http://www.selenic.com/mercurial/wiki/ Mercurial] installed.
            </p>
        </li>
    <li>
        <p>
            Create a new working copy from the release trunk:
            </p>
        <div class='indent'><code>hg clone <nowiki>http://reluk.ca/var/db/repo/votorola/</nowiki> <var>WORK</var></code></div>
        <p>
            This creates a directory named <var>WORK</var>.
            You can freely rename it or move it.
            </p>
        </li>
    <li>
        <p>
            <em>(programmers only)</em>
            [http://reluk.ca/project/votorola/b/instructions.xht Test build] the code.
            </p>
        </li>
    <li>
        <p>
             You may then proceed to modify the files.
             When you are done, always do a clean build before committing:
            </p>
        <div class='indent'><code>votorola/b/build clean release</code></div>
        <p>
             Then &#x2018;hg commit&#x2019; to permanently record your changes
             in the working copy's repository.<ref>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.</ref>
            </p>
        </li>
    </ol>

You may then share your work, either by publishing it to the Web using &#x2018;hg serve&#x2019; or &#x2018;hgweb.cgi&#x2019;; or by email using &#x2018;hg bundle&#x2019;.  If you make improvements, please send your repo URI (or bundle) to the [http://reluk.ca/contact.xht 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 <code>TortoiseHg-0.8.1-hg-1.3.1.exe</code>.

''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 <code>hg version</code>:

<pre>
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.
    </pre>

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":

<pre>
; 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
    </pre>

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

  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:

<pre>
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
    </pre>

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

<pre>
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</pre>

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:

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

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

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

<pre>
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.
    </pre>

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

===Committing and sharing changes===

When you are finished, use <code>hg commit</code> to record a new changeset:

  C:\tmp\WORK>hg commit

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

<pre>
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 &lt;me@somewhere.com&gt;
HG: branch 'default'
HG: changed votorola/a/locale/A.properties
  </pre>

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:

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

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:

<pre>
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
    </pre>

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 <code>hg update</code> will fail.
In that case, see: http://mercurial.selenic.com/wiki/TutorialConflict

==Notes==
<references/>