6* New tests are added where applicable
7* Benchmarks are added where applicable
8* Run benchmarks locally if you suspect any regressions
9* Documentation is added for any new combinators
10 * New combinators have time and space complexity annotations
11 * New combinators have `since` annotation
12* Changelog entry is added for exposed combinators.
13* Identify breaking changes, or changes that may require depndency
14 version bound changes. See https://pvp.haskell.org/. Also see the
15 "Breaking changes section below".
16* Optionally, look at hlint output if anything in that is worth fixing.
17* Merge the PR by rebasing. Note that github always creates new commits when
18 merged with rebase, it records the committer as well as the author in the
19 commit. This makes the local branch diverge from master. You can rebase and
20 merge the commit manually in your local git tree and push the resulting
21 master branch to avoid new commits and divergence from the original tree.
25* Check if any critical pending bugs or issues are to be included
26* If this is a major release check if any previously deprecated features are to
27 be removed in this release.
28* Check pre-release APIs to be exposed, especially from streamly-examples
29* PVP is adhered to, additionally do not change pre-release APIs in a
34 * Documentation is updated.
35 * Check if all the links in the docs are stable.
36 * External links might point to the `master` branch of a few
37 repositories. Pin them to a specific version that works with the current
39 * You can run `rg '/blob/'` and `rg '/tree/'` to search for github links.
40 * For example, links that point to `streamly-examples` point to its
41 `master` branch. Instead, while making the release we need to pin the
42 links to a specific revision that works with the latest commit of the
44 * Ideally, the distribution process should automatically replace these
45 with current stable references.
46 * The markdown documentation files have no broken links. See the section
47 about [checking for broken
48 links](#checking-for-broken-links-in-the-markdown-files) for more info.
49 * Haddock docs are consistent with the changes in the release
50 * Tutorial has been updated for new changes
51 * Documents in the `docs` directory are consistent with new changes
52 * All combinators have time and space complexity annotations
53 * All combinators have `since` annotation
54 * Modules that were renamed or APIs that moved to other modules should be
55 marked as "since" the current release.
56 * Check all released modules to ensure that they do not have any leftover
57 `Internal` or `Pre-release` annotations.
58 * Unreleased combinators should be marked with `Pre-release` or
59 `Internal` annotations
60 * Streamly homepage is updated with the release docs
61 * FileSystem.Event.Windows/Darwin modules require special handling
66 * Run tests using bin/test.sh to test with memory restrictions
67 * Manually build and test for all flags (esp. `dev` flag) not covered by CIs
68 * Test prime GHC version with -O0 and -O1
72 * Check regressions from previous release
73 * Run benchmarks with large stream size (`bench.sh --long`) to
74 check for space leaks and to ensure constant memory usage for streaming
76 * Run benchmarks with `dev` flag on. Some `fileio` benchmarks are disabled
78 * Check comparative benchmarks using streaming-benchmarks
82 * Make sure all dependency bounds can use latest versions
83 * Update `stack.yaml` to latest stable resolver, cleanup extra-deps
84 * Make sure fusion-plugin is up to date and uploaded
85 * Check the dependency footprint of the library. See
86 [Generating Dependency Graph](#generating-dependency-graph) section.
88* _Dependent Packages_:
91 [streamly-examples](https://github.com/composewell/streamly-examples)
92 to make sure it runs with the latest release.
93 * Check the performance of examples where applicable
99* _Update Package Metadata:_
101 * Make sure the description in cabal file is in sync with the docs
102 * Make sure CI configs include last three major releases of GHC in CI testing.
103 * Update GHC `tested-with` field
104 * Update `docs/Compiling.md` with the distributions tested with
105 * Any docs linked inside haddock/cabal/changelog or any other such file
106 should go in the extra-doc-files section instead of
107 extra-source-files. Otherwise hackage shows the links as broken.
108 * Make sure any additional files are added to `extra-source-files` in cabal
109 file. Artifacts required for build, test, benchmarks, docs, licenses
110 should be packaged. Build environment customization may or may not be
113* _Copyrights and Contibutors_
115 * Make sure contributors to the release are listed in
116 `docs/CONTRIBUTORS.md`.
117 * Bump the release version in `docs/CONTRIBUTORS.md`.
118 * Make sure any third party code included in the release has been listed in
119 `docs/Credits.md` and the license is added to the repo.
121* _Update changelog & Version_:
123 * Find API changes using `cabal-diff streamly 0.8.2 .` and record
124 them in docs/API-changelog.txt.
125 * Make sure all the bug fixes being included in this release are marked
126 with a target release on github. So that users can search by release if
128 * Bump the package version in configure.ac and run autoreconf
129 * Change the `Unreleased` section at the top of changelog file to the new
130 release version number and the month/year of publishing.
131 * Bump the package version in cabal file or package.yaml
132 * Bump the package version in any docs/links, use something like
133 `rg '0\.8\.'|grep -v -i since` to find any remaining occurrences of the
134 old release. Check `rg -i unreleased` for any remaining todos.
138 * Wait for final CI tests to pass:
140 * Mask out the build status lines from the
141 [docs/Introduction.md](/docs/User/Tutorials/Introduction.md)
143 * Use a clean workspace to create source distribution
144 by freshly cloning the git repository. The reason for
145 doing this is that we use wild-cards in cabal file for
146 `extra-source-files`, these wild-cards may match additional
147 files lying around in the workspace and unintentionally ship
149 * Upload and verify the candidate
150 * `cabal v2-sdist; cabal upload <tarpath>`
151 * `cabal v2-haddock --haddock-for-hackage --enable-doc; cabal upload -d <tarpath>`
152 * Publish the package
153 * `cabal v2-sdist`; `cabal upload --publish <tarpath>`
154 * Run packcheck on the uploaded package. To get the latest uploaded
155 version from hackage, run `cabal unpack <package-name>`. You might
156 have to run `cabal update`.
157 * Create a git tag corresponding to the release where X.Y.Z is the new
158 package version (`git tag vX.Y.Z && git push -f origin vX.Y.Z`).
159 * Add to stackage (`build-constraints.yaml` in Stackage repo) if needed
160 * Optionally upload `package-X.Y.Z-sdist.tar.gz` to github release page
161 * `gh release create vX.Y.Z --title "vX.Y.Z"`
162 * `gh release upload vX.Y.Z package-X.Y.Z-sdist.tar.gz`
163 * Update release contributors on github release page
164 (`git shortlog -s prev_tag..new_tag | sed $'s/^[0-9 \t]*/* /' | sort -f`)
165 * Update and if needed release streaming-benchmarks package
166 * Check https://matrix.hackage.haskell.org/package/streamly
167 * Check haddocks on Hackage, upload if not built
168 * Announce to haskell-cafe@haskell.org
172This section lists what constitutes breaking changes. See
173https://pvp.haskell.org/ breaking changes that can be determined by the
174API alone. We specify some additional recommendations here:
176Behavior changes, this kind of changes are nasty and should be avoided. If such
177changes are made they should be emphasized adequately in the changelog:
179* Silent changes in the behavior of an API without any changes to the
181* Even fixing a bug could break things as users may have employed workarounds
183* Changes in the behavior of a dependency may also cause a change in behavior.
185Be cautious about the following:
187* Change in version bounds of dependencies may cause compilation failure for
188 some programs because they may not be able to find a build plan.
189* Ideally, new warnings should not be considered breaking, dependencies
190 should never be compiled with -Werror. But packages may not be following
192* Deprecating an API may issue new warnings, however the code can still be
193 compiled if warnings are not treated as errors.
197* Internal APIs can change without having to change the major version. However,
198 we should try to align the Internal API changes with a major release as long
203We label the issues in different dimensions based on the lifecyle and different
204management aspects of the issue. The folowing sections discuss the labels used
205to manage the issues. If a new label is required, it should be discussed before
210The level-1 triaging of the issue determines the current disposition
211of the issue. If no change is required the issue must have one of the
215* disposition:question
216* disposition:discussion
217* disposition:duplicate
220If a change is required we need to do level-2 triage of the issue, see the
225When a change is required we need to put one of the __change type__
226labels as part of level-2 triaging:
228* type:performance: User visible impact on performance.
229* type:testing: Improves testing or related to testing.
230* type:usability: It is not convenient to use the library.
231* type:documentation: documentation is not correct or sufficient.
232* type:bug: A functionality issue, not working as expected.
233* type:enhancement: includes a new feature or enhancement
234* type:maintenance: A refactor or any other change with no user visible impact.
238In addition we can put a __product aspect__ label describing a feature name or
239any other product specific classification bucket.
241* aspect:<aspect name>
245Optionally we can add a severity label to indicate how severe is the
246impact of the bug/issue, which may determine how important it is to fix it. By
247default the severity is normal, if it is high we put a label:
253For a user visible issue whether it has a release/changelog impact:
255* api:new: includes a new feature or enhancement
256* api:breaking: has a breaking impact on existing deployments
257* api:deprecating: deprecates an existing functionality
259__RULE__: Any commit that may affect the end user in some way MUST have
260either a changelog entry OR MUST have an issue marked with one of the
265By default the issues are normal priority. We use a label for high priority
272If the issue is assigned to someone then it is considered scheduled. Otherwise
273it is unscheduled. Unassigned issues may have the following labels:
275* sched:deferred: deliberately deferred for some reason.
276* sched:blocked: blocked on any other fix or a decision to be mad
280* help-wanted: anyone can take the issue and contribute
281* good-first-issue: good for new contributors
283## Correlating Changes, Issues and Releases
285For planning purposes, open issues may be marked with milestones or target
286releases. However, it may not always be known which release a fix will finally
287land in. For example, we may decide to make a minor release instead of a major
288one if there are no breaking changes yet, so we may not always know what would
289be the next release version.
291Trackability means that we should be able to find which issues got fixed in
292which release. Or what all issues got fixed in a particular release. We track
293significant changes using the changelog. However, there may be more changes
294that can only be tracked via issues, PRs or commits. When we make a release we
295can mark all the issues fixed in that release with a correct release target for
298For better trackability of which issue got fixed in which release we need the
301* Before you close an issue make sure a commit or a PR fixing the issue is
302 attached with it. In the commit message you can reference an issue like
303 "fixes #50", you can do the same in a PR as well.
304* Before we make a new release EVERY issue with a commit included in that
305 release that affects the end user, especially bugs and breaking changes MUST
306 have the target release correctly set.
308## Changelog Management
310Keep the unreleased changes in the `Unreleased` section at the top of changelog
311file. Using `Unreleased` instead of the next release number for unreleased
312changes is important. First, we do not know the next release number in advance,
313it could be a major or minor release. Second, if we use the next release
314number instead, then when adding a new change to the changelog, at one look we
315cannot know whether the release number on top is unreleased or released.
319* GPG signed releases and tags
321## Generating Dependency Graph
323Ways to get the dependencies. In the streamly package top dir:
326# Keep only streamly in the packages section of stack.yaml
327$ stack --system-ghc dot . --external|dot -Tpdf > streamly.pdf
330Using nix, remove the test and benchmark components from
331`shellFor/packages` in `default.nix` to get library only
332dependencies. May show additional ghc boot libraries.
335$ nix-shell --run "ghc-pkg dot | dot -Tpdf > streamly.pdf"
338## Checking for broken symlinks
340The following command - when run from the repository root - finds all the
341broken symlinks in the project.
345 -not -path "./dist*" \
346 -not -path "./.stack*" \
347 -not -path "./benchmark/bench-report/dist*"
350## Checking for broken links in the markdown files
352You can use [markdown-link-check](https://github.com/tcort/markdown-link-check)
353for finding broken links.
355You can run it using `npx` like so:
357npx markdown-link-check <markdown-file>
360The following command - when run from the repository root - finds all the
361markdown files that we need to consider:
364find . -type f -name "*.md" \
365 -not -path "./dist*" \
366 -not -path "./.stack*" \
367 -not -path "./benchmark/bench-report/dist*"
370The following executes the markdown link checking with proper configuration on
371the results. This also checks all the links are absolute to the root of the
375find . -type f -name "*.md" \
376 -not -path "./dist*" \
377 -not -path "./.stack*" \
378 -not -path "./benchmark/bench-report/dist*" \
379 -exec npx markdown-link-check -c /dev/stdin --quiet {} \; <<EOF
392 "replacementPatterns": [
394 "pattern": "^", "replacement": "{{BASEURL}}"
401Once you run that, you can check all the links again without the config,
402filtering in only `http`, `ftp`, and `mailto` links.
405find . -type f -name "*.md" \
406 -not -path "./dist*" \
407 -not -path "./.stack*" \
408 -not -path "./benchmark/bench-report/dist*" \
409 -exec npx markdown-link-check --quiet {} \; 2>&1 | grep -e "http" -e "ftp" -e "mailto"
keysesc to close
- j k
- move down, up
- enter
- open
- esc
- back, or up a level
- 1 2 3 4
- readme, files, commits, refs
- /
- filter
- y
- copy the clone command
- c
- compare the chosen commit with another (or shift-click both)
- ?
- show or hide this list