1 # Contributing to Cabal
3 Building Cabal for hacking
4 --------------------------
6 The current recommended way of developing Cabal is to use the
7 `v2-build` feature which [shipped in cabal-install-1.24](http://blog.ezyang.com/2016/05/announcing-cabal-new-build-nix-style-local-builds/).
8 If you use the latest version of cabal published on Hackage, it is sufficient to run:
14 If not, you aren't able to build the testsuite, so you need to disable the default `cabal.project` that implies configuring the testsuite, e.g., with:
17 cabal v2-build --project-file=cabal.project.release cabal
20 The location of your build products will vary depending on which version of
21 cabal-install you use to build; see the documentation section
22 [Where are my build products?](http://cabal.readthedocs.io/en/latest/nix-local-build.html#where-are-my-build-products)
23 to find the binary (or just run `find -type f -executable -name cabal`).
25 Here are some other useful variations on the commands:
28 cabal v2-build Cabal # build library only
29 cabal v2-build Cabal-tests:unit-tests # build Cabal's unit test suite
30 cabal v2-build cabal-tests # etc...
36 **Using Github Actions.**
37 If you are not in a hurry, the most convenient way to run tests on Cabal
38 is to make a branch on GitHub and then open a pull request; our
39 continuous integration service on Github Actions builds and
40 tests your code. Title your PR with WIP so we know that it does not need
43 Some tips for using Github Actions effectively:
45 * Github Actions builds take a long time. Use them when you are pretty
46 sure everything is OK; otherwise, try to run relevant tests locally
49 * Watch over your jobs on the [Github Actions website](http://github.org/haskell/cabal/actions).
50 If you know a build of yours is going to fail (because one job has
51 already failed), be nice to others and cancel the rest of the jobs,
52 so that other commits on the build queue can be processed.
54 **How to debug a failing CI test.**
55 One of the annoying things about running tests on CI is when they
56 fail, there is often no easy way to further troubleshoot the broken
57 build. Here are some guidelines for debugging continuous integration
60 1. Can you tell what the problem is by looking at the logs? The
61 `cabal-testsuite` tests run with `-v` logging by default, which
62 is dumped to the log upon failure; you may be able to figure out
63 what the problem is directly this way.
65 2. Can you reproduce the problem by running the test locally?
66 See the next section for how to run the various test suites
67 on your local machine.
69 3. Is the test failing only for a specific version of GHC, or
70 a specific operating system? If so, try reproducing the
71 problem on the specific configuration.
73 4. Is the test failing on a Github Actions per-GHC build.
74 In this case, if you click on "Branch", you can get access to
75 the precise binaries that were built by Github Actions that are being
76 tested. If you have an Ubuntu system, you can download
77 the binaries and run them directly.
79 If none of these let you reproduce, there might be some race condition
80 or continuous integration breakage; please file a bug.
82 **Running tests locally.**
83 To run tests locally with `v2-build`, you will need to know the
84 name of the test suite you want. Cabal and cabal-install have
85 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)
87 The most important test suite is `cabal-testsuite`: most user-visible
88 changes to Cabal should come with a test in this framework. See
89 [cabal-testsuite/README.md](cabal-testsuite/README.md) for more
90 information about how to run tests and write new ones. Quick
91 start: use `cabal-tests` to run `Cabal` tests, and `cabal-tests
92 --with-cabal=/path/to/cabal` to run `cabal-install` tests
93 (don't forget `--with-cabal`! Your cabal-install tests won't
96 There are also other test suites:
98 * `Cabal-tests:unit-tests` are small, quick-running unit tests
99 on small pieces of functionality in Cabal. If you are working
100 on some utility functions in the Cabal library you should run this
103 * `cabal-install:unit-tests` are small, quick-running unit tests on
104 small pieces of functionality in cabal-install. If you are working
105 on some utility functions in cabal-install you should run this test
108 * `cabal-install:long-tests` are QuickCheck tests on
109 cabal-install's dependency solver, VCS, and file monitoring code.
110 If you are working on the solver you should run this test suite.
112 * `cabal-install:integration-tests2` are integration tests on some
113 top-level API functions inside the `cabal-install` source code.
115 For these test executables, `-p` which applies a regex filter to the test
116 names. When running `cabal-install` test suites, one need only use `cabal test` or
117 `cabal run <test-target>` in order to test locally.
122 Manual Quality Assurance (QA) is performed to ensure that the changes impacting
123 the command-line interface, whether adding or modifying a behaviour,
124 are tested before being released. This allows us to catch UX regressions and put
125 a human perspective into testing.
127 Contributions that touch `cabal-install` are expected to include notes for the QA team.
128 They are a description of an expected result upon calling `cabal-install` with certain parameters.
133 > Calling `cabal haddock-project` should produce documentation for the whole cabal project with the following defaults enabled:
134 > * Documentation lives in ./haddocks
135 > * The file `./haddocks/index.html` should exist
137 Manual QA is not expected to find every possible bug, but to really challenge the assumptions of the contributor, and to verify that their own testing
138 of their patch is not influenced by their setup or implicit knowledge of the system.
140 Whitespace Conventions
141 ----------------------
143 * No tab characters allowed.
144 * No trailing whitespace allowed.
145 * File needs to be terminated by a newline character.
147 These conventions are enforced by the
148 [fix-whitespace](https://hackage.haskell.org/package/fix-whitespace)
149 tool. Install it from hackage as usual (`cabal install fix-whitespace`)
150 and run it in the project root to fix whitespace violations.
152 The files included in the automatic whitespace check are specified in
153 `fix-whitespace.yaml`. Please add to this file if you add textfiles
154 to this repository that are not included by the rules given there.
155 Note that files that make essential use of tab characters (like `Makefile`)
156 should _not_ be included in the automatic check.
158 Whitespace conventions are enforced by
159 [CI](https://github.com/haskell/cabal/actions/workflows/whitespace.yml).
160 If you push a fix of a whitespace violation, please do so in a
169 * Try to follow style conventions of a file you are modifying, and
170 avoid gratuitous reformatting (it makes merges harder!)
172 * Format your commit messages [in the standard way](https://chris.beams.io/posts/git-commit/#seven-rules).
174 * A lot of Cabal does not have top-level comments. We are trying to
175 fix this. If you add new top-level definitions, please Haddock them;
176 and if you spend some time understanding what a function does, help
177 us out and add a comment. We'll try to remind you during code review.
179 * If you do something tricky or non-obvious, add a comment.
181 * For local imports (Cabal module importing Cabal module), import lists
182 are NOT required (although you may use them at your discretion.) For
183 third-party and standard library imports, please use either qualified imports
184 or explicit import lists.
186 * You can use basically any GHC extension supported by a GHC in our
187 support window, except Template Haskell, which would cause
188 bootstrapping problems in the GHC compilation process.
190 * Our GHC support window is five years for the Cabal library and three
191 years for cabal-install: that is, the Cabal library must be
192 buildable out-of-the-box with the dependencies that shipped with GHC
193 for at least five years. The Travis CI checks this, so most
194 developers submit a PR to see if their code works on all these
195 versions of GHC. `cabal-install` must also be buildable on all
196 supported GHCs, although it does not have to be buildable
197 out-of-the-box. Instead, the `cabal-install/bootstrap.sh` script
198 must be able to download and install all of the dependencies (this
199 is also checked by CI). Also, self-upgrade to the latest version
200 (i.e. `cabal install cabal-install`) must work with all versions of
201 `cabal-install` released during the last three years.
203 * `Cabal` has its own Prelude, in `Distribution.Compat.Prelude`,
204 that provides a compatibility layer and exports some commonly
205 used additional functions. Use it in all new modules.
207 * As far as possible, please do not use CPP. If you must use it,
208 try to put it in a `Compat` module, and minimize the amount of code
209 that is enclosed by CPP. For example, prefer:
212 #ifdef mingw32_HOST_OS
221 #ifdef mingw32_HOST_OS
230 We like [this style guide][guide].
232 [guide]: https://github.com/tibbe/haskell-style-guide/blob/master/haskell-style.md
234 GitHub Ticket Conventions
237 Each major `Cabal`/`cabal-install` release (e.g. 3.4, 3.6, etc.) has a
238 corresponding GitHub Project and milestone. A ticket is included in a release's
239 project if the release managers are tenatively planning on including a fix for
240 the ticket in the release, i.e. if they are actively seeking someone to work on
243 By contrast, a ticket is milestoned to a given release if we are open to
244 accepting a fix in that release, i.e. we would very much appreciate someone
245 working on it, but are not committing to actively sourcing someone to work on
248 GitHub Pull Request Conventions
251 Every (non-backport) pull request has to go through a review and get 2
252 approvals. After this is done, the author of the pull request is expected to add
253 any final touches they deem important and put the `merge me` label on the pull
254 request. If the author lacks permissions to apply labels, they are welcome to
255 explicitly signal the merge intent on the discussion thread of the pull request,
256 at which point others (e.g., reviewers) apply the label. Merge buttons are
257 reserved for exceptional situations, e.g., CI fixes being iterated on or
258 backports/patches that need to be expedited for a release.
260 Currently there is a 2 day buffer for potential extra feedback between the last
261 update of a pull request (e.g. a commit, a rebase, an addition of the `merge me`
262 label) and the moment the Mergify bot picks up the pull request for a merge.
264 If your pull request consists of several commits, consider using `squash+merge
265 me` instead of `merge me`: the Mergify bot will squash all the commits into one
266 and concatenate the commit messages of the commits before merging.
271 When opening a pull request, you should write a changelog entry
272 (or more in case of multiple independent changes).
273 This is done by adding files in the `changelog.d` directory.
275 The files follow a simple key-value format similar to the one for .cabal files.
277 Here's an exhaustive example:
280 synopsis: Add feature xyz
281 packages: cabal-install
284 significance: significant
294 Only the `synopsis` field is actually required, but you should also set the others where applicable.
296 | Field | Description |
297 | ----- | ----------- |
298 | `synopsis` | Brief description of the change. Often just the pr title. |
299 | `description` | Longer description, with a list of sub-changes. Not needed for small/atomic changes. |
300 | `packages` | Packages affected by the change (`cabal-install`, `Cabal`...). Omit if it's an overarching or non-package change. |
301 | `prs` | Space-separated hash-prefixed pull request numbers containing the change (usually just one). |
302 | `issues` | Space-separated hash-prefixed issue numbers that the change fixes/closes/affects. |
303 | `significance` | Set to `significant` if the change is significant, that is if it warrants being put near the top of the changelog. |
305 You can find a large number of real-world examples of changelog files
306 [here](https://github.com/haskell/cabal/tree/bc83de27569fda22dbe1e10be1a921bebf4d3430/changelog.d).
308 At release time, the entries will be merged with
309 [this tool](https://github.com/fgaz/changelog-d).
311 In addition, if you're changing the .cabal file format specification you should
312 add an entry in `doc/file-format-changelog.rst`.
317 There are a few main venues of communication:
319 * 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.
321 * For more organizational concerns, the [mailing
322 list](http://www.haskell.org/mailman/listinfo/cabal-devel) is used.
324 * Many developers idle on `#hackage` on [`irc.libera.chat`](https://libera.chat). The `#ghc` channel is also a decently good bet.
325 * You can join the channel using a web client, even anonymously: https://web.libera.chat/#hackage
326 * Alternatively you can join it using [matrix](https://matrix.org/): https://matrix.to/#/#hackage:libera.chat
331 Notes for how to make a release are at the
332 wiki page ["Making a release"](https://github.com/haskell/cabal/wiki/Making-a-release).
333 Currently, [@emilypi](https://github.com/emilypi), [@fgaz](https://github.com/fgaz) and [@Mikolaj](https://github.com/Mikolaj) have access to
334 `haskell.org/cabal`, and [@Mikolaj](https://github.com/Mikolaj) is the point of contact for getting
340 Auto-generated API documentation for the `master` branch of Cabal is automatically uploaded here: http://haskell.github.io/cabal-website/doc/html/Cabal/.
342 ## Issue triage [![Open Source Helpers](https://www.codetriage.com/haskell/cabal/badges/users.svg)](https://www.codetriage.com/haskell/cabal)
344 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).