Simple Hackage release workflow for package maintainers
|Version on this page:||0.3|
|LTS Haskell 20.15:||0.4.2|
|Stackage Nightly 2023-03-23:||0.4.2|
|Latest on Hackage:||0.4.2|
Module documentation for 0.3
There are no documented modules for this package.
hkgr (pronounced “hackager”) is a tool for making releases of
Haskell packages on Hackage.
It uses a cautious stepped approach to releases.
Here is an example of doing a release of hkgr itself.
After committing the latest changes for the release, create a tag and tarball:
$ hkgr tagdist v0.2.5 No errors or warnings could be found in the package. Running hlint ./Main.hs:107:28: Warning: Redundant do Found: do void $ cmdBool "hlint" ["."] Perhaps: void $ cmdBool "hlint" ["."] Resolving dependencies... Configuring hkgr-0.2.5... Building source dist for hkgr-0.2.5... Preprocessing executable 'hkgr' for hkgr-0.2.5.. Source tarball created: dist/hkgr-0.2.5.tar.gz
After fixing up, retag a new tarball:
$ hkgr tagdist -f Updated tag 'v0.2.5' (was 55b69db) No errors or warnings could be found in the package. Running hlint Resolving dependencies... Configuring hkgr-0.2.5... Building source dist for hkgr-0.2.5... Preprocessing executable 'hkgr' for hkgr-0.2.5.. Source tarball created: dist/hkgr-0.2.5.tar.gz
Alternatively if you have manually tagged the version
vX.Y.Z you can use
hkgr dist to create a tarball.
The tarball can now be uploaded to Hackage as a candidate release:
$ hkgr upload Uploaded to https://hackage.haskell.org/package/hkgr-0.2.5/candidate
One can continue to
tagdist -f and
everything looks good and CI passed etc,
then it is time to push the final tag and publish the release:
$ hkgr publish Everything up-to-date Total 0 (delta 0), reused 0 (delta 0) To github.com:juhp/hkgr.git * [new tag] v0.2.5 -> v0.2.5 Published at https://hackage.haskell.org/package/hkgr-0.2.5
hkgr tagdist makes a dist tarball from a git tag:
tagdist command first reads the current package version
.cabal file in the current directory), and uses that to
It then runs
cabal sdist from a temporary pristine checkout of the tag
to generate the dist tarball.
Note that hkgr is lenient: it allows making a release with uncommitted changes in the working tree, but it will show the uncommitted changes. However the version must be committed.
If the tag already exists (eg if you already ran
and you need to add commits to the release
you can use
--force to move the tag to the latest commit
and generate a new tarball off that,
tagdist refuses to run again to prevent accidently overwriting
the tag and dist tarball.
One should not be able to
tagdist on an already published
(ie released) version made with hkgr.
If sdist fails for some reason then hkgr tries to reset the tag.
Alternatively if you have already manually tagged a release with ‘v’ prefix
you can use
hkgr dist to create a tarball.
hkgr upload uploads the tarball to Hackage as a candidate release.
hkgr tagdist -f, this can be repeated.
Haddock draft documentation can also be uploaded if desired with
hkgr publish releases the tarball to Hackage.
If it succeeds then hkgr creates a “published lockfile” in
and the git tag is pushed to origin.
(Then hkgr will refuse to do further commands on the released version.)
Optionally one can publish haddock docs with
hkgr new creates a new project.
If you don’t pass a name it will try to check the current directory.
cabal init to setup various files but replaces the .cabal file
with a template stored in
~/.config/hkgr/template.cabal which the user
can freely customize.
stack.yaml file and git repo is also set up.
One can use
hub create etc to create the project on Github.
git, and also
hlint if available.
- only read Hackage username/password if not in ~/.cabal/config
- ‘upload’: show newer untagged commits
- ‘dist’: new command for a manually tagged release
- fix the check for package version committed
- Main.hs: explicitly export main and add SPDX-License-Identifier
- move Main.hs to src/
- handle git submodules (not –recursive yet)
- use typed-process to interleave IO to display auth errors
- check name and .cabal filename consistent
- put tarballs in .hkgr/
- upload: error if tag no longer on branch
- publish: only push up to tag
- upload: do not hide output since it conceals any error
- new: improvements to work better with cabal-3.0 init
- tagdist: include existing tag in error message
- experimental ‘new’ project command with user template file
- switch to cabal v2-sdist
- upload: display error correctly
- upload: add –force switch - to refresh tag and tarball
- no hlint summary
- fix published message
- improve output for hlint and uploaded url
- also check for staged changes
- check that package version is committed
- use quiet cabal v1-configure and v1-sdist commands
- make cabal upload quiet
- assert that cabal-install installed
- run hlint in git checkout instead of working tree
- git push before publishing
- only push up to tag
- push git tag
- hlint is now a warning not an error
- prefix version tags with v
- surround git diff output with quote lines
- catch exception for sdist
- run hlint before git tag
- relax force sdist when no existing tarball
- show git diff to warn project dirty
- fix creation of published symlink lockfile
- tagdist before
cabal uploadif no tarball
- merge tag and dist commands into tagdist
- if sdist fails then reset tag
- drop push-tags command
- add published lock file: prevents tagging/dist/upload after publish
- tag before sdist if no tag
- push tag after publishing
- Initially created.