Scope

Scalax is intended to contain much the same code that might be found in the standard library of a language, that is, code that will be of use to a wide range of developers and is not specific to particular problem domains, platforms, etc. There is a strong focus on quality of code rather than quantity.

Process

Scalax is comprised of numerous subprojects, each of which is developed in its own Mercurial repository, so that it can mature at its own pace. Anyone can gain commit access to these repositories, so that development can proceed using a Wiki-style model. The maintainers will periodically pull code from the development repositories into testing, and ultimately stable, releases. Final Scalax releases are intended to contain only code that can be considered mature and stable, and that has passed peer review.

Making contributions

Anyone can become a committer to Scalax. The procedure is roughly this:

Please first introduce yourself and your plans on the mailing list.
Mail me, indicating a preferred username and password (or the output of htpasswd -ns) in order to get commit access. You will also need to provide a signed Contributor License Agreement (individual or corporate). We require this to ensure that we are legally entitled to publish any contributions you make. These agreements are substantially identical to those used by the Apache foundation, among others.
Push your changes to the appropriate repository at https://hg.scalaforge.org, or send them to the mailing list if you would like to discuss them first.

If you would like to start a new subproject, the rough structure should first be discussed on the list, and then I will create a repository for it.

Using Mercurial

The best source of information is the online book, however the following should be enough to get started quickly. This text refers to the https URLs that are used by committers, however the http URLs will also work for everything but sending patches back to the server.

Setting up Mercurial

You can download Mercurial from the official site, or through most Linux package managers. I recommend the following as a basis for your configuration file (/etc/mercurial/hgrc on *nix):

[extensions]
hgk =
mq =
transplant =
fetch =
record =
graphlog =

[defaults]
record = -A
qrefresh = -g
export = -g

This mostly activates a selection of useful plugins which are included in the Mercurial distribution, but not enabled by default.

Obtaining a repository

Visit https://hg.scalaforge.org in a web browser in order to see the list of available repositories. To download one, run e.g. hg clone https://hg.scalaforge.org/scalax/website. This will create a new directory called website containing a copy of the repository.

Making a patch

Once you have made some changes to your working copy which you would like to submit, use hg record to create a new patch. It is very helpful to those reviewing your code to create a distinct and helpfully-named patch with each logical change that you make. The record extension helps you do this by confirming each change that it will commit. As configured above, it will also ask you about any new files that you create, which avoids needing to issue separate hg add instructions. Alternatively you can use the built-in commit command to grab everything. Either way, an editor will be executed at the end for you to enter a commit message.

Once created, a patch will still only exist in your local repository, so you will need to publish it.

Emailing a patch

If you do not have commit access, or you want to ask for a patch to be reviewed before committing it, you can format a patch ready to send to the list using hg export 1234. Replace 1234 with the revision number of the patch you would like to send. You can see which patches are not yet in the central repository using hg outgoing.

This process can be automated using the Patchbomb extension.

Pushing patches

To send all your outstanding patches to the central repository, simply use hg push.

Keeping up-to-date

The easiest way to pull new patches into your local repository is with hg fetch. This will fetch any new patches from the central repository and merge them into your working directory, recording a new patch containing the merge operation if necessary. If there any conflicts, you will be prompted to resolve them interactively.