The website svgwg.org is purely used as a staging server for the SVG WG's Mercurial repositories. This is to work around the lack of support for Mercurial hooks (see below) on dvcs.w3.org. The official location of the WG's Mercurial repositories remains dvcs.w3.org.
Anyone can clone the repositories in svgwg.org/hg, but only working group members who have had their SSH keys added to the server may push to svgwg.org. To have their key added, WG members should send their SSH public key (that's the file ending in .pub!) to Cameron.
Cloning a repository from svgwg.org
If you intend on creating a clone from which you will push changes back to svgwg.org, you should clone using an ssh:// URL (instead of the https:// URL) and use the username 'svgwg'. For example, to clone the 'svg2' repo you'd use:
hg clone ssh://email@example.com/hg/svg2 local/path/svg2
Everyone must use the username 'svgwg' - your key provides your real identity to the server once your connection passes through ssh.
Refer to the full list of repositories, for most tasks you will only need to clone the svg2 and svg2-tools repositories.
To build the spec, you will need a Unix-like environment. cygwin on Windows will work. You also specifically need the following tools installed:
- node (nodejs on Fedora... the 'node' package is a Ham radio thing!)
- ssh (this is in the openssh package on cygwin)
If you are on cygwin, then you will need to ensure that node is in your path. You can do this by adding this to the end of your
.bash_profile file in your cygwin home directory:
export PATH="$PATH:/cygdrive/c/Program Files/nodejs"
Unlike the CVS repository, the svg2 repository does not contain any generated files. Please do not add and commit generated files without full discussion at a WG meeting.
To build the published version of the spec from the master files in svg2, get a copy of svg2 and svg2-tools (see above for cloning) and put them side-by-side in a directory. Now in svg2, simply run the normal "make" command as you would have done for SVG 1.1.
By default, the Makefile will check to ensure that you have the latest revision of the svg2-tools repository. If you do not, it will refuse to build, and you will need to update. (If checking the latest revision of the remote svg2-tools repository fails for whatever reason, for example if you are not connected to the network, then the build will proceed.) If you need to skip this check for some reason, running "make all" will build the spec immediately.
The spec normally references some style sheets that are on www.w3.org. If you are somewhere without network (like on an aeroplane) then you can build with references to a local version of the W3C TR style sheets by setting the environment variable SVG_BUILD_LOCAL_STYLE_SHEETS to anything, for example:
$ SVG_BUILD_LOCAL_STYLE_SHEETS=1 $ make ...
Before making changes, be aware that there are some automated checks in place on svgwg.org that will block your changes if they fail those checks. See the Hooks section below. Some of the more experienced Mercurial users in the WG can help you if your changes get blocked - don't stress it.
Other than that, you just commit and push your changes as you would to any Mercurial repository.
As an example, to add a new file:
- Create file in your local HG directory.
- hg add Mark file to be added to local repository.
- hg commit Commit file to your local repository.
- hg outgoing Verify what is going to be pushed.
- hg push Push change to swgwg.org.
- hg push --rebase Push change to swgwg.org if you comitted before pull.
Other useful commands:
- hg status List changed files in the working directory and files not in the HG repository.
- hg diff Show differences between the working directory and the repository.
- hg log Show history of repository.
- hg pull Pulls changes from svghg.org into your local repository (but not local directory).
- hg update Updates local directory to local repository.
Mercurial hooks are user supplied Python functions or shell commands that Mercurial can be made to executed when certain operations are carried out on a repository. For example, a user could provide a Python script to send out a notification email, and tell Mercurial to execute this hook every time someone pushes new changesets into the repository.
The hooks currently implemented and actually in use on svgwg.org are managed in the svg-repo-hooks repository. These hooks can be changed as the WG decides, but currently they:
- check that the pushed changes can be built into the published form of the spec without errors
- automatically publish an updated editor's draft
- check that pushed changesets do not unwittingly change the line endings of files (which would trash the diff and render hg annotate/blame useless for those files)
- check that the commit message for each changeset contains the string "r=<user>" or "NOREVIEW"
- check that the "user" for (author of) each changeset is in the form "name <email>"
- log the identity of the person pushing changesets
This is just a first pass. We could do many other useful things such as:
- automatically push successful pushes to svgwg.org up to dvcs.w3.org
- check that the "user" for (author of) each changeset is a known contributor who has agreed to assigned copyright to the W3C
- check that users are using their company (not personal) email address when creating changesets
- check that pushes don't add unintended unmerged heads
- send out a notification email when new changesets are added
- run tests
The hooks repository can be changed by any WG member with push access to the server, but please check with other WG members before making changes, and please, please test your changes before you push.
New repositories can be added to svgwg.org simply by cloning them up to the server. The hg-sandbox directory is specifically intended to allow WG members to practice using hg, test changes, or share repositories, all without messing with the normal 'hg' directory. For example, to add a repository at svgwg.org/hg-sandbox/example you would do:
hg clone local/path/repo ssh://firstname.lastname@example.org/hg-sandbox/example