From a2af062ed6b0237e50257c2690949b169365a1b9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jonatan=20M=C3=A4nnchen?= Date: Mon, 24 Feb 2025 16:13:57 +0100 Subject: [PATCH] Split README from CONTRIBUTING --- .ort.yml | 2 +- CONTRIBUTING.md | 186 ++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 184 ++--------------------------------------------- 3 files changed, 193 insertions(+), 179 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/.ort.yml b/.ort.yml index e3e3362f547..ca2e588fa5f 100644 --- a/.ort.yml +++ b/.ort.yml @@ -109,7 +109,7 @@ curations: comment: "Ignored by ScanCode" detected_license: "NONE" concluded_license: "Apache-2.0" - - path: "README.md" + - path: "CONTRIBUTING.md" reason: "INCORRECT" comment: "Wrongly identified TSL license" detected_license: "Apache-2.0 OR NOASSERTION OR LicenseRef-scancode-tsl-2020" diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000000..2e6f0e6adb9 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,186 @@ + + +# Contributing to Elixir + +We invite contributions to Elixir. To contribute, there are a few +things you need to know about the code. First, Elixir code is divided +by each application inside the `lib` folder: + + * `elixir` - Elixir's kernel and standard library + + * `eex` - EEx is the template engine that allows you to embed Elixir + + * `ex_unit` - ExUnit is a simple test framework that ships with Elixir + + * `iex` - IEx stands for Interactive Elixir: Elixir's interactive shell + + * `logger` - Logger is the built-in logger + + * `mix` - Mix is Elixir's build tool + +You can run all tests in the root directory with `make test`. You can +also run tests for a specific framework with `make test_#{APPLICATION}`, for example, +`make test_ex_unit`. If you just changed something in Elixir's standard +library, you can run only that portion through `make test_stdlib`. + +If you are only changing one file, you can choose to compile and run tests +for that specific file for faster development cycles. For example, if you +are changing the String module, you can compile it and run its tests as: + +```sh +bin/elixirc lib/elixir/lib/string.ex -o lib/elixir/ebin +bin/elixir lib/elixir/test/elixir/string_test.exs +``` + +Some test files need their `test_helper.exs` to be explicitly required +before, such as: + +```sh +bin/elixir -r lib/logger/test/test_helper.exs lib/logger/test/logger_test.exs +``` + +You can also use the `LINE` env var to run a single test: + +```sh +LINE=123 bin/elixir lib/elixir/test/elixir/string_test.exs +```` + +To recompile all (including Erlang modules): + +```sh +make compile +``` + +After your changes are done, please remember to run `make format` to guarantee +all files are properly formatted, then run the full suite with +`make test`. + +If your contribution fails during the bootstrapping of the language, +you can rebuild the language from scratch with: + +```sh +make clean_elixir compile +``` + +Similarly, if you can not get Elixir to compile or the tests to pass after +updating an existing checkout, run `make clean compile`. You can check +[the official build status](https://github.com/elixir-lang/elixir/actions/workflows/ci.yml). +More tasks can be found by reading the [Makefile](Makefile). + +With tests running and passing, you are ready to contribute to Elixir and +[send a pull request](https://help.github.com/articles/using-pull-requests/). +We have saved some excellent pull requests we have received in the past in +case you are looking for some examples: + + * [Implement Enum.member? - Pull request](https://github.com/elixir-lang/elixir/pull/992) + * [Add String.valid? - Pull request](https://github.com/elixir-lang/elixir/pull/1058) + * [Implement capture_io for ExUnit - Pull request](https://github.com/elixir-lang/elixir/pull/1059) + +## Reviewing changes + +Once a pull request is sent, the Elixir team will review your changes. +We outline our process below to clarify the roles of everyone involved. + +All pull requests must be approved by two committers before being merged into +the repository. If changes are necessary, the team will leave appropriate +comments requesting changes to the code. Unfortunately, we cannot guarantee a +pull request will be merged, even when modifications are requested, as the Elixir +team will re-evaluate the contribution as it changes. + +Committers may also push style changes directly to your branch. If you would +rather manage all changes yourself, you can disable the "Allow edits from maintainers" +feature when submitting your pull request. + +The Elixir team may optionally assign someone to review a pull request. +If someone is assigned, they must explicitly approve the code before +another team member can merge it. + +When the review finishes, your pull request will be squashed and merged +into the repository. If you have carefully organized your commits and +believe they should be merged without squashing, please mention it in +a comment. + +## Licensing and Compliance Requirements + +Please review our [Open Source Policy](OPEN_SOURCE_POLICY.md) for complete +guidelines on licensing and compliance. Below is a summary of the key points +affecting **all external contributors**: + +- Accepted Licenses: Any code contributed must be licensed under the + `Apache-2.0` license. +- SPDX License Headers: With the exception of approved test fixture files, + all new or modified files in a pull request must include correct SPDX + headers. If you are creating a new file under the `Apache-2.0` license, for + instance, please use: + + ```elixir + # SPDX-License-Identifier: Apache-2.0 + # SPDX-FileCopyrightText: 2021 The Elixir Team + ``` + +- No Executable Binaries: Contributions must **not** include any executable + binary files. If you require an exception (for example, certain test artifacts), + please see the policy on how to request approval and document exceptions. +- Preserving Copyright and License Info: If you copy code from elsewhere, + ensure that **all original copyright and license notices remain intact**. If + they are missing or incomplete, you must add them. +- Failure to Comply: Pull requests that do not meet these licensing and + compliance standards will be rejected or require modifications before merging. +- Developer Certificate of Origin: All contributions are subject to the + Developer Certificate of Origin. + + ``` + By making a contribution to this project, I certify that: + + (a) The contribution was created in whole or in part by me and I + have the right to submit it under the open source license + indicated in the file; or + + (b) The contribution is based upon previous work that, to the + best of my knowledge, is covered under an appropriate open + source license and I have the right under that license to + submit that work with modifications, whether created in whole + or in part by me, under the same open source license (unless + I am permitted to submit under a different license), as + Indicated in the file; or + + (c) The contribution was provided directly to me by some other + person who certified (a), (b) or (c) and I have not modified + it. + + (d) I understand and agree that this project and the contribution + are public and that a record of the contribution (including + all personal information I submit with it, including my + sign-off) is maintained indefinitely and may be redistributed + consistent with this project or the open source license(s) + involved. + ``` + + See http://developercertificate.org/ for a copy of the Developer Certificate + of Origin license. + +## Building documentation + +Building the documentation requires that [ExDoc](https://github.com/elixir-lang/ex_doc) +is installed and built alongside Elixir: + +```sh +# After cloning and compiling Elixir, in its parent directory: +git clone https://github.com/elixir-lang/ex_doc.git +cd ex_doc && ../elixir/bin/elixir ../elixir/bin/mix do deps.get + compile +``` + +Now go back to Elixir's root directory and run: + +```sh +make docs # to generate HTML pages +make docs DOCS_FORMAT=epub # to generate EPUB documents +``` + +This will produce documentation sets for `elixir`, `eex`, `ex_unit`, `iex`, `logger`, +and `mix` under the `doc` directory. If you are planning to contribute documentation, +[please check our best practices for writing documentation](https://hexdocs.pm/elixir/writing-documentation.html). diff --git a/README.md b/README.md index 618bba2139f..f200cb113a0 100644 --- a/README.md +++ b/README.md @@ -117,184 +117,12 @@ variable `ERL_COMPILER_OPTIONS=deterministic`. ## Contributing -We invite contributions to Elixir. To contribute, there are a few -things you need to know about the code. First, Elixir code is divided -by each application inside the `lib` folder: - - * `elixir` - Elixir's kernel and standard library - - * `eex` - EEx is the template engine that allows you to embed Elixir - - * `ex_unit` - ExUnit is a simple test framework that ships with Elixir - - * `iex` - IEx stands for Interactive Elixir: Elixir's interactive shell - - * `logger` - Logger is the built-in logger - - * `mix` - Mix is Elixir's build tool - -You can run all tests in the root directory with `make test`. You can -also run tests for a specific framework with `make test_#{APPLICATION}`, for example, -`make test_ex_unit`. If you just changed something in Elixir's standard -library, you can run only that portion through `make test_stdlib`. - -If you are only changing one file, you can choose to compile and run tests -for that specific file for faster development cycles. For example, if you -are changing the String module, you can compile it and run its tests as: - -```sh -bin/elixirc lib/elixir/lib/string.ex -o lib/elixir/ebin -bin/elixir lib/elixir/test/elixir/string_test.exs -``` - -Some test files need their `test_helper.exs` to be explicitly required -before, such as: - -```sh -bin/elixir -r lib/logger/test/test_helper.exs lib/logger/test/logger_test.exs -``` - -You can also use the `LINE` env var to run a single test: - -```sh -LINE=123 bin/elixir lib/elixir/test/elixir/string_test.exs -```` - -To recompile all (including Erlang modules): - -```sh -make compile -``` - -After your changes are done, please remember to run `make format` to guarantee -all files are properly formatted, then run the full suite with -`make test`. - -If your contribution fails during the bootstrapping of the language, -you can rebuild the language from scratch with: - -```sh -make clean_elixir compile -``` - -Similarly, if you can not get Elixir to compile or the tests to pass after -updating an existing checkout, run `make clean compile`. You can check -[the official build status](https://github.com/elixir-lang/elixir/actions/workflows/ci.yml). -More tasks can be found by reading the [Makefile](Makefile). - -With tests running and passing, you are ready to contribute to Elixir and -[send a pull request](https://help.github.com/articles/using-pull-requests/). -We have saved some excellent pull requests we have received in the past in -case you are looking for some examples: - - * [Implement Enum.member? - Pull request](https://github.com/elixir-lang/elixir/pull/992) - * [Add String.valid? - Pull request](https://github.com/elixir-lang/elixir/pull/1058) - * [Implement capture_io for ExUnit - Pull request](https://github.com/elixir-lang/elixir/pull/1059) - -### Reviewing changes - -Once a pull request is sent, the Elixir team will review your changes. -We outline our process below to clarify the roles of everyone involved. - -All pull requests must be approved by two committers before being merged into -the repository. If changes are necessary, the team will leave appropriate -comments requesting changes to the code. Unfortunately, we cannot guarantee a -pull request will be merged, even when modifications are requested, as the Elixir -team will re-evaluate the contribution as it changes. - -Committers may also push style changes directly to your branch. If you would -rather manage all changes yourself, you can disable the "Allow edits from maintainers" -feature when submitting your pull request. - -The Elixir team may optionally assign someone to review a pull request. -If someone is assigned, they must explicitly approve the code before -another team member can merge it. - -When the review finishes, your pull request will be squashed and merged -into the repository. If you have carefully organized your commits and -believe they should be merged without squashing, please mention it in -a comment. - -### Licensing and Compliance Requirements - -Please review our [Open Source Policy][11] for complete guidelines on licensing -and compliance. Below is a summary of the key points affecting -**all external contributors**: - -- Accepted Licenses: Any code contributed must be licensed under the - `Apache-2.0` license. -- SPDX License Headers: With the exception of approved test fixture files, - all new or modified files in a pull request must include correct SPDX - headers. If you are creating a new file under the `Apache-2.0` license, for - instance, please use: - - ```elixir - # SPDX-License-Identifier: Apache-2.0 - # SPDX-FileCopyrightText: 2021 The Elixir Team - ``` - -- No Executable Binaries: Contributions must **not** include any executable - binary files. If you require an exception (for example, certain test artifacts), - please see the policy on how to request approval and document exceptions. -- Preserving Copyright and License Info: If you copy code from elsewhere, - ensure that **all original copyright and license notices remain intact**. If - they are missing or incomplete, you must add them. -- Failure to Comply: Pull requests that do not meet these licensing and - compliance standards will be rejected or require modifications before merging. -- Developer Certificate of Origin: All contributions are subject to the - Developer Certificate of Origin. - - ``` - By making a contribution to this project, I certify that: - - (a) The contribution was created in whole or in part by me and I - have the right to submit it under the open source license - indicated in the file; or - - (b) The contribution is based upon previous work that, to the - best of my knowledge, is covered under an appropriate open - source license and I have the right under that license to - submit that work with modifications, whether created in whole - or in part by me, under the same open source license (unless - I am permitted to submit under a different license), as - Indicated in the file; or - - (c) The contribution was provided directly to me by some other - person who certified (a), (b) or (c) and I have not modified - it. - - (d) I understand and agree that this project and the contribution - are public and that a record of the contribution (including - all personal information I submit with it, including my - sign-off) is maintained indefinitely and may be redistributed - consistent with this project or the open source license(s) - involved. - ``` - - See http://developercertificate.org/ for a copy of the Developer Certificate - of Origin license. - -## Building documentation - -Building the documentation requires that [ExDoc](https://github.com/elixir-lang/ex_doc) -is installed and built alongside Elixir: - -```sh -# After cloning and compiling Elixir, in its parent directory: -git clone https://github.com/elixir-lang/ex_doc.git -cd ex_doc && ../elixir/bin/elixir ../elixir/bin/mix do deps.get + compile -``` - -Now go back to Elixir's root directory and run: - -```sh -make docs # to generate HTML pages -make docs DOCS_FORMAT=epub # to generate EPUB documents -``` - -This will produce documentation sets for `elixir`, `eex`, `ex_unit`, `iex`, `logger`, -and `mix` under the `doc` directory. If you are planning to contribute documentation, -[please check our best practices for writing documentation](https://hexdocs.pm/elixir/writing-documentation.html). +Contributions to Elixir are always welcome! Before you get started, please check +out our [CONTRIBUTING.md](CONTRIBUTING.md) file. There you will find detailed +guidelines on how to set up your environment, run the test suite, format your +code, and submit pull requests. We also include information on our review +process, licensing requirements, and helpful tips to ensure a smooth +contribution experience. ## Development links