hkgr: Simple Hackage release workflow for package maintainers

[ gpl, program, util ] [ Propose Tags ]

Hkgr (pronounced Hackager) is a tool to help make new releases of Haskell packages, with commands for git tagging, pristine sdist, and uploading to Hackage.


[Skip to Readme]
Versions [faq] 0.0, 0.1, 0.2, 0.2.1, 0.2.2, 0.2.3, 0.2.3.1, 0.2.3.2, 0.2.3.3, 0.2.4, 0.2.4.1, 0.2.5, 0.2.5.1, 0.2.5.2 (info)
Change log CHANGELOG.md
Dependencies base (<5), directory (>=1.3.1.0), filepath, semigroups, simple-cabal (>=0.1.0), simple-cmd (>=0.2.0), simple-cmd-args (>=0.1.1) [details]
License GPL-3.0-only
Copyright 2019-2020 Jens Petersen
Author Jens Petersen
Maintainer juhpetersen@gmail.com
Category Util
Home page https://github.com/juhp/hkgr
Bug tracker https://github.com/juhp/hkgr/issues
Source repo head: git clone https://github.com/juhp/hkgr.git
Uploaded by JensPetersen at 2020-02-29T08:00:21Z
Distributions NixOS:0.2.5.2, Stackage:0.0
Executables hkgr
Downloads 2937 total (275 in the last 30 days)
Rating (no votes yet) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Hackage Matrix CI
Docs not available [build log]
Last success reported on 2020-02-29 [all 2 reports]

Downloads

Maintainer's Corner

For package maintainers and hackage trustees


Readme for hkgr-0.2.5.2

[back to package description]

Hkgr

Hackage GPL-3 license Build status

hkgr (pronounced "hackager") is a tool for making releases of Haskell packages on Hackage.

It uses a cautious stepped approach to releases.

Example usage

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

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 upload until 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

Details

tagdist

hkgr tagdist makes a dist tarball from a git tag:

The tagdist command first reads the current package version (from the .cabal file in the current directory), and uses that to git tag. 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 tagdist earlier), 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, otherwise 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.

upload

hkgr upload uploads the tarball to Hackage as a candidate release. Like hkgr tagdist -f, this can be repeated.

Haddock draft documentation can also be uploaded if desired with hkgr upload-haddock.

publish

hkgr publish releases the tarball to Hackage.

If it succeeds then hkgr creates a "published lockfile" in dist/, 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 publish-haddock.

Requirements

hkgr uses cabal-install >=2, git, and also hlint if available.