CONTRIBUTING.md

   1 # Contributing to Cabal
   2
   3 Building Cabal for hacking
   4 --------------------------
   5
   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/).  Assuming
   8 that you have a sufficiently recent cabal-install (see above),
   9 it is sufficient to run:
  10
  11 ~~~~
  12 cabal v2-build cabal
  13 ~~~~
  14
  15 To build a local, development copy of cabal-install.  The location
  16 of your build products will vary depending on which version of
  17 cabal-install you use to build; see the documentation section
  18 [Where are my build products?](http://cabal.readthedocs.io/en/latest/nix-local-build.html#where-are-my-build-products)
  19 to find the binary (or just run `find -type f -executable -name cabal`).
  20
  21 Here are some other useful variations on the commands:
  22
  23 ~~~~
  24 cabal v2-build Cabal # build library only
  25 cabal v2-build Cabal:unit-tests # build Cabal's unit test suite
  26 cabal v2-build cabal-tests # etc...
  27 ~~~~
  28
  29 Running tests
  30 -------------
  31
  32 **Using Github Actions and AppVeyor.**
  33 If you are not in a hurry, the most convenient way to run tests on Cabal
  34 is to make a branch on GitHub and then open a pull request; our
  35 continuous integration service on Github Actions and AppVeyor will build and
  36 test your code.  Title your PR with WIP so we know that it does not need
  37 code review.
  38
  39 Some tips for using Github Actions effectively:
  40
  41 * Github Actions builds take a long time.  Use them when you are pretty
  42   sure everything is OK; otherwise, try to run relevant tests locally
  43   first.
  44
  45 * Watch over your jobs on the [Github Actions website](http://github.org/haskell/cabal/actions).
  46   If you know a build of yours is going to fail (because one job has
  47   already failed), be nice to others and cancel the rest of the jobs,
  48   so that other commits on the build queue can be processed.
  49
  50 **How to debug a failing CI test.**
  51 One of the annoying things about running tests on CI is when they
  52 fail, there is often no easy way to further troubleshoot the broken
  53 build.  Here are some guidelines for debugging continuous integration
  54 failures:
  55
  56 1. Can you tell what the problem is by looking at the logs?  The
  57    `cabal-testsuite` tests run with `-v` logging by default, which
  58    is dumped to the log upon failure; you may be able to figure out
  59    what the problem is directly this way.
  60
  61 2. Can you reproduce the problem by running the test locally?
  62    See the next section for how to run the various test suites
  63    on your local machine.
  64
  65 3. Is the test failing only for a specific version of GHC, or
  66    a specific operating system?  If so, try reproducing the
  67    problem on the specific configuration.
  68
  69 4. Is the test failing on a Github Actions per-GHC build.
  70    In this case, if you click on "Branch", you can get access to
  71    the precise binaries that were built by Github Actions that are being
  72    tested.  If you have an Ubuntu system, you can download
  73    the binaries and run them directly.
  74
  75 5. Is the test failing on AppVeyor?  Consider logging in via
  76    Remote Desktop to the build VM:
  77    https://www.appveyor.com/docs/how-to/rdp-to-build-worker/
  78
  79 If none of these let you reproduce, there might be some race condition
  80 or continuous integration breakage; please file a bug.
  81
  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)
  86
  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
  94 run without it).
  95
  96 There are also other test suites:
  97
  98 * `Cabal: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
 101   test suite.
 102
 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
 106   suite.
 107
 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.
 111
 112 * `cabal-install:integration-tests2` are integration tests on some
 113   top-level API functions inside the `cabal-install` source code.
 114
 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.
 118
 119
 120 Conventions
 121 -----------
 122
 123 * Spaces, not tabs.
 124
 125 * Try to follow style conventions of a file you are modifying, and
 126   avoid gratuitous reformatting (it makes merges harder!)
 127
 128 * Format your commit messages [in the standard way](https://chris.beams.io/posts/git-commit/#seven-rules).
 129
 130 * A lot of Cabal does not have top-level comments.  We are trying to
 131   fix this.  If you add new top-level definitions, please Haddock them;
 132   and if you spend some time understanding what a function does, help
 133   us out and add a comment.  We'll try to remind you during code review.
 134
 135 * If you do something tricky or non-obvious, add a comment.
 136
 137 * If your commit only touches comments, you can use `[ci skip]`
 138   anywhere in the body of the commit message to avoid needlessly
 139   triggering the build bots.
 140
 141 * For local imports (Cabal module importing Cabal module), import lists
 142   are NOT required (although you may use them at your discretion.)  For
 143   third-party and standard library imports, please use either qualified imports
 144   or explicit import lists.
 145
 146 * You can use basically any GHC extension supported by a GHC in our
 147   support window, except Template Haskell, which would cause
 148   bootstrapping problems in the GHC compilation process.
 149
 150 * Our GHC support window is five years for the Cabal library and three
 151   years for cabal-install: that is, the Cabal library must be
 152   buildable out-of-the-box with the dependencies that shipped with GHC
 153   for at least five years.  The Travis CI checks this, so most
 154   developers submit a PR to see if their code works on all these
 155   versions of GHC.  `cabal-install` must also be buildable on all
 156   supported GHCs, although it does not have to be buildable
 157   out-of-the-box. Instead, the `cabal-install/bootstrap.sh` script
 158   must be able to download and install all of the dependencies (this
 159   is also checked by CI). Also, self-upgrade to the latest version
 160   (i.e. `cabal install cabal-install`) must work with all versions of
 161   `cabal-install` released during the last three years.
 162
 163 * `Cabal` has its own Prelude, in `Distribution.Compat.Prelude`,
 164   that provides a compatibility layer and exports some commonly
 165   used additional functions. Use it in all new modules.
 166
 167 * As far as possible, please do not use CPP. If you must use it,
 168   try to put it in a `Compat` module, and minimize the amount of code
 169   that is enclosed by CPP.  For example, prefer:
 170   ```
 171   f :: Int -> Int
 172   #ifdef mingw32_HOST_OS
 173   f = (+1)
 174   #else
 175   f = (+2)
 176   #endif
 177   ```
 178
 179   over:
 180   ```
 181   #ifdef mingw32_HOST_OS
 182   f :: Int -> Int
 183   f = (+1)
 184   #else
 185   f :: Int -> Int
 186   f = (+2)
 187   #endif
 188   ```
 189
 190 We like [this style guide][guide].
 191
 192 [guide]: https://github.com/tibbe/haskell-style-guide/blob/master/haskell-style.md
 193
 194 Changelog
 195 ---------
 196
 197 When opening a pull request, you should write a changelog entry.
 198 This is done by adding a file in the `changelog.d` directory.
 199
 200 The files follow a simple key-value format similar to the one for .cabal files.
 201
 202 Here's an exhaustive example:
 203
 204 ```cabal
 205 synopsis: Add feature xyz
 206 packages: cabal-install
 207 prs: #0000
 208 issues: #0000 #0000
 209 significance: significant
 210
 211 description: {
 212
 213 - Detail number 1
 214 - Detail number 2
 215
 216 }
 217 ```
 218
 219 Only the `synopsis` field is actually required, but you should also set the others where applicable.
 220
 221 | Field          | Description                                                                                                        |
 222 | -----          | -----------                                                                                                        |
 223 | `synopsis`     | Brief description of the change. Often just the pr title.                                                          |
 224 | `description`  | Longer description, with a list of sub-changes. Not needed for small/atomic changes.                               |
 225 | `packages`     | Packages affected by the change (`cabal-install`, `Cabal`...). Omit if it's an overarching or non-package change.  |
 226 | `prs`          | Space-separated hash-prefixed pull request numbers containing the change (usually just one).                       |
 227 | `issues`       | Space-separated hash-prefixed issue numbers that the change fixes/closes/affects.                                  |
 228 | `significance` | Set to `significant` if the change is significant, that is if it warrants being put near the top of the changelog. |
 229
 230 You can find a large number of real-world examples of changelog files
 231 [here](https://github.com/haskell/cabal/tree/bc83de27569fda22dbe1e10be1a921bebf4d3430/changelog.d).
 232
 233 At release time, the entries will be merged with
 234 [this tool](https://github.com/phadej/changelog-d).
 235
 236 Communicating
 237 -------------
 238
 239 There are a few main venues of communication:
 240
 241 * 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.
 242
 243 * For more organizational concerns, the [mailing
 244   list](http://www.haskell.org/mailman/listinfo/cabal-devel) is used.
 245
 246 * Many developers idle on `#hackage` on `irc.freenode.net` ([archives](http://ircbrowse.net/browse/hackage)).  `#ghc` ([archives](http://ircbrowse.net/browse/ghc)) is also a decently good bet.
 247
 248 Releases
 249 --------
 250
 251 Notes for how to make a release are at the
 252 wiki page ["Making a release"](https://github.com/haskell/cabal/wiki/Making-a-release).
 253 Currently, @23Skidoo, @rthomas, @tibbe and @dcoutts have access to
 254 `haskell.org/cabal`, and @davean is the point of contact for getting
 255 permissions.
 256
 257 API Documentation
 258 -----------------
 259
 260 Auto-generated API documentation for the `master` branch of Cabal is automatically uploaded here: http://haskell.github.io/cabal-website/doc/html/Cabal/.
 261
 262 ## Issue triage [![Open Source Helpers](https://www.codetriage.com/haskell/cabal/badges/users.svg)](https://www.codetriage.com/haskell/cabal)
 263
 264 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).