hkgr
Simple Hackage release workflow for package maintainers
LTS Haskell 22.37: | 0.4.6 |
Stackage Nightly 2024-10-11: | 0.4.6 |
Latest on Hackage: | 0.4.6 |
hkgr-0.4.6@sha256:fee228c56ba641b68995b0372f305dd1ac4bfd6eaf148effd8f9c8f1e1e5abf3,2331
Module documentation for 0.4.6
There are no documented modules for this package.
Hkgr
hkgr
(pronounced “hackager”) is a tool for making releases of
Haskell packages on Hackage.
It uses a cautious stepped iterative 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.4
No errors or warnings could be found in the package.
Running hlint
src/Main.hs:(407,9)-(408,55): Warning: Eta reduce
Found:
replaceHolder lbl val file
= sed ["s/@" ++ lbl ++ "@/" ++ val ++ "/"] file
Perhaps:
replaceHolder lbl val = sed ["s/@" ++ lbl ++ "@/" ++ val ++ "/"]
[]
["src/Main.hs","data/template.cabal.tmpl","README.md","CHANGELOG.md","LICENSE","hkgr.cabal"]
[(NoExec,"CHANGELOG.md"),(NoExec,"LICENSE"),(NoExec,"README.md"),(NoExec,"data/template.cabal.tmpl"),(NoExec,"hkgr.cabal"),(NoExec,"src/Main.hs")]
Wrote tarball sdist to /home/petersen/github/hkgr/.hkgr/hkgr-0.4.tar.gz
After fixing up, retag a new tarball with --force
and upload candidate,
in one go:
$ hkgr upload -f
Updated tag 'v0.4' (was f6d72ba)
No errors or warnings could be found in the package.
Running hlint
[]
["src/Main.hs","data/template.cabal.tmpl","README.md","CHANGELOG.md","LICENSE","hkgr.cabal"]
[(NoExec,"CHANGELOG.md"),(NoExec,"LICENSE"),(NoExec,"README.md"),(NoExec,"data/template.cabal.tmpl"),(NoExec,"hkgr.cabal"),(NoExec,"src/Main.hs")]
Wrote tarball sdist to /home/petersen/github/hkgr/.hkgr/hkgr-0.4.tar.gz
hackage.haskell.org password:
Uploaded to https://hackage.haskell.org/package/hkgr-0.4/candidate
Alternatively if you had manually tagged the release with v0.4
you can use hkgr tagdist --existing-tag
to create a dist tarball.
One can continue to tagdist -f
and/or upload -f
until
everything looks good and CI passed etc.
Then it is time to push the final tag and publish the release:
$ hkgr publish
git pushing... done
Total 0 (delta 0), reused 0 (delta 0), pack-reused 0
To github.com:juhp/hkgr.git
* [new tag] v0.4 -> v0.4
hackage.haskell.org password:
Published at https://hackage.haskell.org/package/hkgr-0.4
Help
$ hkgr --version
0.4.6
$ hkgr --help
Hackage Release tool
Usage: hkgr [--version] COMMAND
'Hackager' is a package release tool for easy Hackage workflow
Available options:
-h,--help Show this help text
--version Show version
Available commands:
new setup a new project
tagdist 'git tag' version and 'cabal sdist' tarball
upload 'cabal upload' candidate tarball to Hackage
publish git push and cabal upload --publish
upload-haddock Upload candidate documentation to Hackage
publish-haddock Publish documentation to Hackage
build Do a local pristine build from the tarball
version Show the package version from .cabal file
rename Rename the Cabal package
github Add github repo
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, until the version is bumped.
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 --existing-tag
to create a dist tarball.
upload
hkgr upload
uploads the tarball to Hackage as a candidate release.
Like hkgr tagdist -f
, hkgr upload -f
can be repeated.
Haddock draft documentation can also be uploaded once if desired
with hkgr upload-haddock
.
If you have an existing version tag (starting with v
) you can use
the --existing-tag
option to skip the tagging step (like for tagdist
).
publish
hkgr publish
releases the tarball to Hackage, after doing a pristine
local build and git pushing the tag and its commits to origin.
If it succeeds, then hkgr creates a “published lockfile” in .hkgr/
.
(Then hkgr will refuse to do further commands on the released version.)
Optionally one can publish haddock docs with hkgr publish-haddock
.
build
hkgr build
will try to do a pristine build of the latest created tarball
for the tag. This is useful for catching missing files from the tarball,
preventing brownbag releases.
new
hkgr new
creates a new project.
If you don’t pass a name it will try to check the current directory.
It uses 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.
A stack.yaml
file and git repo is also set up.
github
(One can use gh repo create
etc to create the project repo on Github)
and then hkgr github
to add the github remote to your project.
Requirements
hkgr uses cabal-install
>=2, git
, and also hlint
if available.
Contribute
hkgr
is licensed and distributed under the GPL version 3 or later.
Reports and contributions are welcome at https://github.com/juhp/hkgr.
Changes
Changelog
0.4.6 (2024-06-20)
- ‘new’: add –license option
- ‘new’: bump stack.yaml resolver to lts-21
- add missing SUMMARY placeholder to template
0.4.5 (2024-05-23)
- ‘tagdist’, ‘upload’: also do pristine cabal build unless –no-build
0.4.4 (2024-05-03)
- .cabal template: add autogen-modules and update tested-with ghc versions
- publish,build: output message before cabal build
- use simple-cmd +-+
0.4.3.2 (2023-10-20)
- use a cabal.project for pristine sdist/build to ignore any parent project
- .cabal template: updated tested-with ghc versions
0.4.3.1 (2023-07-05)
- fix the template file SPDX license tag and cabal-version field placement
0.4.3 (2023-05-30)
- bump template to Cabal 2.2
- add pristine ‘build’ command: used before publish
- use haskeline for reading user/passwd via simple-prompt
0.4.2 (2022-06-24)
- ‘new’: need cabal init –license option, otherwise no LICENSE file is created
- ‘github’: new command to add github remote for project
0.4.1 (2022-06-23)
- ‘rename’ improvements
- ‘new’: avoid error on cabal >= 3.4 by not passing –license to cabal init
0.4 (2022-03-27)
- template.cabal: use cabal 2.0 and define hs-source-dirs
- ‘tagdist –existing-tag’ replaces ‘dist’ command
- ‘upload’: add –existing-tag for dist rather than tagdist
- ‘new’: stack init with lts-17
- ‘rename’: experimental command to rename a project
- add ‘–no-hlint’ option to skip running hlint (also hlint is no longer run for ‘publish’)
0.3 (2020-05-07)
- 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
0.2.7 (2020-02-27)
- 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
0.2.6.1 (2020-07-30)
- upload: do not hide output since it conceals any error
- new: improvements to work better with cabal-3.0 init
0.2.6 (2020-06-11)
- tagdist: include existing tag in error message
- experimental ‘new’ project command with user template file
~/.config/hkgr/template.cabal
- switch to cabal v2-sdist
- upload: display error correctly
- upload: add –force switch - to refresh tag and tarball
0.2.5.2 (2020-02-29)
- no hlint summary
- fix published message
0.2.5.1 (2020-02-29)
- improve output for hlint and uploaded url
- also check for staged changes
0.2.5 (2020-02-29)
- check that package version is committed
- use quiet cabal v1-configure and v1-sdist commands
- make cabal upload quiet
0.2.4.1 (2020-02-11)
- assert that cabal-install installed
- run hlint in git checkout instead of working tree
0.2.4 (2019-10-05)
- git push before publishing
- only push up to tag
0.2.3 (2019-09-30)
- 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
0.2.2 (2019-07-06)
- run hlint before git tag
- relax force sdist when no existing tarball
- show git diff to warn project dirty
0.2.1 (2019-06-24)
- fix creation of published symlink lockfile
- tagdist before
cabal upload
if no tarball
0.2 (2019-06-24)
- merge tag and dist commands into tagdist
- if sdist fails then reset tag
- drop push-tags command
0.1 (2019-06-24)
- add published lock file: prevents tagging/dist/upload after publish
- tag before sdist if no tag
- push tag after publishing
0.0 (2019-06-08)
- Initially created.