From 77bc55beb81f945041bdae14173d855e62cd46b2 Mon Sep 17 00:00:00 2001 From: Mike Pilgrem Date: Tue, 19 Dec 2023 23:43:21 +0000 Subject: [PATCH] Add CONTRIBUTING.md (based on Stack's, cut down) --- CONTRIBUTING.md | 298 ++++++++++++++++++++++++++++++++++++++++++++++++ package.yaml | 1 + pantry.cabal | 1 + 3 files changed, 300 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..447d6fdc --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,298 @@ +# Contributors Guide + +Thank you for considering contributing to the maintenance or development of +pantry! We hope that the following information will encourage and assist you. We +start with some advice about pantry's governance. + +## pantry's governance + +People involved in maintaining or developing pantry with rights to make commits +to the repository can be classified into two groups: 'committers' and +'maintainers'. + +### pantry's committers + +We encourages a wide range of people to be granted rights to make commits to the +repository. + +People are encouraged to take initiative to make non-controversial changes, such +as documentation improvements, bug fixes, performance improvements, and feature enhancements. + +Maintainers should be included in discussions of controversial changes and +tricky code changes. + +Our general approach is **"it's easier to ask forgiveness than permission"**. If +there is ever a bad change, it can always be rolled back. + +### pantry's maintainers + +pantry's maintainers are long-term contributors to the project. Michael Snoyman +(@snoyberg) was the founder of pantry, and its initial maintainer - and he has +added others. Michael's current interests and priorities mean that he is no +longer actively involved in adding new features to pantry. + +Maintainers are recognized for their contributions including: + +* Direct code contribution +* Review of pull requests +* Interactions on the GitHub issue tracker + +The maintainer team make certain decisions when that is necessary, specifically: + +* How to proceed, if there is disagreement on how to do so on a specific topic +* Whether to add or remove (see further below) a maintainer + +Generally, maintainers are only removed due to non-participation or actions +unhealthy to the project. Removal due to non-participation is not a punishment, +simply a recognition that maintainership is for active participants only. + +We hope that removal due to unhealthy actions will never be necessary, but would +include protection for cases of: + +* Disruptive behavior in public channels related to pantry +* Impairing the codebase through bad commits/merges + +Like committers, maintainers are broadly encouraged to make autonomous +decisions. Each maintainer is empowered to make a unilateral decision. However, +maintainers should favor getting consensus first if: + +* They are uncertain what is the best course of action +* They anticipate that other maintainers or users of pantry will disagree on the + decision + +## Bug Reports + +Please [open an issue](https://github.com/commercialhaskell/pantry/issues/new) +and use the provided template to include all necessary details. + +The more detailed your report, the faster it can be resolved and will ensure it +is resolved in the right way. Once your bug has been resolved, the responsible +person will tag the issue as _Needs confirmation_ and assign the issue back to +you. Once you have tested and confirmed that the issue is resolved, close the +issue. If you are not a member of the project, you will be asked for +confirmation and we will close it. + +## Error messages + +To support the Haskell Foundation's +[Haskell Error Index](https://errors.haskell.org/) initiative, all pantry +error messages generated by pantry itself should have a unique initial line: + +~~~text +Error: [S-nnn] +~~~ + +where `nnn` is a three-digit number in the range 100 to 999. + +If you create a new pantry error, select a number using a random number +generator (see, for example, [RANDOM.ORG](https://www.random.org/)) and check +that number is not already in use in pantry's code. If it is, pick another until +the number is unique. + +All exceptions generated by pantry itself are implemented using data +constructors of closed sum types. Typically, there is one such type for each +module that exports functions that throw exceptions. + +## Code + +If you would like to contribute code to fix a bug, add a new feature, or +otherwise improve pantry, pull requests are most welcome. It's a good idea to +[submit an issue](https://github.com/commercialhaskell/pantry/issues/new) to +discuss the change before plowing into writing code. + +Please include a +[ChangeLog](https://github.com/commercialhaskell/pantry/blob/master/ChangeLog.md) +entry with your pull request. + +## Code Quality + +The pantry project uses [yamllint](https://github.com/adrienverge/yamllint) as a +YAML file quality tool and [HLint](https://github.com/ndmitchell/hlint) as a +code quality tool. + +### Linting of YAML files + +The yamllint configuration extends the tools default and is set out in +`.yamllint.yaml`. In particular, indentation is set at 2 spaces and `- ` in +sequences is treated as part of the indentation. + +### Linting of Haskell source code + +The HLint configurations is set out in `.hlint.yaml`. + +pantry contributors need not follow dogmatically the suggested HLint hints but +are encouraged to debate their usefulness. If you find a HLint hint is not +useful and detracts from readability of code, consider marking it in the +[configuration file](https://github.com/commercialhaskell/pantry/blob/master/.hlint.yaml) +to be ignored. Please refer to the +[HLint manual](https://github.com/ndmitchell/hlint#readme) +for configuration syntax. + +We are optimizing for code clarity, not code concision or what HLint thinks. + +You can install HLint with Stack. You might want to install it in the global +project in case you run into dependency conflicts. HLint can report hints in +your favourite text editor. Refer to the HLint repository for more details. + +To install, command: + +~~~text +stack install hlint +~~~ + +## Code Style + +A single code style is not applied consistently to pantry's code and pantry is +not Procrustean about matters of style. Rules of thumb, however, are: + +* keep pull requests that simply reformat code separate from those that make + other changes to code; and +* when making changes to code other than reformatting, follow the existing style + of the function(s) or module(s) in question. + +That said, the following may help: + +* pantry's code generally avoids the use of C preprocessor (CPP) directives. + Windows and non-Windows code is separated in separate source code directories + and distinguished in pantry's Cabal file. Multi-line strings are generally + formatted on the assumption that GHC's `CPP` language pragma is not being + used. +* Language pragmas usually start with `NoImplictPrelude`, where applicable, and + then all others are listed alphabetically. The closing `#-}` are aligned, for + purely aesthetic reasons. +* pantry is compiled with GHC's `-Wall` enabled, which includes `-Wtabs` (no + tabs in source code). Most modules are based on two spaces (with one space for + a `where`) for indentation but older and larger modules are still based on + four spaces. +* pantry's code and documentation tends to be based on lines of no more than 80 + characters or, if longer, no longer than necessary. +* pantry uses export lists. +* pantry's imports are listed alphabetically. The module names are left aligned, + with space left for `qualified` where it is absent. +* pantry's code is sufficiently stable that explict import lists can sensibly be + used. Not all modules have comprehensive explicit import lists. +* Short explicit import lists follow the module name. Longer lists start on the + line below the module name. Spaces are used to separate listed items from + their enclosing parentheses. +* In function type signatures, the `::` is kept on the same line as the + function's name. This format is Haskell syntax highlighter-friendly. +* If `where` is used, the declarations follow on a separate line. + +## Continuous integration (CI) + +We use [GitHub Actions](https://docs.github.com/en/actions) to do CI on pantry. +The configuration of the workflows is in the YAML files in `.github/workflows`. +The current active workflows are: + +### Linting - `lint.yml` + +This workflow will run if: + +* there is a pull request +* commits are pushed to this branch: `master` + +The workflow has one job (`style`). It runs on `ubuntu` only and applies +yamllint and Hlint. + +### Stan tool - `stan.yml` + +[Stan](https://hackage.haskell.org/package/stan) is a Haskell static analysis +tool. As of `stan-0.1.0.1`, it supports GHC >= 9.6.3. The tool is configured by +the contents of the `.stan.toml` file. + +This workflow will run if: + +* there is a pull request +* requested + +## Haskell Language Server + +You may be using [Visual Studio Code](https://code.visualstudio.com/) (VS Code) +with its +[Haskell extension](https://marketplace.visualstudio.com/items?itemName=haskell.haskell), +which is powered by the +[Haskell Language Server](https://github.com/haskell/haskell-language-server) +(HLS). + +pantry can be built with Stack (which is recommended) or with Cabal (the tool). + +=== "Stack" + + If you use Stack to build Stack, command `stack ghci` in the root directory + of the pantry project should work as expected, if you have first commanded + `stack build` once. + + `ghc` should be on the PATH if you run VS Code itself in the Stack + environment: + ~~~text + stack exec -- code . + ~~~ + + The following [cradle (`hie.yaml`)](https://github.com/haskell/hie-bios) + should suffice to configure Haskell Language Server (HLS) explicitly for + each of the buildable components in pantry's Cabal file: + ~~~yaml + cradle: + stack: + - path: "./src" + component: "pantry:lib" + - path: "./int" + component: "pantry:lib" + - path: "./app" + component: "pantry:exe:test-pretty-exceptions" + - path: "./test" + component: "pantry:test:spec" + ~~~ + +=== "Cabal (the tool)" + + If you use Cabal (the tool) to build Stack, command `cabal repl` in the root + directory of the Stack project should work as expected, if you have GHC and + (on Windows) MSYS2 on the PATH. + + `ghc` and (on Windows) MSYS2 should be on the PATH if you run commands + (including `cabal`) in the Stack environment: + ~~~text + stack exec --no-ghc-package-path -- cabal repl + ~~~ + + or + ~~~text + stack exec --no-ghc-package-path -- code . + ~~~ + + Use of GHC's environment variable `GHC_PACKAGE_PATH` is not compatible with + Cabal (the tool). That is why the `--no-ghc-package-path` flag must be + specified with `stack exec` when relying on Cabal (the tool). + + The following [cradle (`hie.yaml`)](https://github.com/haskell/hie-bios) + should suffice to configure Haskell Language Server (HLS) explicitly for + each of the buildable components in pantry's Cabal file: + ~~~yaml + cradle: + cabal: + - path: "./src" + component: "lib:pantry" + - path: "./int" + component: "lib:pantry" + - path: "./app" + component: "exe:test-pretty-exceptions" + - path: "./test" + component: "test:spec" + ~~~ + +A cradle is not committed to pantry's repository because it imposes a choice of +build tool. + +## Slack channel + +If you're making deep changes and real-time communication with the pantry team +would be helpful, we have a `#stack-collaborators` Slack channel in the +Haskell Foundation workspace. To join the workspace, follow this +[link](https://haskell-foundation.slack.com/join/shared_invite/zt-z45o9x38-8L55P27r12YO0YeEufcO2w#/shared-invite/email). + +## Matrix room + +There is also a +[Stack and Stackage room](https://matrix.to/#/#haskell-stack:matrix.org) +at address `#haskell-stack:matrix.org` on [Matrix](https://matrix.org/). diff --git a/package.yaml b/package.yaml index 20ae7649..8a964646 100644 --- a/package.yaml +++ b/package.yaml @@ -10,6 +10,7 @@ license: BSD3 github: commercialhaskell/pantry extra-source-files: +- CONTRIBUTING.md - README.md - ChangeLog.md - attic/hpack-0.1.2.3.tar.gz diff --git a/pantry.cabal b/pantry.cabal index 1f8cc7b7..215b89b2 100644 --- a/pantry.cabal +++ b/pantry.cabal @@ -18,6 +18,7 @@ license: BSD3 license-file: LICENSE build-type: Simple extra-source-files: + CONTRIBUTING.md README.md ChangeLog.md attic/hpack-0.1.2.3.tar.gz