Svgwg.org

From SVG

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.

Note: all changes to the WG repositories must go through svgwg.org. If some people push their changes directly to dvcs.w3.org and others push theirs to svgwg.org, then we'll end up with unintended branches that may be virtually impossible to merge. Additionally, any changes pushed directly to dvcs.w3.org will not have passed the checks carried out on pushes to svgwg.org (see the Hooks section below).


Access

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

Before you clone any of the repositories it is very important that you have a per-user Mercurial configuration file containing the lines detailed on the Mercurial page. The 'hgext.eol =' line and '[eol]' section are especially important to add before checking out!


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://svgwg@svgwg.org/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.

Prerequisites

To build the spec, you will need a Unix-like environment. cygwin on Windows will work. You also specifically need the following tools installed:

  • mercurial
  • make
  • python
  • node (nodejs on Fedora... the 'node' package is a Ham radio thing!)
  • ssh (this is in the openssh package on cygwin)
  • rsync

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"

Building

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

Note: Cygwin FAQ has this information, but since I've hit it myself - might be useful to put here as well. The spec doesn't build on Cygwin if you have spaces in the path - http://cygwin.com/faq.html#faq.setup.name-with-space

Making changes

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.


Unlike CVS or SVN, a commit or push applies to ALL files in the repository, and not just those files in your current directory and its subdirectories.

HG manages files, not directories. Empty directories cannot be created. If you empty a directory it will be deleted.

Hooks

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.

Repository sandbox

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://svgwg@svgwg.org/hg-sandbox/example
Retrieved from "https://www.w3.org/Graphics/SVG/WG/wiki/index.php?title=Svgwg.org&oldid=7489"