From 7d1fd6bbf99d5072fb64b9563f91729bfd3b8ab7 Mon Sep 17 00:00:00 2001 From: Emily Pillmore Date: Sun, 2 May 2021 17:05:22 -0400 Subject: [PATCH] Update CONTRIBUTING.md + add changelog entry --- CONTRIBUTING.md | 61 ++++++------------------------- cabal-install/cabal-install.cabal | 2 +- changelog.d/pr-7358 | 21 +++++++++++ doc/cabal-project.rst | 4 +- 4 files changed, 36 insertions(+), 52 deletions(-) create mode 100644 changelog.d/pr-7358 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ba2fea4fab4..0aefb5c534b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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. @@ -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. @@ -137,21 +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. +names. When running `cabal-install` test suites, one need only use `cabal test` or +`cabal run ` in order to test locally. Conventions diff --git a/cabal-install/cabal-install.cabal b/cabal-install/cabal-install.cabal index b74e739ff0b..8e42a9bc7dd 100644 --- a/cabal-install/cabal-install.cabal +++ b/cabal-install/cabal-install.cabal @@ -239,7 +239,7 @@ library executable cabal - import: warnings, base-dep, cabal-dep, cabal-install-solver-dep + import: warnings, base-dep, cabal-dep main-is: Main.hs hs-source-dirs: main default-language: Haskell2010 diff --git a/changelog.d/pr-7358 b/changelog.d/pr-7358 new file mode 100644 index 00000000000..481e3402187 --- /dev/null +++ b/changelog.d/pr-7358 @@ -0,0 +1,21 @@ +synopsis: Expose `cabal-install` as library +prs: #7358 +issues: #7224 #6090 #4798 #3781 #1597 +significance: significant +description { + +- Exposes `cabal-install` as a library, bumping the `cabal-install` cabal version to 2.2, and removing the dogfooding framework surrounding `cabal-install` to facilitate easier testing. + +- Moves `cabal-install-solver` out to its own directory, and treats it as its own separate project. Addresses #6090, #7224, and #3781 + +- Enable HPC coverage: + + - absorb `cabal-install-solver-dsl` module into the test modules, and + incorporate it into its own test target. + + - Splits out `cabal-install` unit tests from long-running tests. + + - Adds proper subcomponent coverage masking so we can finally generate + baseline coverage reports for `cabal-install`. + +} \ No newline at end of file diff --git a/doc/cabal-project.rst b/doc/cabal-project.rst index d0d00698df1..ebd154cadd3 100644 --- a/doc/cabal-project.rst +++ b/doc/cabal-project.rst @@ -625,7 +625,7 @@ feature was added. other. It's not possible to set :cfg-field:`with-compiler` on a - per-package basis. + per-package basis. The command line variant of this flag is ``--with-compiler=ghc-7.8``; there is also a short version @@ -703,7 +703,7 @@ feature was added. The command line variant of this flag is ``--compiler=ghc``. It's not possible to set :cfg-field:`compiler` on a - per-package basis. + per-package basis. .. cfg-field:: tests: boolean --enable-tests