Stuff:Votorola/revision control system
|
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:
-
Ensure you have Mercurial installed.
-
Create a new working copy from the release trunk:
hg clone http://reluk.ca/var/db/repo/votorola/ WORKThis creates a directory named WORK. You can freely rename it or move it.
-
(programmers only) Test build the code.
-
You may then proceed to modify the files. When you are done, always do a clean build before committing:
votorola/b/build clean releaseThen ‘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
- ^ 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.
