You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Highly incomplete. Also, revise contributor documentation including
moving some things to the maintainer documentation and absorbing the old
maintainers list which is now at the top.
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).
11
+
12
+
3
13
## Building Cabal for hacking
4
14
5
15
If you use the `cabal` executable from the latest version of the
If your PR fixes a specific ticket, how busy was the discussion there?
508
+
A new command or option most likely warrants a `significance: significant`
509
+
tag, as do command line changes that disrupt the workflow of many users or
510
+
API changes that require substantial updates for downstream users.
501
511
502
512
Put yourself in the shoes of the user: would you appreciate seeing this
503
513
change highlighted in the announcement post or release notes overview? If
504
514
so, add `significance: significant`.
505
515
516
+
506
517
## Communicating
507
518
508
519
There are a few main venues of communication:
@@ -516,20 +527,13 @@ There are a few main venues of communication:
516
527
* You can join the channel using a web client, even anonymously: https://web.libera.chat/#hackage
517
528
* Alternatively you can join it using [matrix](https://matrix.org/): https://matrix.to/#/#hackage:matrix.org
518
529
519
-
## Releases
520
-
521
-
Notes for how to make a release are at the
522
-
wiki page ["Making a release"](https://github.com/haskell/cabal/wiki/Making-a-release).
523
-
Currently, [@emilypi](https://github.com/emilypi), [@fgaz](https://github.com/fgaz) and [@Mikolaj](https://github.com/Mikolaj) have access to
524
-
`haskell.org/cabal`, and [@Mikolaj](https://github.com/Mikolaj) is the point of contact for getting
525
-
permissions.
526
530
527
531
## Preview Releases
528
532
529
533
We make preview releases available to facilitate testing of development builds.
530
534
531
535
Artifacts can be found on the [`cabal-head` release page](https://github.com/haskell/cabal/releases/tag/cabal-head).
532
-
The Validate CI pipeline generates tarballs with a `cabal` executable. The executable gets uploaded to this release by the pipelines that run on `master`.
536
+
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`.
@@ -546,37 +550,12 @@ and then build by calling `cabal build cabal-install --enable-executable-static`
546
550
547
551
Auto-generated API documentation for the `master` branch of Cabal is automatically uploaded here: http://haskell.github.io/cabal-website/doc/html/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).
552
553
553
554
## Hackage Revisions
554
555
555
556
We are reactive rather than proactive with revising bounds on our dependencies
556
557
for code already released on Hackage. If you would benefit from a version bump,
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.)
4
+
5
+
This is a first draft; many things are as yet missing. Open an issue if you need something added here.
* Matthew Pickering ([`@mpickering`](https://github.com/mpickering), [email protected])
14
-
15
-
### How we compose this list
20
+
* Matthew Pickering ([`@mpickering`](https://github.com/mpickering), [email protected])
16
21
17
-
The main goal of the team is to ensure that Cabal is keeping up with the ever-evolving Haskell ecosystem.
18
-
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.
19
-
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.
22
+
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.
20
23
21
24
Successful maintenance requires coordination, and the team engages in three main ways:
22
25
23
26
- attending to issues and PRs on GitHub;
24
27
25
28
- discussing Cabal on the [Matrix channel](https://matrix.to/#/#hackage:matrix.org);
26
29
27
-
- meeting biweekly in video calls with agenda prepared asynchronously in a Markdown document, which also holds the meeting notes.
30
+
- meeting biweekly in video calls with agenda prepared asynchronously in a [Markdown document](https://hackmd.io/ytXS6xrAS2mTyPVxdUS6OA?both), which also holds the meeting notes.
28
31
29
32
Worth noting that the meetings are open to everyone interested in Cabal, especially aspiring and returning Cabal contributors. Ask on Matrix how to join.
30
33
31
-
Most of the current team are volunteers, and we are happy to receive any help.
32
-
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.
34
+
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.
35
+
36
+
37
+
## Workflows
38
+
39
+
The standard workflows are:
40
+
41
+
-`bootstrap.yml`: bootstrap a cabal from prepared JSONs (see `make bootstrap-jsons`)
42
+
-`validate.yml`: build a cabal with extra assertions and run the full test suite on it
43
+
-`changelogs.yml`: validate `changelog.d` files using [`changelog-d`]
44
+
-`dependabot.yml`: check `dependabot` configuration (sadly, not automatic; we lifted this from Ubuntu's CI)
45
+
-`lint.yml`: run `hlint` on cabal sources
46
+
-`format.yml`: check source formatting using Fourmolu v0.12
47
+
-`quick-jobs.yml`: various (formerly) quick checks
48
+
-`release.yaml`: build devel / release binaries for multiple platforms
49
+
-`typos.yml`: look for typos in documentation
50
+
-`users-guide.yml`: generate the users guide, creating an artifact
51
+
-`whitespace.yml`: check for extraneous whitespace in various files
52
+
-`check-sdist.yml`: make sure cabal can be built against the `Cabal` bootlib (see e.g. #10931, #9863)
53
+
-`release.yml`: build release binaries, either as part of a release or for testing
54
+
55
+
The validate workflow performs a number of tests on tier-1 platforms:
56
+
57
+
- 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`)
58
+
- 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
59
+
- it builds but doesn't validate (for some reason) a static `cabal` on Alpine with MUSL
60
+
- it dogfoods `cabal` by having it build itself
61
+
62
+
You can use a manual dispatch on the validate workflow. It has two optional parameters:
63
+
-`allow-newer line` will add an `allow-newer:` entry to the project file. Don't include the prefix.
64
+
-`constraints line` will similarly add a `constraints:` entry.
65
+
66
+
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`.
67
+
68
+
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.)
69
+
70
+
71
+
## Actions
72
+
73
+
Currently there is only one local action:
74
+
75
+
-`reusable-release.yaml`: the actual guts of `release.yaml` above.
76
+
77
+
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.
78
+
79
+
80
+
## Support tiers
81
+
82
+
Currently we support the following platforms as Tier 1:
83
+
84
+
- MacOS on AArch64
85
+
- X86-64 (aka AMD64)
86
+
- Windows (10 and 11)
87
+
88
+
Tier 2 platforms are:
89
+
90
+
- FreeBSD (AMD64 only)
91
+
- Alpine/MUSL static build
92
+
- MacOS on Intel
93
+
- X86 (deprecated)
94
+
- ARM Linux (Debian and Alpine)
95
+
96
+
We do not currently test on tier 2 platforms, but support for that is coming.
97
+
98
+
99
+
## CI
100
+
101
+
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.
102
+
103
+
The rules for PRs on release branches are:
104
+
105
+
- only 1 approval needed for backports via Mergify (`@mergifyio backport branch`), otherwise 2 as usual
106
+
- 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
107
+
108
+
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).
109
+
110
+
111
+
## GPG keys
112
+
113
+
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.
114
+
115
+
116
+
## Releases
117
+
118
+
Notes for how to make a release are at the
119
+
wiki page ["Making a release"](https://github.com/haskell/cabal/wiki/Making-a-release).
120
+
Currently, [@emilypi](https://github.com/emilypi), [@fgaz](https://github.com/fgaz) and [@Mikolaj](https://github.com/Mikolaj) have access to
121
+
`haskell.org/cabal`, and [@Mikolaj](https://github.com/Mikolaj) is the point of contact for getting
122
+
permissions.
123
+
124
+
125
+
## Hackage Revisions
126
+
127
+
We have a CI setup to test that our main pipeline ("Validate") accepts a proposed revision. To use
0 commit comments