Uploading packages and package candidates

Uploading packages

Upload and publish a package permanently: Upload

Uploading a package puts it in the 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.

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 and curation

By default, uploaded packages are curated which means that both maintainers and hackage trustees may revise their metadata (particularly involving version bounds) to guide build tools in producing install-plans. (For more information on revisions, see the FAQ).

In order to ensure the integrity and well-functioning of the Hackage/Cabal ecosystem, all curated 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.

Further, an important property of the PVP contract is that it can only be effective and provide strong enough guarantees if it is followed not only by an individual package, but also by that package's transitive dependencies. Consequently, packages which are curated should aim to depend only on other curated packages.

In the course of the curation process, the Hackage Trustees need to be able to contact package maintainers, to inform them about and help to resolve issues with their packages (including its meta-data) which affect the Hackage ecosystem.

Package uploaders may choose to exclude individual package uploads from curation, by setting the x-curation: field of the package's cabal file to uncurated. Packages which are uncurated have no expectations on them regarding versioning policy. Trustees or maintainers may adopt uncurated packages into the curated layer through metadata revisions. Metadata revisions must not set the value of the x-curation field to any variant of uncurated.

Two variants of the uncurated property are supported. First, uncurated-no-trustee-contact, which indicates that maintainers do not wish to be contacted by trustees regarding any metadata issues with the package. (Contact may still occur over issues that are not related to curation, such as licensing, etc.). Second, uncurated-seeking-adoption, which indicates that maintainers would like their package to be adopted in the curated layer, but currently some issue prevents this, which they would like assistance with.

In the future, metadata regarding curation will be made available in the UI of Hackage, and different derived indexes will be provided for the uncurated and curated layers of packages.

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.

Public repositories

It is preferable if any web pages linked from the following fields are publicly accessible:

Bug report URL
Homepage URL
Source repositories

In particular, where these fields refer to a repository, a public repository is preferable. This gives users access to existing issues (e.g. to check for duplicates before raising a bug) and package version history. It also enables users to gauge whether packages are being actively maintained or developed. That said, links to private repositories are acceptable, just not as useful.

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.

Group Accounts

Occasionally organizations want to have a group / organizational account for a package that is maintained by a group of people. The recommended approach for these cases is to only do package uploads from individual accounts and use the group account only for managing the maintainer list for the package.

Package Candidates

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.

Upload a package candidate

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 Category field. 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

# assumes cabal 2.4 or later
cabal v2-haddock --builddir="$dir" --haddock-for-hackage --enable-doc

cabal upload -d --publish $dir/*-docs.tar.gz
```