Skip to content

Commit 28afcec

Browse files
committed
Fix #5787 Add info about goals, governance and support
The new content is largely taken from https://www.snoyman.com/blog/2021/01/stack-governance/, with some minor stylistic changes and the addition of a little introductory welcome and context.
1 parent 5e37b4f commit 28afcec

File tree

1 file changed

+118
-13
lines changed

1 file changed

+118
-13
lines changed

CONTRIBUTING.md

Lines changed: 118 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,106 @@
11
# Contributors Guide
22

3+
Thank you for considering contributing to the maintenance or development of
4+
Stack, or otherwise supporting users of Stack! We hope that the following
5+
information will encourage and assist you. We start with some advice about
6+
Stack's goals and governance, and approach to supporting users.
7+
8+
## Stack's goals
9+
10+
Stack's current goals are:
11+
12+
* To provide easy to use tooling for Haskell development
13+
* To provide complete support for at least the following three development
14+
environments: Linux, macOS, and Windows
15+
* To address the needs of industrial users, open source maintainers, and other
16+
people
17+
* To focus on the 'curated package set' use case
18+
* To prioritize reproducible build plans
19+
20+
The goals above are not set in stone. However, any major changes to them
21+
should involve significant public discussion and a public vote by the Stack
22+
maintainer team.
23+
24+
## Stack's governance
25+
26+
People involved in maintaining or developing Stack with rights to make commits
27+
to the repository can be classified into two groups: 'committers' and
28+
'maintainers'.
29+
30+
### Stack's committers
31+
32+
We encourages a wide range of people to be granted rights to make commits to the
33+
repository.
34+
35+
People are encouraged to take initiative to make non-controversial
36+
changes, such as documentation improvements, bug fixes, performance
37+
improvements, and feature enhancements.
38+
39+
Maintainers should be included in discussions of controversial changes and
40+
tricky code changes.
41+
42+
Our general approach is **"it's easier to ask forgiveness than permission"**. If
43+
there is ever a bad change, it can always be rolled back.
44+
45+
### Stack's maintainers
46+
47+
Stack's maintainers are long-term contributors to the project. Michael Snoyman
48+
(@snoyberg) was the founder of Stack, and its initial maintainer - and he has
49+
added others. Michael's current interests and priorties mean that he is no
50+
longer actively involved in adding new features to Stack.
51+
52+
Maintainers are recognized for their contributions including:
53+
54+
* Direct code contribution
55+
* Review of pull requests
56+
* Interactions on the GitHub issue tracker
57+
* Documentation management
58+
* External support - for example, hosting or training
59+
60+
The maintainer team make certain decisions when that is necessary, specifically:
61+
62+
* How to proceed, if there is disagreement on how to do so on a specific topic
63+
* Whether to add or remove (see further below) a maintainer
64+
65+
Generally, maintainers are only removed due to non-participation or actions
66+
unhealthy to the project. Removal due to non-participation is not a punishment,
67+
simply a recognition that maintainership is for active participants only.
68+
69+
We hope that removal due to unhealthy actions will never be necessary, but would
70+
include protection for cases of:
71+
72+
* Disruptive behavior in public channels related to Stack
73+
* Impairing the codebase through bad commits/merges
74+
75+
Like committers, maintainers are broadly encouraged to make autonomous
76+
decisions. Each maintainer is empowered to make a unilateral decision. However,
77+
maintainers should favor getting consensus first if:
78+
79+
* They are uncertain what is the best course of action
80+
* They anticipate that other maintainers or users of Stack will disagree on the
81+
decision
82+
83+
## Stack's support
84+
85+
A large part of the general discussion around Stack is on support-related
86+
topics, and that is reflected in the current issue tracker content. Assistance
87+
in responding to such matters is greatly appreciated.
88+
89+
While support-related matters can be posted here as an 'issue', we encourage the
90+
use of other forums, in particular
91+
[Haskell's Discourse](https://discourse.haskell.org/). We also recommend
92+
Haskell's Discourse for general discussions about Stack's current or desired
93+
features. Stack is also discussed on Reddit's
94+
[Haskell community](https://www.reddit.com/r/haskell/).
95+
96+
We encourage use of those other forums because support-related discussions can
97+
clog up the issue tracker and make it more difficult to maintain the project.
98+
People needing support may also get a faster and fuller response on other
99+
forums.
100+
101+
Additions to the issue tracker are better suited to concrete feature proposals,
102+
bug reports, and other code base discussions (for example, refactorings).
103+
3104
## Bug Reports
4105

5106
Please [open an issue](https://github.com/commercialhaskell/stack/issues/new)
@@ -19,7 +120,8 @@ If you would like to help with documentation, please note that for most cases
19120
the Wiki has been deprecated in favor of markdown files placed in a new `/doc`
20121
subdirectory of the repository itself. Please submit a
21122
[pull request](https://help.github.com/articles/using-pull-requests/) with your
22-
changes/additions based off the [the stable branch](https://github.com/commercialhaskell/stack/tree/stable).
123+
changes/additions based off the
124+
[the stable branch](https://github.com/commercialhaskell/stack/tree/stable).
23125

24126
The documentation is rendered on [haskellstack.org](http://haskellstack.org) by
25127
readthedocs.org using Sphinx and CommonMark. Since links and formatting vary
@@ -61,16 +163,18 @@ quality tool.
61163

62164
Note that stack contributors need not dogmatically follow the suggested hints
63165
but are encouraged to debate their usefulness. If you find a hint is not useful
64-
and detracts from readability, consider marking it in the [configuration
65-
file](https://github.com/commercialhaskell/stack/blob/master/.hlint.yaml) to
66-
be ignored. Please refer to the [HLint manual](https://github.com/ndmitchell/hlint#readme)
166+
and detracts from readability, consider marking it in the
167+
[configuration file](https://github.com/commercialhaskell/stack/blob/master/.hlint.yaml)
168+
to be ignored. Please refer to the
169+
[HLint manual](https://github.com/ndmitchell/hlint#readme)
67170
for configuration syntax.
68171

69-
Quoting [@mgsloan](https://github.com/commercialhaskell/stack/pulls?utf8=%E2%9C%93&q=is%3Apr%20author%3Amgsloan):
172+
Quoting
173+
[@mgsloan](https://github.com/commercialhaskell/stack/pulls?utf8=%E2%9C%93&q=is%3Apr%20author%3Amgsloan):
70174

71175
> We are optimizing for code clarity, not code concision or what HLint thinks.
72176
73-
You can install HLint with stack. You might want to install it in the global
177+
You can install HLint with Stack. You might want to install it in the global
74178
project in case you run into dependency conflicts. HLint can report hints in
75179
your favourite text editor. Refer to the HLint repository for more details.
76180

@@ -89,10 +193,12 @@ $ ./etc/scripts/hlint.sh
89193
## Testing
90194

91195
The Stack code has both unit tests and integration tests. Integration tests can
92-
be found in the [test/integration](https://github.com/commercialhaskell/stack/tree/master/test/integration)
93-
folder and unit tests, in the [src/test](https://github.com/commercialhaskell/stack/tree/master/src/test)
94-
folder. Tests are written using the [Hspec](https://hspec.github.io/) framework. In
95-
order to run the full test suite, you can simply do:
196+
be found in the
197+
[test/integration](https://github.com/commercialhaskell/stack/tree/master/test/integration)
198+
folder and unit tests, in the
199+
[src/test](https://github.com/commercialhaskell/stack/tree/master/src/test)
200+
folder. Tests are written using the [Hspec](https://hspec.github.io/) framework.
201+
In order to run the full test suite, you can simply do:
96202

97203
```bash
98204
$ stack test
@@ -186,13 +292,12 @@ if you have the appropriate permissions. If you'd specifically like a
186292
branch or PR to run integration tests, add a comment in the PR and we
187293
can queue one up.
188294

189-
190295
### Skipping build
191296

192297
There are times (like a minor type fix) where you don't want the CI to
193298
run. For those cases, you can add `[skip ci]` or `[ci skip]` in your
194-
commit message to skip the builds. For more details, [refer
195-
here](https://github.com/Microsoft/azure-pipelines-agent/issues/858#issuecomment-475768046).
299+
commit message to skip the builds. For more details,
300+
[refer here](https://github.com/Microsoft/azure-pipelines-agent/issues/858#issuecomment-475768046).
196301

197302
## Slack channel
198303

0 commit comments

Comments
 (0)