|
| 1 | +# Haskell package metadata |
| 2 | + |
| 3 | +Haskell packages have a lot of metadata that can be provided via `.cabal` files. |
| 4 | +This policy gives guidance on what to put in the various fields. |
| 5 | +See [the cabal documentation](https://cabal.readthedocs.io/en/stable/cabal-package.html#package-properties) for what these fields mean. |
| 6 | + |
| 7 | +| Field | Policy | Example | Rationale | |
| 8 | +|----------------------|-------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------| |
| 9 | +| `name` | Required by cabal. | `plutus-core` | | |
| 10 | +| `version` | Required by cabal. | `1.0.0` | | |
| 11 | +| `cabal-version` | Should be at least `3.4`. | `3.6` | `3.4` is somewhat recent and removes some warts. | |
| 12 | +| `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. | |
| 13 | +| `license` | Must be `Apache-2.0` | `Apache-2.0` | See the [legal policy page](../../legal/index.html). | |
| 14 | +| `license-file` | Omit in favour of `license-files`. | | Apache 2.0 requires multiple license files. | |
| 15 | +| `license-files` | Must include both `LICENSE` and `NOTICE`. | `LICENSE NOTICE` | See the [legal policy page](../../legal/index.html). | |
| 16 | +| `copyright` | Omit. | | See the [legal policy page](../../legal/index.html). | |
| 17 | +| `author` | Omit. | | Typically there is no clear single author of a package. | |
| 18 | +| `maintainer` | Optional, should be a person with significant responsibility according to the [project docs ](../../project/index.html). | `[email protected]` | We don't have more reliable and persistent maintainer email addresses than people's personal ones, so we have to use those if anything. | |
| 19 | +| `stability` | Omit. | | This is not usually meaningful for us, and is not widely used even in the Haskell OSS community. | |
| 20 | +| `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` | | |
| 21 | +| `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. | |
| 22 | +| `package-url` | Omit. | | Not relevant. | |
| 23 | +| `synopsis` | No policy. | | | |
| 24 | +| `description` | No policy. | | | |
| 25 | +| `category` | Omit. | | This has never really caught on even in the Haskell OSS community. | |
| 26 | +| `tested-with` | Omit. | | This is not checked and there are almost no tools that actually use it, so it provides little value. | |
| 27 | +| `data-files` | No policy. | | | |
| 28 | +| `data-dir` | No policy. | | | |
| 29 | +| `extra-source-files` | No policy. | | | |
| 30 | +| `extra-doc-files` | The [`CHANGELOG` file](../../project/index.html) should be included here. | | | |
| 31 | +| `extra-tmp-files` | No policy. | | | |
0 commit comments