-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Add a page on cabal package metadata
- Loading branch information
Showing
2 changed files
with
32 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,31 @@ | ||
| # Haskell package metadata | ||
|
|
||
| Haskell packages have a lot of metadata that can be provided via `.cabal` files. | ||
| This policy gives guidance on what to put in the various fields. | ||
| See [the cabal documentation](https://cabal.readthedocs.io/en/stable/cabal-package.html#package-properties) for what these fields mean. | ||
|
|
||
| | Field | Policy | Example | Rationale | | ||
| |----------------------|------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------| | ||
| | `name` | Required by cabal. | `plutus-core` | | | ||
| | `version` | Required by cabal. | `1.0.0` | | | ||
| | `cabal-version` | Should be at least `3.4`. | `3.6` | `3.4` is somewhat recent and removes some warts. | | ||
| | `build-type` | Strongly prefer `Simple` and do not include `Setup.hs`. `Custom` can occasionally be necessary. | `Simple` | All build types other than `Simple` have bad tooling support and are surprising to developers. | | ||
| | `license` | Must be `Apache-2.0` | `Apache-2.0` | See the [legal policy page](../../legal/index.html). | | ||
| | `license-file` | Omit in favour of `license-files`. | | Apache 2.0 requires multiple license files. | | ||
| | `license-files` | Must include both `LICENSE` and `NOTICE`. | `LICENSE NOTICE` | See the [legal policy page](../../legal/index.html). | | ||
| | `copyright` | Omit. | | See the [legal policy page](../../legal/index.html). | | ||
| | `author` | Omit. | | Typically there is no clear single author of a package. | | ||
| | `maintainer` | Optional, should be a person with significant responsibility according to the [project docs](../../project/index.html). | `john@iohk.io` | We don't have more reliable and persistent maintainer email addresses than people's personal ones, so we have to use those if anything. | | ||
| | `stability` | Omit. | | This is not usually meaningful for us, and is not widely used even in the Haskell OSS community. | | ||
| | `homepage` | Optional, if the project has a webpage, then use that, otherwise a github link usually works well. | `https://github.com/input-output-hk/plutus` | | | ||
| | `bug-reports` | Optional, should be the github issues link, or wherever community-reported issues are expected to go. | `https://github.com/input-output-hk/plutus/issues` | Github is usually our only public issue tracker. | | ||
| | `package-url` | Omit. | | Not relevant. | | ||
| | `synopsis` | No policy. | | | | ||
| | `description` | No policy. | | | | ||
| | `category` | Omit. | | This has never really caught on even in the Haskell OSS community. | | ||
| | `tested-with` | Omit. | | This is not checked and there are almost no tools that actually use it, so it provides little value. | | ||
| | `data-files` | No policy. | | | | ||
| | `data-dir` | No policy. | | | | ||
| | `extra-source-files` | No policy. | | | | ||
| | `extra-doc-files` | The [`CHANGELOG` file](../../project/index.html) should be included here. | | | | ||
| | `extra-tmp-files` | No policy. | | | |