-
Notifications
You must be signed in to change notification settings - Fork 704
/
Copy pathCONTRIBUTING.md
320 lines (242 loc) · 13.8 KB
/
CONTRIBUTING.md
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
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
# Contributing to Cabal
Building Cabal for hacking
--------------------------
The current recommended way of developing Cabal is to use the
`v2-build` feature which [shipped in cabal-install-1.24](http://blog.ezyang.com/2016/05/announcing-cabal-new-build-nix-style-local-builds/). Assuming
that you have a sufficiently recent cabal-install (see above),
it is sufficient to run:
```
cabal v2-build cabal
```
To build a local, development copy of cabal-install. The location
of your build products will vary depending on which version of
cabal-install you use to build; see the documentation section
[Where are my build products?](http://cabal.readthedocs.io/en/latest/nix-local-build.html#where-are-my-build-products)
to find the binary (or just run `find -type f -executable -name cabal`).
Here are some other useful variations on the commands:
```
cabal v2-build Cabal # build library only
cabal v2-build Cabal-tests:unit-tests # build Cabal's unit test suite
cabal v2-build cabal-tests # etc...
```
Running tests
-------------
**Using Github Actions.**
If you are not in a hurry, the most convenient way to run tests on Cabal
is to make a branch on GitHub and then open a pull request; our
continuous integration service on Github Actions builds and
tests your code. Title your PR with WIP so we know that it does not need
code review.
Some tips for using Github Actions effectively:
* Github Actions builds take a long time. Use them when you are pretty
sure everything is OK; otherwise, try to run relevant tests locally
first.
* Watch over your jobs on the [Github Actions website](http://github.org/haskell/cabal/actions).
If you know a build of yours is going to fail (because one job has
already failed), be nice to others and cancel the rest of the jobs,
so that other commits on the build queue can be processed.
**How to debug a failing CI test.**
One of the annoying things about running tests on CI is when they
fail, there is often no easy way to further troubleshoot the broken
build. Here are some guidelines for debugging continuous integration
failures:
1. Can you tell what the problem is by looking at the logs? The
`cabal-testsuite` tests run with `-v` logging by default, which
is dumped to the log upon failure; you may be able to figure out
what the problem is directly this way.
2. Can you reproduce the problem by running the test locally?
See the next section for how to run the various test suites
on your local machine.
3. Is the test failing only for a specific version of GHC, or
a specific operating system? If so, try reproducing the
problem on the specific configuration.
4. Is the test failing on a Github Actions per-GHC build.
In this case, if you click on "Branch", you can get access to
the precise binaries that were built by Github Actions that are being
tested. If you have an Ubuntu system, you can download
the binaries and run them directly.
If none of these let you reproduce, there might be some race condition
or continuous integration breakage; please file a bug.
**Running tests locally.**
To run tests locally with `v2-build`, you will need to know the
name of the test suite you want. Cabal and cabal-install have
several. Also, you'll want to read [Where are my build products?](http://cabal.readthedocs.io/en/latest/nix-local-build.html#where-are-my-build-products)
The most important test suite is `cabal-testsuite`: most user-visible
changes to Cabal should come with a test in this framework. See
[cabal-testsuite/README.md](cabal-testsuite/README.md) for more
information about how to run tests and write new ones. Quick
start: use `cabal-tests` to run `Cabal` tests, and `cabal-tests
--with-cabal=/path/to/cabal` to run `cabal-install` tests
(don't forget `--with-cabal`! Your cabal-install tests won't
run without it).
There are also other test suites:
* `Cabal-tests:unit-tests` are small, quick-running unit tests
on small pieces of functionality in Cabal. If you are working
on some utility functions in the Cabal library you should run this
test suite.
* `cabal-install:unit-tests` are small, quick-running unit tests on
small pieces of functionality in cabal-install. If you are working
on some utility functions in cabal-install you should run this test
suite.
* `cabal-install:long-tests` are QuickCheck tests on
cabal-install's dependency solver, VCS, and file monitoring code.
If you are working on the solver you should run this test suite.
* `cabal-install:integration-tests2` are integration tests on some
top-level API functions inside the `cabal-install` source code.
For these test executables, `-p` which applies a regex filter to the test
names. When running `cabal-install` test suites, one need only use `cabal test` or
`cabal run <test-target>` in order to test locally.
Whitespace Conventions
----------------------
* No tab characters allowed.
* No trailing whitespace allowed.
* File needs to be terminated by a newline character.
These conventions are enforced by the
[fix-whitespace](https://hackage.haskell.org/package/fix-whitespace)
tool. Install it from hackage as usual (`cabal install fix-whitespace`)
and run it in the project root to fix whitespace violations.
The files included in the automatic whitespace check are specified in
`fix-whitespace.yaml`. Please add to this file if you add textfiles
to this repository that are not included by the rules given there.
Note that files that make essential use of tab characters (like `Makefile`)
should _not_ be included in the automatic check.
Whitespace conventions are enforced by
[CI](https://github.com/haskell/cabal/actions/workflows/whitespace.yml).
If you push a fix of a whitespace violation, please do so in a
_separate commit_.
Other Conventions
-----------------
* Try to follow style conventions of a file you are modifying, and
avoid gratuitous reformatting (it makes merges harder!)
* Format your commit messages [in the standard way](https://chris.beams.io/posts/git-commit/#seven-rules).
* A lot of Cabal does not have top-level comments. We are trying to
fix this. If you add new top-level definitions, please Haddock them;
and if you spend some time understanding what a function does, help
us out and add a comment. We'll try to remind you during code review.
* If you do something tricky or non-obvious, add a comment.
* For local imports (Cabal module importing Cabal module), import lists
are NOT required (although you may use them at your discretion.) For
third-party and standard library imports, please use either qualified imports
or explicit import lists.
* You can use basically any GHC extension supported by a GHC in our
support window, except Template Haskell, which would cause
bootstrapping problems in the GHC compilation process.
* Our GHC support window is five years for the Cabal library and three
years for cabal-install: that is, the Cabal library must be
buildable out-of-the-box with the dependencies that shipped with GHC
for at least five years. The Travis CI checks this, so most
developers submit a PR to see if their code works on all these
versions of GHC. `cabal-install` must also be buildable on all
supported GHCs, although it does not have to be buildable
out-of-the-box. Instead, the `cabal-install/bootstrap.sh` script
must be able to download and install all of the dependencies (this
is also checked by CI). Also, self-upgrade to the latest version
(i.e. `cabal install cabal-install`) must work with all versions of
`cabal-install` released during the last three years.
* `Cabal` has its own Prelude, in `Distribution.Compat.Prelude`,
that provides a compatibility layer and exports some commonly
used additional functions. Use it in all new modules.
* As far as possible, please do not use CPP. If you must use it,
try to put it in a `Compat` module, and minimize the amount of code
that is enclosed by CPP. For example, prefer:
```
f :: Int -> Int
#ifdef mingw32_HOST_OS
f = (+1)
#else
f = (+2)
#endif
```
over:
```
#ifdef mingw32_HOST_OS
f :: Int -> Int
f = (+1)
#else
f :: Int -> Int
f = (+2)
#endif
```
We like [this style guide][guide].
[guide]: https://github.com/tibbe/haskell-style-guide/blob/master/haskell-style.md
GitHub Ticket Conventions
-------------------
Each major `Cabal`/`cabal-install` release (e.g. 3.4, 3.6, etc.) has a
corresponding GitHub Project and milestone. A ticket is included in a release's
project if the release managers are tenatively planning on including a fix for
the ticket in the release, i.e. if they are actively seeking someone to work on
the ticket.
By contrast, a ticket is milestoned to a given release if we are open to
accepting a fix in that release, i.e. we would very much appreciate someone
working on it, but are not committing to actively sourcing someone to work on
it.
GitHub Pull Request Conventions
-------------------
Every (non-backport) pull request has to go through a review and get 2
approvals. After this is done, the author of the pull request is expected to add
any final touches they deem important and put the `merge me` label on the pull
request. If the author lacks permissions to apply labels, they are welcome to
explicitly signal the merge intent on the discussion thread of the pull request,
at which point others (e.g., reviewers) apply the label. Merge buttons are
reserved for exceptional situations, e.g., CI fixes being iterated on or
backports/patches that need to be expedited for a release.
Currently there is a 2 day buffer for potential extra feedback between the last
update of a pull request (e.g. a commit, a rebase, an addition of the `merge me`
label) and the moment the Mergify bot picks up the pull request for a merge.
If your pull request consists of several commits, consider using `squash+merge
me` instead of `merge me`: the Mergify bot will squash all the commits into one
and concatenate the commit messages of the commits before merging.
Changelog
---------
When opening a pull request, you should write a changelog entry
(or more in case of multiple independent changes).
This is done by adding files in the `changelog.d` directory.
The files follow a simple key-value format similar to the one for .cabal files.
Here's an exhaustive example:
```cabal
synopsis: Add feature xyz
packages: cabal-install
prs: #0000
issues: #0000 #0000
significance: significant
description: {
- Detail number 1
- Detail number 2
}
```
Only the `synopsis` field is actually required, but you should also set the others where applicable.
| Field | Description |
| ----- | ----------- |
| `synopsis` | Brief description of the change. Often just the pr title. |
| `description` | Longer description, with a list of sub-changes. Not needed for small/atomic changes. |
| `packages` | Packages affected by the change (`cabal-install`, `Cabal`...). Omit if it's an overarching or non-package change. |
| `prs` | Space-separated hash-prefixed pull request numbers containing the change (usually just one). |
| `issues` | Space-separated hash-prefixed issue numbers that the change fixes/closes/affects. |
| `significance` | Set to `significant` if the change is significant, that is if it warrants being put near the top of the changelog. |
You can find a large number of real-world examples of changelog files
[here](https://github.com/haskell/cabal/tree/bc83de27569fda22dbe1e10be1a921bebf4d3430/changelog.d).
At release time, the entries will be merged with
[this tool](https://github.com/fgaz/changelog-d).
In addition, if you're changing the .cabal file format specification you should
add an entry in `doc/file-format-changelog.rst`.
Communicating
-------------
There are a few main venues of communication:
* Most developers subscribe to receive messages from [all issues](https://github.com/haskell/cabal/issues); issues can be used to [open discussion](https://github.com/haskell/cabal/issues?q=is%3Aissue+is%3Aopen+custom+label%3A%22type%3A+discussion%22). If you know someone who should hear about a message, CC them explicitly using the @username GitHub syntax.
* For more organizational concerns, the [mailing
list](http://www.haskell.org/mailman/listinfo/cabal-devel) is used.
* Many developers idle on `#hackage` on [`irc.libera.chat`](https://libera.chat). The `#ghc` channel is also a decently good bet.
* You can join the channel using a web client, even anonymously: https://web.libera.chat/#hackage
* Alternatively you can join it using [matrix](https://matrix.org/): https://matrix.to/#/#hackage:libera.chat
Releases
--------
Notes for how to make a release are at the
wiki page ["Making a release"](https://github.com/haskell/cabal/wiki/Making-a-release).
Currently, [@emilypi](https://github.com/emilypi), [@fgaz](https://github.com/fgaz) and [@Mikolaj](https://github.com/Mikolaj) have access to
`haskell.org/cabal`, and [@Mikolaj](https://github.com/Mikolaj) is the point of contact for getting
permissions.
API Documentation
-----------------
Auto-generated API documentation for the `master` branch of Cabal is automatically uploaded here: http://haskell.github.io/cabal-website/doc/html/Cabal/.
## Issue triage [](https://www.codetriage.com/haskell/cabal)
You can contribute by triaging issues which may include reproducing bug reports or asking for vital information, such as version numbers or reproduction instructions. If you would like to start triaging issues, one easy way to get started is to [subscribe to cabal on CodeTriage](https://www.codetriage.com/haskell/cabal).