/
CONTRIBUTING.md
216 lines (146 loc) · 8.85 KB
/
CONTRIBUTING.md
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
# Contributing to Dhall
## Am I in the right place?
This repository hosts language-independent features of the Dhall ecosystem:
* The [Dhall standard][standard] grammar and semantics
* [Dhall infrastructure][infrastructure]
* The [Prelude][prelude] of shared utility functions
Issues on this repository typically discuss language design and proposed
changes to the language that are not specific to an integration.
For example:
* [Natural / Integer syntax suggestion](https://github.com/dhall-lang/dhall-lang/issues/138)
* [Simplify if x then y else y to y](https://github.com/dhall-lang/dhall-lang/issues/108)
If you want to discuss a specific implementation of the Dhall language, then you
usually want to create an issue against the repository for that implementation.
The two most common repositories that we often redirect people to are:
* [`dhall-haskell`][dhall-haskell-issues] - Questions about the Haskell
integration, including the `dhall` executable provided by that package
For example:
* [Add `dhall --type` option](https://github.com/dhall-lang/dhall-haskell/issues/349)
* [Error message seems wrong](https://github.com/dhall-lang/dhall-haskell/issues/299)
* [`dhall-json`][dhall-json-issues] - Questions about the JSON integration,
including the `dhall-to-json`/`dhall-to-yaml` executables provided by that
package
For example:
* [Convert some association lists to homogeneous maps](https://github.com/dhall-lang/dhall-json/issues/27)
* [Valid Dhall not parsed by dhall-to-{json,yaml}](https://github.com/dhall-lang/dhall-json/issues/4)
## What is the correct way to ask a question?
You can either open issues [here][dhall-lang-issues] to ask a question
or use the [Dhall discourse][dhall-discourse]. You can also use
[Stack Overflow][stack-overflow]. I (@Gabriella439) subscribe by e-mail
to any Stack Overflow issues created with the tag `dhall`.
## Do I belong here?
Everybody is welcome! The Dhall community is not an "exclusive" or "elite"
club. People of all experience levels can join and begin contributing and
should feel comfortable and safe making mistakes.
People of all backgrounds belong here as long as they treat others with dignity
and respect and do not harass or belittle others.
## How do I change the language?
We make all changes to the language through pull requests to change the files
located in the [standard][standard] directory of this repository.
For simple changes, just begin by opening a [pull request][dhall-lang-pulls].
You don't need the change to be pre-approved before opening a pull request
since the discussion can happen directly on the pull request conversation.
For more complex changes, you might want the feature to be approved before
spending time on creating a matching pull request. You can open an
[issue][dhall-lang-issues] discussing your idea first and if the issue is
approved then you can proceed with a pull request.
You also don't have to understand how to translate your change to a formal
grammar or type-checking judgments in order to propose the change. Just propose
your idea and if your idea is approved then you can ask somebody (including
@Gabriella439) to formally standardize your change via a pull request for you.
The proposed change should also include some examples that show how it should be
used, eventual caveats, etc. These examples should end up in the [tests][dhall-lang-tests]
folder, so that all the implementations can verify that their approach is
conformant with the changes to the typechecker, import system, etc.
## How do changes get approved?
Changes only require approval if they change the [standard][standard] or
[Prelude][prelude]. If a pull request does not require approval, anybody with
the "commit bit" (i.e. write access to this repository) can merge it after a 24
hour waiting period. See below for more details about how to obtain the commit
bit.
Changes to the [standard][standard] and [Prelude][prelude] are voted on by
actively maintained implementations of the Dhall language. Votes are made
using the GitHub pull request review feature. Each implementation gets one
vote.
At the time of this writing the five actively supported implementations of Dhall
are:
* [`dhall-haskell` - Haskell bindings to Dhall](https://github.com/dhall-lang/dhall-haskell)
Led by @Gabriella439
* [`dhall-clj` - Clojure bindings to Dhall](https://github.com/f-f/dhall-clj)
Led by @f-f
* [`dhall-ruby` - ruby bindings to Dhall](https://git.sr.ht/~singpolyma/dhall-ruby)
Led by @singpolyma
* [`dhall-rust` - Rust bindings to Dhall](https://github.com/Nadrieril/dhall-rust)
Led by @Nadrieril
* [`dhall-golang` - Go bindings to Dhall](https://github.com/philandstuff/dhall-golang)
Led by @philandstuff
Each of those implementations get one vote cast by the lead contributor for each
implementation.
Implementations do not need to be useful or widely used to get a vote. If you
create a complete implementation as a side project that nobody uses and does not
integrate with anything, you still get to vote on changes to the standard.
Derived implementations do not count as a vote. For example, there are many
integrations that are powered by the Haskell integration (such as `dhall-to-nix`
and `dhall-to-json`), but they do not count as extra votes because they are not
a separate reimplementation of the standard.
The rules for merging a change are:
* You can merge a change 7 days after the original submission, even without
positive votes, so long as there are less than 50% negative votes
* You can merge a change 3 days after the original submission if you have
50% or more positive votes
* You must wait at least 24 hours since the last change before merging
Merging `master` into your branch does not count as a change for this
purpose
You also do not need to get new changes re-approved. Just wait 24 hours
The process is designed to be quick with a bias to action since if we make
mistakes we can always roll them back with a new proposal.
### Soundness of proposed changes
For non-trivial changes there should be a proof-of-concept implementation as a
sanity check. Moreover, changes to the type system need to have an informal proof
sketch of the following four soundness rules:
- Type-inference won't diverge
- If an expression type-checks, normalizing that expression won't diverge
- Normalizing an inferred type won't diverge
- Normalizing an expression doesn't change its type
- All inferred types are in β-normal form
## How do I update generated test files?
There are two sets of files you may need to update in the course of a change:
* If you add or modify any `.cbor` files in the test suite then you will need to
generate the matching `.diag` files
* If you add or update any Prelude utilities then you will need to lint them
and re-freeze downstream files
CI will remind you to update these files if you forget. Specifically, a test
failure will show up on your pull request displaying a diff between what CI
expected and what was found.
There are two ways you can apply the change:
* You can manually update the code to match the diff that CI displayed
* You can run a script that produces an output exactly matching what CI
expected
Since CI uses Nix the latter scripts require you to install Nix:
* [Nix](https://nixos.org/nix/)
You can also use the same cache that CI uses to avoid rebuilding the world by
following these instructions:
* [Use our shared caches](https://github.com/dhall-lang/dhall-haskell#nix)
Once you do that, you can run the following scripts:
* `./scripts/generate-test-files.sh` - This generates `.diag` files from `.cbor`
files
* `./scripts/lint-prelude.sh` - This freezes and lints the Prelude
## How do I get the "commit bit"?
Just ask! I (@Gabriella439) hand out the commit bit freely to anybody who
displays sustained interest in the project, sometimes even if they don't ask.
However, you shouldn't assume that you are undeserving if I haven't given you
the commit bit. I might just be busy or forgetful, so I appreciate a helpful
reminder. You can ask directly by e-mail (see my account profile) or by opening
an issue, whichever you prefer.
I hand out the commit bit freely because mistakes are easy to fix or roll back.
Learn by doing and get your hands dirty!
[infrastructure]: https://github.com/dhall-lang/dhall-lang/tree/master/nixops
[standard]: https://github.com/dhall-lang/dhall-lang/tree/master/standard
[prelude]: https://github.com/dhall-lang/dhall-lang/tree/master/Prelude
[dhall-discourse]: https://discourse.dhall-lang.org/
[dhall-haskell-issues]: https://github.com/dhall-lang/dhall-haskell/issues
[dhall-lang-issues]: https://github.com/dhall-lang/dhall-lang/issues
[dhall-lang-pulls]: https://github.com/dhall-lang/dhall-lang/pulls
[dhall-lang-tests]: https://github.com/dhall-lang/dhall-lang/tree/master/tests
[dhall-json-issues]: https://github.com/dhall-lang/dhall-json/issues
[stack-overflow]: https://stackoverflow.com/