summaryrefslogtreecommitdiff
path: root/contributing.mdwn
blob: ceeb461c3a52c47b025bdfb03ecd2a74d5c37b5c (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
[[!meta title="Contributing to Gitano"]]
[[!meta author="Daniel Silverstone"]]
[[!meta date="2017-04-08 11:00:00"]]

[[!toc]]

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|about/contact]] and
[[IRC channel|about/contact]].  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|https://trello.com/gitano]], find the relevant board (for example,
your bug might be in [[lace|https://trello.com/b/WBY0Z1yL/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](mailto: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](https://en.wikipedia.org/wiki/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:

* <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 `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 `+1`s, 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|http://editorconfig.org/]] 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.