Version 18 (modified by Dominic Hargreaves, 15 years ago) (diff)


Openguides commit policy

In order to ensure that OpenGuides development happens in a controlled way and with peer review, the following points need to be adhered to when contributing code (this is especially true for people with direct commit access to Subversion, but also relevant for those submitting patches via the mailing list or Trac).

Code style

A recommended programming style is given in Damian Conway's book Perl Best Practices. --IvorWilliams

Question from KakePugh: can you be more specific about what you mean here?


An indent is four spaces in Perl code, two spaces in templates. Do not use literal tabs.

If you are using vim, the following in your ~/.vimrc may help:

set tabstop=4
set expandtab

Literal tabs can also be straightened out with perltidy (see Perl::Tidy).

Function and variable names

Use lowercase and underscores, not CamelCase. For example, my_method_name rather than myMethodName.

Before committing

Before committing changes to the repository, you should ensure that all tests continue to pass (and if you have added more code, that you include new tests for it). If you're adding a new feature it's probably best to have discussed things first on the dev mailing list or on an enhancement ticket within Trac. You should most probably have an open ticket for the issue in any case. There is a CommitChecklist which you should look at before committing.

Submitting patches

I encourage committers to attach patches to tickets before committing too, to allow for some initial code review, for non-trivial changes. Patches can be submitted by people without commit rights (running an SVK mirror of the repository can help here).

Please use unified diff format, and give the resulting file an extension of .patch which allows trac to browse it sensibly. This can be done easily with subversion:

cd openguides
svn diff trunk >ticket_123.patch

Upload your patch to the ticket as an attachment. Keep the same name if you have a new revision of the patch which supersedes a previous upload. In the comment to go with the upload, include either the changeset number e.g. [789], for which your patch is made against, or the OpenGuides version number if the patch was made against a CPAN download.

Keep your patch up to date with svn update every time the trunk changes (remember to resolve any conflicts).

When to commit

Sometimes the release manager will call the tree frozen to allow a release to happen. No changes to the tree should be made when the tree is frozen except by the release manager. I intend freeze points to be shown on the Trac roadmap.

How to commit

See Subversion for details of how to access the repository. Remember, you should only be working in the trunk for the time being.

Make sure that changes are committed in a logical fashion. If you are making multiple unrelated changes to files, don't commit them all at once. Subversion (unlike CVS) has the notion of a changeset, so if you commit in this way all the changes will be grouped logically together and be easy to review. This includes the change to the Changes file. If you need to reformat a file, do so as a separate commit.

Automating Trac with Subversion log messages

When you commit a change that fixes a issue reported in a Trac ticket you can (and should, if possible) close the ticket automatically by including the string: "closes #nn" (where nn is the ticket number) in the log message. This will automatically close the ticket with a reference to the changeset. Note that this is a change from the way bugs were handled in RT (they were only closed when in a released version) but this functionality is too useful to not make use of. Hopefully we will get back to a release early, release often mode of operation so this won't hamper us too much.

This should work again - more docs at

You can also just refer to a ticket, which means that hyperlinks between the two will appear but the status will not change. The full specification of this functionality is as follows:

Commands can appear as:

command #1
command #1, #2
command #1 & #2
command #1 and #2

You can have more than one command in a log message. The supported commands are:

close, closed, closes, fix, fixed, fixes, Closes the ticket
addresses, re, references, refs, see References the ticket

Changesets may be linked to from tickets by entering their number in square brackets - eg, [001].


The following currently have commit access to OpenGuides. Usernames refer to the identies within both Subversion and Trac:

Username Name Role
dom DominicHargreaves Release manager, bug triage
earle EarleMartin Developer
ivorw IvorWilliams Developer
nick NickBurch Developer
kake KakePugh Developer
sheldon DavidSheldon? Occasional developer (December hackfest)
ilmari Dagfinn Ilmari Mannsaker Occasional developer (Summer 2007 hackfest)