Skip to content

Commit

Permalink
Amend documenting in CONTRIBUTING.md for cabal-install testing
Browse files Browse the repository at this point in the history
* Add missing bootstrap plans
* Add changelog entry for #7358
  • Loading branch information
emilypi committed Apr 23, 2021
1 parent 21322fb commit db2a099
Show file tree
Hide file tree
Showing 4 changed files with 415 additions and 48 deletions.
58 changes: 10 additions & 48 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,54 +26,23 @@ cabal v2-build Cabal:unit-tests # build Cabal's unit test suite
cabal v2-build cabal-tests # etc...
~~~~

**Dogfooding HEAD.**
Many of the core developers of Cabal dogfood `cabal-install` HEAD
when doing development on Cabal. This helps us identify bugs
which were missed by the test suite and easily experiment with new
features.

The recommended workflow in this case is slightly different: you will
maintain two Cabal source trees: your production tree (built with a
released version of Cabal) which always tracks `master` and which you
update only when you want to move to a new version of Cabal to dogfood,
and your development tree (built with your production Cabal) that you
actually do development on.

In more detail, suppose you have checkouts of Cabal at `~/cabal-prod`
and `~/cabal-dev`, and you have a release copy of cabal installed at
`/opt/cabal/2.4/bin/cabal`. First, build your production tree:

~~~~
cd ~/cabal-prod
/opt/cabal/2.4/bin/cabal v2-build cabal
~~~~

This will produce a cabal binary (see also: [Where are my build products?](http://cabal.readthedocs.io/en/latest/nix-local-build.html#where-are-my-build-products)
). Add this binary to your PATH,
and then use it to build your development copy:

~~~~
cd ~/cabal-dev
cabal v2-build cabal
~~~~

Running tests
-------------

**Using Travis and AppVeyor.**
**Using Github Actions and AppVeyor.**
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 Travis and AppVeyor will build and
continuous integration service on Github Actions and AppVeyor will build and
test your code. Title your PR with WIP so we know that it does not need
code review.

Some tips for using Travis effectively:
Some tips for using Github Actions effectively:

* Travis builds take a long time. Use them when you are pretty
* 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 [Travis website](http://travis-ci.org).
* 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.
Expand All @@ -97,10 +66,9 @@ failures:
a specific operating system? If so, try reproducing the
problem on the specific configuration.

4. Is the test failing on a Travis per-GHC build
([for example](https://travis-ci.org/haskell-pushbot/cabal-binaries/builds/208128401))?
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 Travis that are being
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.

Expand Down Expand Up @@ -137,22 +105,16 @@ There are also other test suites:
on some utility functions in cabal-install you should run this test
suite.

* `cabal-install:solver-quickcheck` are QuickCheck tests on
cabal-install's dependency solver. If you are working
on the solver 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.

**Testing `cabal-install` Locally**

If you are testing `cabal-install` locally, you may refer to its [TESTING.md](cabal-install/TESTING.md) for
instructions on how to use the `Makefile` to produce the appropriate `.cabal` file
with test targets. From there, you may add tests in the usual way.


Conventions
-----------
Expand Down
Loading

0 comments on commit db2a099

Please sign in to comment.