Ways to contribute to Gitano

There are a myriad ways to contribute to Gitano. The simplest way is to simply become an active part of the Gitano community, supporting your fellow community members and other users of Gitano on our mailing lists and IRC channel. Beyond that, if you are having issues with your Gitano setup, contact the community via the list or IRC channel and have a discussion with someone. If you decide that your issue is actually a bug or missing feature in Gitano, then please go to our Trello, find the relevant board (for example, your bug might be in lace), and create a card in the incoming or bugs lanes. If you're unable to create a card due to a need to sign up to Trello, or due to a lack of access (not all of our boards are totally public, sadly), then instead post to the mailing list. One of the developers will pick up your report and triage it, offering help and if necessary fixing the software or documentation.

If, on the other hand, you believe you can fix the bug or implement the feature yourself (and we'd love to encourage you to have a go) then you may want to get the source code and see what you can do. If you're making a contribution toward the documentation, and do not wish to get embroiled in the fun of Git, then simply post to the mailing list with your suggested changes to the copy and a developer will sort that out for you.

Reporting security issues and vulnerabilities

Since security issues and vulnerabilities are somewhat more sensitive, we recommend that you don't immediately blurt them out on the IRC channel or mailing list. Instead we would encourage you to email security@gitano.org.uk directly. This alias goes to a subset of the core developers who will work with you to identify the nature of the vulnerability and to help you through a responsible disclosure process including reporting to the wider security community if you're not already familiar with that process.

The Gitano project believes in a responsible disclosure model for security issues and request that you give the team four weeks from reporting an issue (and failing to address it) before you go to a wider audience. The team aim to respond within days, but correcting a fix across all supported versions of the software may take a little longer.

Repaired security issues will always be reported in the release notes for a version of the software, and patches be made available in the source tree as soon as distributors of Gitano have been given a chance to get patches out to their users.

Getting started with the source code

In order to successfully contribute to Gitano you will need to get the source code so that you can make changes. Gitano is kept in a Git repository which can be found at:

You should clone the repository using the usual commands:

$ mkdir gitano-workspace
$ cd gitano-workspace
$ git clone https://git.gitano.org.uk/gitano.git
$ cd gitano

Once you have acquired a copy of the source code, it is common practice to ensure that you are able to build and run the test suite. This will allow you to be sure that you have all of the build dependencies for Gitano available on your system...

$ make test

It is distinctly possible that you may lack some of the build dependencies. Not least, you must have all of lace, supple, tongue, clod, gall, luxio, and lua-scrypt available. These are readily available from a Debian mirror (Stretch onwards) or from the same git servers listed above. Gitano also depends on lua-rex-pcre and the curl binary at this time.

In addition, Gitano's test suite has a number of dependencies. In order to verify http password support, you will need the htpasswd binary from apache2-utils, and to build the admin manual will require pandoc and all of the texlive suite. Much of this is documented in Gitano's README document found at the top level of the source code.

Gitano tests are mostly wrappered by a tool called yarn for which there are a number of implementations. The TESTING document includes details of how to acquire yarn implementations. It also covers how to write tests, how to understand the tests which exist, how to get coverage reports for when you do write tests, etc. Before writing any tests, or before trying to understand a test failure, please do read the TESTING document carefully and fully.

Asserting the right to supply a change

Any change you supply to Gitano or its associated projects will end up under the licence terms of that project. Typically that is either an ISC-like licence, or a Creative Commons licence for documentation and images. In order to do this there any any number of ways, but the one simplest and easiest to achieve is to use the Signed-off-by feature of Git's commits. If you submit commits which have this in, then the project will take those statements to mean that you understand the licence terms in play and that you have the right to license the content of the commits in that way.

Providing a change to the developers

Foremost in your mind when making a change to give to us should be testing and coverage. Testing of new code is essential, and changes to existing code not already covered by a test must be accompanied by a test. If you are correcting a defect in already tested code, a test which exposes the defect must be created or an existing test modified to expose the issue.

We won't insult your abilities to drive Git (after all, if you're making changes to a Git tool, you're likely able to make branches etc) but since we request changes be supplied in a particular way, here's how to send us a patch...

If you're just publishing a work-in-progress series for review and comment, then you can skip this first step, but if you're actually submitting changes which you hope to be accepted into Gitano then we'd prefer you follow it...

First up, please ensure that you have published your changes on the Internet. (i.e. that you have committed your changes and pushed them to a public Git repository such that the developers can pull from it) A Github repository if you must; though if you've your own Gitano instance sorted out which the developers can pull from, it'll give you some dogfooding kudos :-). The URL to this repository we shall refer to as $repo from now on. Ensure that your changes are pushed to that repository, and we shall refer to the branch they're on as $branch and the SHA1 of the tip of the commits you wish to be merged as $sha.

Next, you can use git format-patch to arrange a set of files which are the patch series. You may do this as follows:

$ cd gitano-workspace/gitano
$ git format-patch --cover-letter -M origin/master -o mails

In your cover letter (mails/0000-cover-letter.patch) please ensure that you fill out the subject properly, and include a description of what your patches are for, what problem they solve, etc. Ideally relate them to a Trello card or another mailing list thread if you can; or quote relevant bits of IRC backlog if applicable. Depending on whether you want the work merged or just commented on, ensure that your subject contains WIP if it's incomplete, RFC if it's a wacky idea and you're after a deeper review on the kind of thing you're up to rather than just how you're doing it, or READY (or nothing) if you want it merging. If you're hoping for a merge, ensure that you followed the first step and include at the top of your cover letter a section like:

Repo: $repo
Ref: $branch
Sha1: $sha

If you can't provide that section, but are after a merge, depending on whether the mailing list mangled things, the developer who merges your work may need to recreate your commits meaning that they may change SHA1, making your merge life a tad harder later on.

Once you've prepared your series, you can use git send-mail to send the entire series through to our developer mailing list where it will be dealt with.

Reviews on the mailing list

In order to make the lives of the core Gitano developer team a little easier, we do review of code on the developer mailing list. Another good way to get into contributing to Gitano is to review stuff which shows up on the list. We are trying to get away from pushes direct to master and so you will see review requests for work done by Gitano core developers too. Do not let that intimidate you into not responding.

Reviewing the patches themselves should be done by replying, quoting the patch, trimming out anything you don't need to comment on, and putting commentary in-line, leaving enough quoted context that the developer can find the bit you are referring to and make the changes necessary. Not all commentary need be things which must be acted upon. You may point out things to consider later or simply hilight things you really like as a way to encourage developers.

Once you have reviewed the full set of patches, reply to the cover letter with a summary of your opinion. If you feel confident enough you may respond with a +1 to indicate that you like the change and you feel it should be merged, or perhaps a -1 to say that you think there are issues serious enough to prevent the series being merged as-is. If you're not confident enough to vote, but still reviewed the series, please do include your opinions, and perhaps provide a +0 or -0 instead so that your vote can be taken into account.

Once a patch receives enough +1s, one of the developers who has push access to the main repositories will merge the change, push them, and respond to the cover letter to that effect.

Dealing with changing your series

If your patch series receives commentary which requires that you change things before it is mergeable, you should respond to the review emails, addressing each point raised, indicating if you are agreeing (and implementing the change) or arguing the point as appropriate. We prefer that patch series are moderately clean, so please ensure that you rebase your work to fold in the changes requested into the patches themselves. Sometimes we may ask you to split a patch up, or to join two patches together. Rebasing your work can do all of this, and more. A clean patch series is much easier to review.

When you have a fresh series, please push it to the appropriate place, and then use the above method to send a new copy to the developer mailing list. It is sensible to include a v2, v3, etc. in the subject line when you do so, but do not make your new series a reply to the old series. The cover letter in a v2 or v3 series should include a brief mention of what has changed since the previous series, but there is no need to include a full interdiff.

Coding standards etc

There are no formal coding standards for Gitano and its associated projects at this time. However, please try to make your code "fit in". This means that if you're modifying one of the library projects you should ensure that the lua-doc comments are correct and that you've written unit tests for your changes, with reasonable code coverage. If you're changing Gitano itself then you need to write a yarn scenario to cover your change properly.

Please don't reflow others' work as part of your change, and ensure where possible that your change is clean of whitespace droppings etc.

Gitano uses the editorconfig mechanism to provide some basic coding style guidelines, and if at all possible you should ensure that your editor abides by them.

Remember to review your patches yourself, before you send them to the list, and you're likely to not cause any style issues.