Uploading packages
Uploading a package puts it in the main package index so that anyone can download it and view information about it. You can only upload a package version once and this cannot be undone, so try to get it right the first time! To reduce the risk of mistakes it's recommended to use the package candidates feature described below.
Because each package added to the main package index has a cost of operation and maintenance associated to it, your package should strive to provide value for the community by being intended to be useful to others, which entails giving your package a meaningful synopsis/description as well as ensuring your package is installable by helping with providing accurate meta-data.
In the course of the curation process, the Hackage Trustees need to be able to contact you, to inform you about and help you resolve issues with your package (including its meta-data) which affect the Hackage ecosystem.
Packages must be in the form produced by Cabal's sdist command: a gzipped tar file package-version.tar.gz comprising a directory package-version containing a package of that name and version, including package.cabal. See the notes at the bottom of the page.
Package versioning
In order to ensure the integrity and well-functioning of the Hackage/Cabal ecosystem, all packages should follow Haskell's Package Versioning Policy (PVP).
In particular, be aware that although the PVP and SemVer are based on the same concepts they differ significantly in structure and consequently are not compatible with each other. Please consult the PVP/SemVer FAQ section for more details about the differences and related issues.
Open source licenses
The code and other material you upload and distribute via this site must be under an open source license. This is a service operated for the benefit of the community and that is our policy. It is also so that we can operate the service in compliance with copyright laws.
The Hackage operators do not want to be in the business of making judgements on what is and is not a valid open source license, but we retain the right to remove packages that are not under licenses that are open source in spirit, or that conflict with our ability to operate this service. (If you want advice, see the ones Cabal recommends.)
The Hackage operators do not need and are not asking for any rights beyond those granted by the open source license you choose to use. All normal open source licenses grant enough rights to be able to operate this service.
In particular, we expect as a consequence of the license that:
- we have the right to distribute what you have uploaded to other people
- we have the right to distribute certain derivatives and format conversions,
including but not limited to:
- documentation derived from the package
- alternative presentations and formats of code (e.g. html markup)
- excerpts and presentation of package metadata
- modified versions of package metadata
Please make sure that you comply with the license of all code and other material that you upload. For example, check that your tarball includes the license files of any 3rd party code that you include.
Privileges
To upload a package, you'll need a Hackage username and password.
If you upload a package or package candidate and no other versions exist in the package database, you become part of the maintainer group for that package, and you can add other maintainers if you wish. If a maintainer group exists for a package, only its members can upload new versions of that package.
If there is no maintainer, the uploader can remove themselves from the group,
and a package trustee can add anyone who wishes
to assume the responsibility. The Maintainer field of the Cabal file should be
None in this case. If a package is being maintained, any release not approved
and supported by the maintainer should use a different package name. Then use
the Maintainer field as above either to commit to supporting the fork
yourself or to mark it as unsupported.
Package Candidates (Tech Preview)
Package candidates are a way to preview the package page, view any warnings or possible errors you might encounter, and let others install it before publishing it to the main index. (Note: you can view these warnings with 'cabal check'.) You can have multiple candidates for each package at the same time so long as they each have different versions. Finally, you can publish a candidate to the main index if it's not there already.
Package candidates have not yet been fully implemented and are still being improved; see Package Candidates Project Dashboard for an overview of what still needs to be done.
Notes
- You should check that your source bundle builds, including the haddock documentation if it's a library.
-
Categories are determined by whatever you put in the
Categoryfield. You should try to pick existing categories when possible. You can have more than one category, separated by commas. If no other versions of the package exist, the categories automatically become the package's tags. - Occasional changes to the GHC base package can mean that some work needs to be done to make packages compatible across a range of versions. See these notes for some tips in how to do so. There are some notes for upgrading much older packages as well.
-
The hackage-server attempts to build documentation for library
packages, but this can fail. Maintainers can generate their own
documentation and upload it by using something along the lines of the
shell script below (note that the last two commands are the key ones):
#!/bin/sh set -e dir=$(mktemp -d dist-docs.XXXXXX) trap 'rm -r "$dir"' EXIT cabal haddock --builddir="$dir" --for-hackage --haddock-option=--hyperlinked-source # Starting with cabal 2.0, `--publish` is needed for uploading to non-candidate releases cabal upload -d $dir/*-docs.tar.gz