Skip to content

Commit 491e4df

Browse files
maennchenmaennchen
authored
Split README from CONTRIBUTING (elixir-lang#14297)
1 parent a58382f commit 491e4df

File tree

3 files changed

+193
-179
lines changed

3 files changed

+193
-179
lines changed

‎.ort.yml

+1-1
Original file line numberDiff line numberDiff line change
@@ -109,7 +109,7 @@ curations:
109109
comment: "Ignored by ScanCode"
110110
detected_license: "NONE"
111111
concluded_license: "Apache-2.0"
112-
- path: "README.md"
112+
- path: "CONTRIBUTING.md"
113113
reason: "INCORRECT"
114114
comment: "Wrongly identified TSL license"
115115
detected_license: "Apache-2.0 OR NOASSERTION OR LicenseRef-scancode-tsl-2020"

‎CONTRIBUTING.md

+186
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,186 @@
1+
<!--
2+
SPDX-License-Identifier: Apache-2.0
3+
SPDX-FileCopyrightText: 2021 The Elixir Team
4+
SPDX-FileCopyrightText: 2012 Plataformatec
5+
-->
6+
7+
# Contributing to Elixir
8+
9+
We invite contributions to Elixir. To contribute, there are a few
10+
things you need to know about the code. First, Elixir code is divided
11+
by each application inside the `lib` folder:
12+
13+
* `elixir` - Elixir's kernel and standard library
14+
15+
* `eex` - EEx is the template engine that allows you to embed Elixir
16+
17+
* `ex_unit` - ExUnit is a simple test framework that ships with Elixir
18+
19+
* `iex` - IEx stands for Interactive Elixir: Elixir's interactive shell
20+
21+
* `logger` - Logger is the built-in logger
22+
23+
* `mix` - Mix is Elixir's build tool
24+
25+
You can run all tests in the root directory with `make test`. You can
26+
also run tests for a specific framework with `make test_#{APPLICATION}`, for example,
27+
`make test_ex_unit`. If you just changed something in Elixir's standard
28+
library, you can run only that portion through `make test_stdlib`.
29+
30+
If you are only changing one file, you can choose to compile and run tests
31+
for that specific file for faster development cycles. For example, if you
32+
are changing the String module, you can compile it and run its tests as:
33+
34+
```sh
35+
bin/elixirc lib/elixir/lib/string.ex -o lib/elixir/ebin
36+
bin/elixir lib/elixir/test/elixir/string_test.exs
37+
```
38+
39+
Some test files need their `test_helper.exs` to be explicitly required
40+
before, such as:
41+
42+
```sh
43+
bin/elixir -r lib/logger/test/test_helper.exs lib/logger/test/logger_test.exs
44+
```
45+
46+
You can also use the `LINE` env var to run a single test:
47+
48+
```sh
49+
LINE=123 bin/elixir lib/elixir/test/elixir/string_test.exs
50+
````
51+
52+
To recompile all (including Erlang modules):
53+
54+
```sh
55+
make compile
56+
```
57+
58+
After your changes are done, please remember to run `make format` to guarantee
59+
all files are properly formatted, then run the full suite with
60+
`make test`.
61+
62+
If your contribution fails during the bootstrapping of the language,
63+
you can rebuild the language from scratch with:
64+
65+
```sh
66+
make clean_elixir compile
67+
```
68+
69+
Similarly, if you can not get Elixir to compile or the tests to pass after
70+
updating an existing checkout, run `make clean compile`. You can check
71+
[the official build status](https://github.com/elixir-lang/elixir/actions/workflows/ci.yml).
72+
More tasks can be found by reading the [Makefile](Makefile).
73+
74+
With tests running and passing, you are ready to contribute to Elixir and
75+
[send a pull request](https://help.github.com/articles/using-pull-requests/).
76+
We have saved some excellent pull requests we have received in the past in
77+
case you are looking for some examples:
78+
79+
* [Implement Enum.member? - Pull request](https://github.com/elixir-lang/elixir/pull/992)
80+
* [Add String.valid? - Pull request](https://github.com/elixir-lang/elixir/pull/1058)
81+
* [Implement capture_io for ExUnit - Pull request](https://github.com/elixir-lang/elixir/pull/1059)
82+
83+
## Reviewing changes
84+
85+
Once a pull request is sent, the Elixir team will review your changes.
86+
We outline our process below to clarify the roles of everyone involved.
87+
88+
All pull requests must be approved by two committers before being merged into
89+
the repository. If changes are necessary, the team will leave appropriate
90+
comments requesting changes to the code. Unfortunately, we cannot guarantee a
91+
pull request will be merged, even when modifications are requested, as the Elixir
92+
team will re-evaluate the contribution as it changes.
93+
94+
Committers may also push style changes directly to your branch. If you would
95+
rather manage all changes yourself, you can disable the "Allow edits from maintainers"
96+
feature when submitting your pull request.
97+
98+
The Elixir team may optionally assign someone to review a pull request.
99+
If someone is assigned, they must explicitly approve the code before
100+
another team member can merge it.
101+
102+
When the review finishes, your pull request will be squashed and merged
103+
into the repository. If you have carefully organized your commits and
104+
believe they should be merged without squashing, please mention it in
105+
a comment.
106+
107+
## Licensing and Compliance Requirements
108+
109+
Please review our [Open Source Policy](OPEN_SOURCE_POLICY.md) for complete
110+
guidelines on licensing and compliance. Below is a summary of the key points
111+
affecting **all external contributors**:
112+
113+
- Accepted Licenses: Any code contributed must be licensed under the
114+
`Apache-2.0` license.
115+
- SPDX License Headers: With the exception of approved test fixture files,
116+
all new or modified files in a pull request must include correct SPDX
117+
headers. If you are creating a new file under the `Apache-2.0` license, for
118+
instance, please use:
119+
120+
```elixir
121+
# SPDX-License-Identifier: Apache-2.0
122+
# SPDX-FileCopyrightText: 2021 The Elixir Team
123+
```
124+
125+
- No Executable Binaries: Contributions must **not** include any executable
126+
binary files. If you require an exception (for example, certain test artifacts),
127+
please see the policy on how to request approval and document exceptions.
128+
- Preserving Copyright and License Info: If you copy code from elsewhere,
129+
ensure that **all original copyright and license notices remain intact**. If
130+
they are missing or incomplete, you must add them.
131+
- Failure to Comply: Pull requests that do not meet these licensing and
132+
compliance standards will be rejected or require modifications before merging.
133+
- Developer Certificate of Origin: All contributions are subject to the
134+
Developer Certificate of Origin.
135+
136+
```
137+
By making a contribution to this project, I certify that:
138+
139+
(a) The contribution was created in whole or in part by me and I
140+
have the right to submit it under the open source license
141+
indicated in the file; or
142+
143+
(b) The contribution is based upon previous work that, to the
144+
best of my knowledge, is covered under an appropriate open
145+
source license and I have the right under that license to
146+
submit that work with modifications, whether created in whole
147+
or in part by me, under the same open source license (unless
148+
I am permitted to submit under a different license), as
149+
Indicated in the file; or
150+
151+
(c) The contribution was provided directly to me by some other
152+
person who certified (a), (b) or (c) and I have not modified
153+
it.
154+
155+
(d) I understand and agree that this project and the contribution
156+
are public and that a record of the contribution (including
157+
all personal information I submit with it, including my
158+
sign-off) is maintained indefinitely and may be redistributed
159+
consistent with this project or the open source license(s)
160+
involved.
161+
```
162+
163+
See http://developercertificate.org/ for a copy of the Developer Certificate
164+
of Origin license.
165+
166+
## Building documentation
167+
168+
Building the documentation requires that [ExDoc](https://github.com/elixir-lang/ex_doc)
169+
is installed and built alongside Elixir:
170+
171+
```sh
172+
# After cloning and compiling Elixir, in its parent directory:
173+
git clone https://github.com/elixir-lang/ex_doc.git
174+
cd ex_doc && ../elixir/bin/elixir ../elixir/bin/mix do deps.get + compile
175+
```
176+
177+
Now go back to Elixir's root directory and run:
178+
179+
```sh
180+
make docs # to generate HTML pages
181+
make docs DOCS_FORMAT=epub # to generate EPUB documents
182+
```
183+
184+
This will produce documentation sets for `elixir`, `eex`, `ex_unit`, `iex`, `logger`,
185+
and `mix` under the `doc` directory. If you are planning to contribute documentation,
186+
[please check our best practices for writing documentation](https://hexdocs.pm/elixir/writing-documentation.html).

‎README.md

+6-178
Original file line numberDiff line numberDiff line change
@@ -117,184 +117,12 @@ variable `ERL_COMPILER_OPTIONS=deterministic`.
117117

118118
## Contributing
119119

120-
We invite contributions to Elixir. To contribute, there are a few
121-
things you need to know about the code. First, Elixir code is divided
122-
by each application inside the `lib` folder:
123-
124-
* `elixir` - Elixir's kernel and standard library
125-
126-
* `eex` - EEx is the template engine that allows you to embed Elixir
127-
128-
* `ex_unit` - ExUnit is a simple test framework that ships with Elixir
129-
130-
* `iex` - IEx stands for Interactive Elixir: Elixir's interactive shell
131-
132-
* `logger` - Logger is the built-in logger
133-
134-
* `mix` - Mix is Elixir's build tool
135-
136-
You can run all tests in the root directory with `make test`. You can
137-
also run tests for a specific framework with `make test_#{APPLICATION}`, for example,
138-
`make test_ex_unit`. If you just changed something in Elixir's standard
139-
library, you can run only that portion through `make test_stdlib`.
140-
141-
If you are only changing one file, you can choose to compile and run tests
142-
for that specific file for faster development cycles. For example, if you
143-
are changing the String module, you can compile it and run its tests as:
144-
145-
```sh
146-
bin/elixirc lib/elixir/lib/string.ex -o lib/elixir/ebin
147-
bin/elixir lib/elixir/test/elixir/string_test.exs
148-
```
149-
150-
Some test files need their `test_helper.exs` to be explicitly required
151-
before, such as:
152-
153-
```sh
154-
bin/elixir -r lib/logger/test/test_helper.exs lib/logger/test/logger_test.exs
155-
```
156-
157-
You can also use the `LINE` env var to run a single test:
158-
159-
```sh
160-
LINE=123 bin/elixir lib/elixir/test/elixir/string_test.exs
161-
````
162-
163-
To recompile all (including Erlang modules):
164-
165-
```sh
166-
make compile
167-
```
168-
169-
After your changes are done, please remember to run `make format` to guarantee
170-
all files are properly formatted, then run the full suite with
171-
`make test`.
172-
173-
If your contribution fails during the bootstrapping of the language,
174-
you can rebuild the language from scratch with:
175-
176-
```sh
177-
make clean_elixir compile
178-
```
179-
180-
Similarly, if you can not get Elixir to compile or the tests to pass after
181-
updating an existing checkout, run `make clean compile`. You can check
182-
[the official build status](https://github.com/elixir-lang/elixir/actions/workflows/ci.yml).
183-
More tasks can be found by reading the [Makefile](Makefile).
184-
185-
With tests running and passing, you are ready to contribute to Elixir and
186-
[send a pull request](https://help.github.com/articles/using-pull-requests/).
187-
We have saved some excellent pull requests we have received in the past in
188-
case you are looking for some examples:
189-
190-
* [Implement Enum.member? - Pull request](https://github.com/elixir-lang/elixir/pull/992)
191-
* [Add String.valid? - Pull request](https://github.com/elixir-lang/elixir/pull/1058)
192-
* [Implement capture_io for ExUnit - Pull request](https://github.com/elixir-lang/elixir/pull/1059)
193-
194-
### Reviewing changes
195-
196-
Once a pull request is sent, the Elixir team will review your changes.
197-
We outline our process below to clarify the roles of everyone involved.
198-
199-
All pull requests must be approved by two committers before being merged into
200-
the repository. If changes are necessary, the team will leave appropriate
201-
comments requesting changes to the code. Unfortunately, we cannot guarantee a
202-
pull request will be merged, even when modifications are requested, as the Elixir
203-
team will re-evaluate the contribution as it changes.
204-
205-
Committers may also push style changes directly to your branch. If you would
206-
rather manage all changes yourself, you can disable the "Allow edits from maintainers"
207-
feature when submitting your pull request.
208-
209-
The Elixir team may optionally assign someone to review a pull request.
210-
If someone is assigned, they must explicitly approve the code before
211-
another team member can merge it.
212-
213-
When the review finishes, your pull request will be squashed and merged
214-
into the repository. If you have carefully organized your commits and
215-
believe they should be merged without squashing, please mention it in
216-
a comment.
217-
218-
### Licensing and Compliance Requirements
219-
220-
Please review our [Open Source Policy][11] for complete guidelines on licensing
221-
and compliance. Below is a summary of the key points affecting
222-
**all external contributors**:
223-
224-
- Accepted Licenses: Any code contributed must be licensed under the
225-
`Apache-2.0` license.
226-
- SPDX License Headers: With the exception of approved test fixture files,
227-
all new or modified files in a pull request must include correct SPDX
228-
headers. If you are creating a new file under the `Apache-2.0` license, for
229-
instance, please use:
230-
231-
```elixir
232-
# SPDX-License-Identifier: Apache-2.0
233-
# SPDX-FileCopyrightText: 2021 The Elixir Team
234-
```
235-
236-
- No Executable Binaries: Contributions must **not** include any executable
237-
binary files. If you require an exception (for example, certain test artifacts),
238-
please see the policy on how to request approval and document exceptions.
239-
- Preserving Copyright and License Info: If you copy code from elsewhere,
240-
ensure that **all original copyright and license notices remain intact**. If
241-
they are missing or incomplete, you must add them.
242-
- Failure to Comply: Pull requests that do not meet these licensing and
243-
compliance standards will be rejected or require modifications before merging.
244-
- Developer Certificate of Origin: All contributions are subject to the
245-
Developer Certificate of Origin.
246-
247-
```
248-
By making a contribution to this project, I certify that:
249-
250-
(a) The contribution was created in whole or in part by me and I
251-
have the right to submit it under the open source license
252-
indicated in the file; or
253-
254-
(b) The contribution is based upon previous work that, to the
255-
best of my knowledge, is covered under an appropriate open
256-
source license and I have the right under that license to
257-
submit that work with modifications, whether created in whole
258-
or in part by me, under the same open source license (unless
259-
I am permitted to submit under a different license), as
260-
Indicated in the file; or
261-
262-
(c) The contribution was provided directly to me by some other
263-
person who certified (a), (b) or (c) and I have not modified
264-
it.
265-
266-
(d) I understand and agree that this project and the contribution
267-
are public and that a record of the contribution (including
268-
all personal information I submit with it, including my
269-
sign-off) is maintained indefinitely and may be redistributed
270-
consistent with this project or the open source license(s)
271-
involved.
272-
```
273-
274-
See http://developercertificate.org/ for a copy of the Developer Certificate
275-
of Origin license.
276-
277-
## Building documentation
278-
279-
Building the documentation requires that [ExDoc](https://github.com/elixir-lang/ex_doc)
280-
is installed and built alongside Elixir:
281-
282-
```sh
283-
# After cloning and compiling Elixir, in its parent directory:
284-
git clone https://github.com/elixir-lang/ex_doc.git
285-
cd ex_doc && ../elixir/bin/elixir ../elixir/bin/mix do deps.get + compile
286-
```
287-
288-
Now go back to Elixir's root directory and run:
289-
290-
```sh
291-
make docs # to generate HTML pages
292-
make docs DOCS_FORMAT=epub # to generate EPUB documents
293-
```
294-
295-
This will produce documentation sets for `elixir`, `eex`, `ex_unit`, `iex`, `logger`,
296-
and `mix` under the `doc` directory. If you are planning to contribute documentation,
297-
[please check our best practices for writing documentation](https://hexdocs.pm/elixir/writing-documentation.html).
120+
Contributions to Elixir are always welcome! Before you get started, please check
121+
out our [CONTRIBUTING.md](CONTRIBUTING.md) file. There you will find detailed
122+
guidelines on how to set up your environment, run the test suite, format your
123+
code, and submit pull requests. We also include information on our review
124+
process, licensing requirements, and helpful tips to ensure a smooth
125+
contribution experience.
298126

299127
## Development links
300128

0 commit comments

Comments
 (0)