git.iko.soy/streamly
on 9183e21 help sign in
streamly/MAINTAINING.md
154 lines 5.9 kB history raw
1# Maintainers' Guide
3## PR Merge Checklist
5* All the CI tests pass
6* New tests are added where applicable
7* Benchmarks are added where applicable
8* hlint
9* Run benchmarks locally if you suspect any regressions
10* If the PR is by someone other than you yourself then merge with a merge
11 commit, otherwise merge by rebasing on master without a separate merge
12 commit.
14## Release Checklist
16* Check if any critical pending bugs or issues are to be included
17* If this is a major release check if any previously deprecated features are to
18 be removed in this release.
19* _Documentation_:
21 * Update the README if needed.
22 * Make sure haddock docs are consistent with the changes in the release
23 * Make sure tutorial has been updated for new changes
24 * Make sure documents in the docs directory are consistent with new changes
26* _Benchmarks_:
28 * Check regressions from previous release
29 * Check comparative benchmarks using streaming-benchmarks
31* _Update Package Metadata:_
33 * Update `stack.yaml` to latest stable resolver, cleanup extra-deps
34 * Make sure the description in cabal file is in sync with README and other docs
35 * Make sure CI configs include last three major releases of GHC in CI testing.
36 * Update `tested-with` field
37 * Make sure all dependency bounds can use latest versions
39* _Update changelog & Version_:
41 * Change the `Unreleased` section at the top of changelog file to the new
42 release version number.
43 * Make sure contributors to the release are listed in
44 `credits/CONTRIBUTORS.md`.
45 * Make sure any third party code included in the release has been listed in
46 `credits/COPYRIGHTS.md` and the license is added to the repo.
47 * Make sure all the bug fixes being included in this release are marked
48 with a target release on github. So that users can search by release if
49 they want.
50 * Add "Since" notations to the new APIs introduced in this release
51 * Bump the package version in cabal file or package.yaml
53* _Upload_:
55 * Wait for final CI tests to pass:
57 * Create a git tag corresponding to the release where X.Y.Z is the new
58 package version (`git tag vX.Y.Z && git push -f origin vX.Y.Z`).
59 * Mask out the build status lines from the README
60 * Upload to hackage
61 * `cabal v2-sdist`; `cabal upload --publish <tarpath>`
62 * `stack upload .`
63 * Add to stackage (`build-constraints.yaml` in Stackage repo) if needed
64 * Optionally upload `package-X.Y.Z-sdist.tar.gz` to github release page
65 * Update release contributors on github release page
66 (`git shortlog -s prev_tag..new_tag | sed $'s/^[0-9 \t]*/* /' | sort -f`)
67 * Update and if needed release streaming-benchmarks package
68 * Check https://matrix.hackage.haskell.org/package/streamly
69 * Check haddocks on Hackage, upload if not built
70 * Announce to haskell-cafe@haskell.org
72## Managing Issues
74### User Impacting Changes
76__RULE__: Any commit that may affect the end user in some way MUST have either a
77changelog entry OR MUST have an issue marked with one of the following labels
78OR both. We can have more than one of these labels on the same issue e.g.
79breaking, enhancement:
81* breaking
82* deprecating
83* enhancement
84* performance
85* usability
86* documentation
87* bug
89Note that if you are making a big feature change you may have a single issue
90for that feature and attach many commits with it. So you do not necessarily
91need to have an issue for each commit.
93### Maintenance Changes
95Commits that do not impact the end user in any way are not required to have a
96changelog entry or an issue. Issues that do not have a corresponding commit
97may be left without a label but preferably should be marked with one of the
98following:
100* question
101* discussion
102* maintenance
103* testing
104* invalid
105* wontfix
107### Feature Labels
109For big features with many issues we can introduce a custom feature label to
110group the issues together.
112### Other Labels
114* help wanted
115* duplicate
116* deferred
118## Correlating Changes, Issues and Releases
120For planning purposes, open issues may be marked with milestones or target
121releases. However, it may not always be known which release a fix will finally
122land in. For example, we may decide to make a minor release instead of a major
123one if there are no breaking changes yet, so we may not always know what would
124be the next release version.
126Trackability means that we should be able to find which issues got fixed in
127which release. Or what all issues got fixed in a particular release. We track
128significant changes using the changelog. However, there may be more changes
129that can only be tracked via issues, PRs or commits. When we make a release we
130can mark all the issues fixed in that release with a correct release target for
131future trackability.
133For better trackability of which issue got fixed in which release we need the
134following:
136* Before you close an issue make sure a commit or a PR fixing the issue is
137 attached with it. In the commit message you can reference an issue like
138 "fixes #50", you can do the same in a PR as well.
139* Before we make a new release EVERY issue with a commit included in that
140 release that affects the end user, especially bugs and breaking changes MUST
141 have the target release correctly set.
143## Changelog Management
145Keep the unreleased changes in the `Unreleased` section at the top of changelog
146file. Using `Unreleased` instead of the next release number for unreleased
147changes is important. First, we do not know the next release number in advance,
148it could be a major or minor release. Second, if we use the next release
149number instead, then when adding a new change to the changelog, at one look we
150cannot know whether the release number on top is unreleased or released.
152## TODO
154* GPG signed releases and tags