Skip to content

Latest commit

 

History

History
262 lines (198 loc) · 11.2 KB

CONTRIBUTING.md

File metadata and controls

262 lines (198 loc) · 11.2 KB
Raw

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. 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? 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. 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?

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 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.

Conventions

  • Spaces, not tabs.

  • 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.

  • 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.

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:

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.

At release time, the entries will be merged with this tool.

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:

Releases

Notes for how to make a release are at the wiki page "Making a release". Currently, @emilypi, @fgaz and @Mikolaj have access to haskell.org/cabal, and @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 Open Source Helpers

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.