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
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.
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 firstname.lastname@example.org 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.
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:
- https://git.gitano.org.uk/gitano.git - Primary repository
- TODO: Add a github mirror?
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
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
texlive suite. Much of this is documented in Gitano's
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
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.
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.
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
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
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
-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
-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.
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
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
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.