Skip to content

first cut at maintainer documentation #11332

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
geekosaur wants to merge 1 commit into
base: master
Choose a base branch
from
Draft

first cut at maintainer documentation #11332

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
89 changes: 34 additions & 55 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,15 @@
# Contributing to Cabal

## The fortnightly meeting

We have a dev call every 2 weeks at https://meet.jit.si/FavourableEvilsAnnounceAppallingly. All contributors and potential contributors are welcome.


## Issue triage [![Open Source Helpers](https://www.codetriage.com/haskell/cabal/badges/users.svg)](https://www.codetriage.com/haskell/cabal)

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


## Building Cabal for hacking

If you use the `cabal` executable from the latest version of the
Expand Down Expand Up @@ -62,7 +72,7 @@ $ cabal build cabal-tests # etc...
There are two ways to run tests: in CI with GitHub actions and locally with
`./validate.sh`.

### Using GitHub Actions.
### 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
Expand All @@ -87,7 +97,7 @@ Some tips for using GitHub Actions effectively:
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.
### 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
Expand All @@ -107,7 +117,7 @@ failures:
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.
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
Expand All @@ -116,7 +126,7 @@ failures:
If none of these let you reproduce, there might be some race condition
or continuous integration breakage; please file a bug.

### Running tests locally.
### Running tests locally

The [`./validate.sh`](./validate.sh) script runs all the test suites. It takes
various options to restrict the test suites it runs; use `--help` to list them.
Expand Down Expand Up @@ -358,10 +368,6 @@ If your pull request consists of several commits, consider using `squash+merge
me` instead of `merge me`: the Mergify bot will squash all the commits into one
and concatenate the commit messages of the commits before merging.

There is also a `merge+no rebase` label. Use this very sparingly, as not rebasing
severely complicates Git history. It is intended for special circumstances, as when
the PR branch cannot or should not be modified. If you have any questions about it,
please ask us.

### Pull Requests & Issues

Expand All @@ -371,32 +377,34 @@ your proposed design, UX considerations, tradeoffs etc. and work them out with
other contributors. The PR itself is for implementation.

If a PR becomes out of sync with its issue, go back to the issue, update
it, and continue the conversation there. Telltale signs of Issue/PR diverging
it, and continue the conversation there. Telltale signs of an issue and PR diverging
are, for example: the PR growing bigger in scope; lengthy discussions
about things that are *not* implementation choices; a change in design.

If your PR is trivial you can omit this process (but explain in the PR why you
think it does not warrant an issue). Feel free to open a new issue (or new
issues) when appropriate.


### Pull request size

Keep your pull requests small, write one pull request per feature, let
Keep your pull requests small, write one pull request per feature, make
the content of the pull request match the title of the pull request.

To get merged, your pull request needs to be reviewed by two other
As mentioned above, your pull request needs to be reviewed by two other
contributors. Large pull requests are daunting to inspect, and the
back-and-forth between the author and reviewer can get frustrating and
difficult to follow.

Split your pull requests in multiple ones if possible (e.g. a refactor
Split your pull requests into multiple ones if possible (e.g. a refactor
and a feature implementation should go in two different pull requests).
This is *especially* important when we decide to backport a pull request
(be it fix or a feature).

Thorough reviews mean fewer regressions, keeping your pull requests small
will improve Cabal codebase quality.


### Pull requests for `gh` users

Are you a [`gh`](https://cli.github.com/) (GitHub’s official command line tool)
Expand All @@ -410,16 +418,17 @@ This way you will not erase the
[PR template](https://github.com/haskell/cabal/blob/master/.github/pull_request_template.md)
all contributors use.


## Changelog

Anything that changes `cabal-install:exe:cabal` or changes exports from library
modules or changes behaviour of functions exported from packages published to
Anything that changes `cabal-install:exe:cabal`, changes exports from library
modules, or changes behaviour of functions exported from packages published to
hackage is a <a id="user-visible-change">user-visible change</a>. Raising the
lower bound on `base` is most definitely a user-visible change because it
excludes versions of GHC from being able to build these packages.

When opening a pull request with a user-visible change, you should write one
changelog entry (or more in case of multiple independent changes) — the
changelog entry (or more in case of multiple independent changes). The
information will end up in our release notes.

Changelogs for the next release are stored in the `changelog.d` directory.
Expand Down Expand Up @@ -493,16 +502,18 @@ add an entry in `doc/file-format-changelog.rst`.

### Is my change `significant`?

Use your best judgement and if unsure ask other maintainers. If your PR fixes
a specific ticket, how busy was the discussion there? A new command or option
most likely warrants a `significance: significant` tag, same with command
line changes that disrupts the workflow of many users or an API change
that requires substantial time to integrate in a program.
Use your best judgement and if unsure ask the
[maintainers](https://github.com/haskell/cabal-CABAL-MAINTAINERS.md).
If your PR fixes a specific ticket, how busy was the discussion there?
A new command or option most likely warrants a `significance: significant`
tag, as do command line changes that disrupt the workflow of many users or
API changes that require substantial updates for downstream users.

Put yourself in the shoes of the user: would you appreciate seeing this
change highlighted in the announcement post or release notes overview? If
so, add `significance: significant`.


## Communicating

There are a few main venues of communication:
Expand All @@ -516,20 +527,13 @@ There are a few main venues of communication:
* You can join the channel using a web client, even anonymously: https://web.libera.chat/#hackage
* Alternatively you can join it using [matrix](https://matrix.org/): https://matrix.to/#/#hackage:matrix.org

## Releases

Notes for how to make a release are at the
wiki page ["Making a release"](https://github.com/haskell/cabal/wiki/Making-a-release).
Currently, [@emilypi](https://github.com/emilypi), [@fgaz](https://github.com/fgaz) and [@Mikolaj](https://github.com/Mikolaj) have access to
`haskell.org/cabal`, and [@Mikolaj](https://github.com/Mikolaj) is the point of contact for getting
permissions.

## Preview Releases

We make preview releases available to facilitate testing of development builds.

Artifacts can be found on the [`cabal-head` release page](https://github.com/haskell/cabal/releases/tag/cabal-head).
The Validate CI pipeline generates tarballs with a `cabal` executable. The executable gets uploaded to this release by the pipelines that run on `master`.
The Build and release CI pipeline generates tarballs with a `cabal` executable. The executable gets uploaded to this release by the pipelines that run on `master`.

We currently make available builds for:
- Linux, dynamically linked (requiring `zlib`, `gmp`, `glibc`)
Expand All @@ -546,37 +550,12 @@ and then build by calling `cabal build cabal-install --enable-executable-static`

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](https://www.codetriage.com/haskell/cabal/badges/users.svg)](https://www.codetriage.com/haskell/cabal)

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

## Hackage Revisions

We are reactive rather than proactive with revising bounds on our dependencies
for code already released on Hackage. If you would benefit from a version bump,
please, open a ticket and get familiar with
[our revision policy](https://github.com/haskell/cabal/issues/9531#issuecomment-1866930240).

The burden of proof that the bump is harmless remains with you, but we have a CI
setup to show that our main pipeline ("Validate") is fine with the bump. To use
it, someone with enough permissions needs to go on the
[Validate workflow page](https://github.com/haskell/cabal/actions/workflows/validate.yml)
and dispatch it manually by clicking "Run workflow".

Running workflow manually as discussed above allows you to supply two inputs:

> allow-newer line
> constraints line

Going via an example, imagine that Cabal only allows `tar` or version less then
or equal to 0.6, and you want to bump it to 0.6. Then, to show that Validate
succeeds with `tar` 0.6, you should input

- `tar` to the "allow-newer line"
- `tar ==0.6` to the "constraints line"

Hopefully, running the Validate pipeline with these inputs succeeds and you
supply the link to the run in the ticket about bumping the bound and making a revision.

If interested in technical details, refer to the parts of `validate.yml` that
mention `hackage-revisions`.
You should ensure that the bump is harmless remains with you, but we will test in our CI
before making the revision.
134 changes: 123 additions & 11 deletions MAINTAINERS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,13 @@
## List of Maintainers
# Cabal maintainer documentation

a.k.a. The Cabal Maintainers Team:
This document outlines some of the things that cabal maintainers should know. Contributors shouldn't need anything in here, unless they're working on the CI system or need an executive decision from a repo maintainer below. (If you find that you do, please open an issue pointing out what needs to be moved to the contributor documentation.)

This is a first draft; many things are as yet missing. Open an issue if you need something added here.


## Maintainers

The Cabal Maintainers Team consists of:

* Mikolaj Konarski ([`@Mikolaj`](https://github.com/Mikolaj), mikolaj@well-typed.com, [`ce1ed8ae0b011d8c`](https://keyserver.ubuntu.com/pks/lookup?op=vindex&search=0xce1ed8ae0b011d8c))

Expand All @@ -10,23 +17,128 @@ a.k.a. The Cabal Maintainers Team:

* Brandon Allbery ([`@geekosaur`](https://github.com/geekosaur), allbery.b@gmail.com, [`227ee1942b0bdb95`](https://keyserver.ubuntu.com/pks/lookup?op=vindex&search=0x227ee1942b0bdb95))

* Matthew Pickering ([`@mpickering`](https://github.com/mpickering), matthew@well-typed.com)

### How we compose this list
* Matthew Pickering ([`@mpickering`](https://github.com/mpickering), matthew@well-typed.com)

The main goal of the team is to ensure that Cabal is keeping up with the ever-evolving Haskell ecosystem.
In practical terms this means producing releases of the packages in this repository on a regular basis: we usually have to release at least as often as does GHC due to an intimate connection between the compiler and the build system.
Hence, the people listed above (in chronological order by when they joined the team) are those who are currently available for carrying out the release procedures.
The main goal of the team is to ensure that Cabal is keeping up with the ever-evolving Haskell ecosystem. In practical terms this means producing releases of the packages in this repository on a regular basis: we usually have to release at least as often as does GHC due to an intimate connection between the compiler and the build system. Hence, the people listed above (in chronological order by when they joined the team) are those who are currently available for carrying out the release procedures.

Successful maintenance requires coordination, and the team engages in three main ways:

- attending to issues and PRs on GitHub;

- discussing Cabal on the [Matrix channel](https://matrix.to/#/#hackage:matrix.org);

- meeting biweekly in video calls with agenda prepared asynchronously in a Markdown document, which also holds the meeting notes.
- meeting biweekly in video calls with agenda prepared asynchronously in a [Markdown document](https://hackmd.io/ytXS6xrAS2mTyPVxdUS6OA?both), which also holds the meeting notes.

Worth noting that the meetings are open to everyone interested in Cabal, especially aspiring and returning Cabal contributors. Ask on Matrix how to join.

Most of the current team are volunteers, and we are happy to receive any help.
If you want to participate in Cabal maintenance as defined above (e.g. take on some release tasks), get in touch: open a GitHub discussion or send a message on Matrix.
Most of the current team are volunteers, and we are happy to receive any help. If you want to participate in Cabal maintenance as defined above (e.g. take on some release tasks), get in touch: open a GitHub discussion or send a message on Matrix.


## Workflows

The standard workflows are:

- `bootstrap.yml`: bootstrap a cabal from prepared JSONs (see `make bootstrap-jsons`)
- `validate.yml`: build a cabal with extra assertions and run the full test suite on it
- `changelogs.yml`: validate `changelog.d` files using [`changelog-d`]
- `dependabot.yml`: check `dependabot` configuration (sadly, not automatic; we lifted this from Ubuntu's CI)
- `lint.yml`: run `hlint` on cabal sources
- `format.yml`: check source formatting using Fourmolu v0.12
- `quick-jobs.yml`: various (formerly) quick checks
- `release.yaml`: build devel / release binaries for multiple platforms
- `typos.yml`: look for typos in documentation
- `users-guide.yml`: generate the users guide, creating an artifact
- `whitespace.yml`: check for extraneous whitespace in various files
- `check-sdist.yml`: make sure cabal can be built against the `Cabal` bootlib (see e.g. #10931, #9863)
- `release.yml`: build release binaries, either as part of a release or for testing

The validate workflow performs a number of tests on tier-1 platforms:

- on current GHCs (see the list of ghc versions in the jobs `matrix` in `validate.yml`) it runs through the full suite of tests (`lib-tests`, `lib-suite`, `cli-tests`, and `cli-suite`)
- on older GHCs (see the `extra-ghc` entries in `validate-old-ghcs`) it only runs `lib-suite-extras`, which is a cut-down test suite
- it builds but doesn't validate (for some reason) a static `cabal` on Alpine with MUSL
- it dogfoods `cabal` by having it build itself

You can use a manual dispatch on the validate workflow. It has two optional parameters:
- `allow-newer line` will add an `allow-newer:` entry to the project file. Don't include the prefix.
- `constraints line` will similarly add a `constraints:` entry.

The bootstrap workflow verifies that cabal can be built from pregenerated JSONs, for use in bootstrapping cabal on a new platform (since cabal is self-hosted). Note that, while we test this on release branches currently, bootstrapping is only supported from `master`.

The release workflow tests that PRs result in releasable `cabal`s, and is also used to produce `cabal` for releases. It can be dispatched manually or via a label `run release build`. It also performs daily draft releases starting at 00:00 UTC. It builds, tests, and releases for a wide variety of platforms, not all of which are considered Tier I for cabal development. (See list of tiers below.)


## Actions

Currently there is only one local action:

- `reusable-release.yaml`: the actual guts of `release.yaml` above.

The `validate-actions` branch in development will add more reusable actions for `validate.yml` in order to reduce duplication and make it more maintainable, and at that time `reusable-release` will likely be moved with the other reusable actions.


## Support tiers

Currently we support the following platforms as Tier 1:

- MacOS on AArch64
- X86-64 (aka AMD64)
- Windows (10 and 11)

Tier 2 platforms are:

- FreeBSD (AMD64 only)
- Alpine/MUSL static build
- MacOS on Intel
- X86 (deprecated)
- ARM Linux (Debian and Alpine)

We do not currently test on tier 2 platforms, but support for that is coming.


## CI

Mergify requires 2 approvals and a 2-day cooldown period before merging on `master`. Release branches are different, because we don't normally commit directly to them except during a release.

The rules for PRs on release branches are:

- only 1 approval needed for backports via Mergify (`@mergifyio backport branch`), otherwise 2 as usual
- no cooldown period, since either it's a backport of a PR that already received scrutiny or we're in the middle of a release and need things to move along

Note that you should not make (or approve) a PR directly to a release branch, unless it's necessary for release (usually this would be changelogs, but occasionally is needed for manual backports with conflicts).


## GPG keys

All maintainers who are authorized to make release binaries should have GPG keys cross-signed with other maintainers' keys. @f-a and @geekosaur can help with this if a new maintainer is onboarded.


## Releases

Notes for how to make a release are at the
wiki page ["Making a release"](https://github.com/haskell/cabal/wiki/Making-a-release).
Currently, [@emilypi](https://github.com/emilypi), [@fgaz](https://github.com/fgaz) and [@Mikolaj](https://github.com/Mikolaj) have access to
`haskell.org/cabal`, and [@Mikolaj](https://github.com/Mikolaj) is the point of contact for getting
permissions.


## Hackage Revisions

We have a CI setup to test that our main pipeline ("Validate") accepts a proposed revision. To use
it, go to the
[Validate workflow page](https://github.com/haskell/cabal/actions/workflows/validate.yml)
and dispatch it manually by clicking "Run workflow". As noted above in ["Workflows"](#workflows),
you can specify `allow-newer:` and `constraints:` entries reflecting the proposed revision.

For example, imagine that Cabal only allows `tar` or version less then
or equal to 0.6, and you want to bump it to 0.6. Then, to show that Validate
succeeds with `tar` 0.6, you should input

- `tar` for the `allow-newer line`
- `tar ==0.6` for the `constraints line`

Hopefully, running the Validate pipeline with these inputs succeeds, and you
should link to the run in the ticket about bumping the bound and making a revision.

If you are interested in the technical details, refer to the parts of `validate.yml` that
mention `hackage-revisions`.
Loading