|
1 | 1 | # How to contribute |
2 | 2 |
|
3 | | -We welcome contributions from external contributors, and this document describes |
4 | | -how to merge code changes. The procedure for contributing code is exactly the |
5 | | -same for the core development team and for external contributors: |
| 3 | +We welcome contributions from external contributors. |
| 4 | +This document describes the contribution process: from proposing a change to |
| 5 | +getting it merged into CMake Cookbook. |
| 6 | +The process for contributing is exactly the same for the core development team |
| 7 | +and for external contributors: |
6 | 8 |
|
7 | 9 | * Maintainers do not push directly to the repository. |
8 | 10 | * Maintainers do not review their own patches. |
9 | 11 | * Approval of one or more maintainers is sufficient for trivial patches. |
10 | | - Trivial patches are (typos and trivial bugfixes) |
11 | | -* For any patch that is not trivial, two maintainers need to sign off the patch. |
12 | | - |
13 | | -Finally, we do not require any formal copyright assignment or contributor |
14 | | -license agreement. Any contributions intentionally sent upstream are presumed |
15 | | -to be offered under terms of the [MIT license](https://tldrlegal.com/license/mit-license) |
| 12 | + Trivial patches are typos and trivial bugfixes |
| 13 | +* For any patch that is not trivial, two maintainers need to review and approve the patch. |
16 | 14 |
|
17 | 15 | ## Getting Started |
18 | 16 |
|
19 | | -* Make sure you have a [GitHub account](https://github.com/signup/free). |
20 | | -* [Fork](https://help.github.com/articles/fork-a-repo/) the |
21 | | - [dev-cafe/cmake-cookbook](https://github.com/dev-cafe/cmake-cookbook) repository on GitHub. |
22 | | -* On your local machine, |
23 | | - [clone](https://help.github.com/articles/cloning-a-repository/) your fork of |
24 | | - the repository. |
25 | | -* The Psi4 documentation has more detailed instructions for interacting with your fork which can be found |
| 17 | +* Make sure you have a [GitHub account]. |
| 18 | +* [Fork] the [dev-cafe/cmake-cookbook] repository on GitHub. |
| 19 | +* On your local machine, [clone] your fork of the CMake Cookbook repository. |
| 20 | +* The [Psi4](http://psicode.org/) documentation has more detailed instructions for interacting with your fork which can be found |
26 | 21 | [here](http://psicode.org/psi4manual/master/build_obtaining.html#faq-forkpsi4public). |
27 | 22 | and [here](http://psicode.org/psi4manual/master/build_obtaining.html#faq-githubworkflow). |
28 | 23 |
|
29 | 24 | ## Making Changes |
30 | 25 |
|
31 | | -* Add some really awesome code to your local fork. It's usually a [good |
32 | | - idea](http://blog.jasonmeridth.com/posts/do-not-issue-pull-requests-from-your-master-branch/) |
33 | | - to make changes on a |
34 | | - [branch](https://help.github.com/articles/creating-and-deleting-branches-within-your-repository/) |
35 | | - with the branch name relating to the feature you are going to add. |
| 26 | +* Add some really awesome code to your local fork. It's usually a [good idea] to |
| 27 | + make changes on a [branch] with the branch name relating to the feature you |
| 28 | + are going to add. A style guide is available in the [STYLE_GUIDE.md file]. |
| 29 | +* **Signoff** your patches by using the [`git commit -s` command] to commit them. |
| 30 | + This will show the CMake Cookbook team that you have read and agreed to the |
| 31 | + [Developer Certificate of Origin] (DCO). |
36 | 32 | * When you are ready for others to examine and comment on your new feature, |
37 | | - navigate to your fork on GitHub and open a [pull request](https://help.github.com/articles/using-pull-requests/) (PR). |
| 33 | + navigate to your fork of CMake Cookbook on GitHub and open a [pull request] (PR) |
| 34 | + __towards the `master` branch__. |
38 | 35 | Note that after you launch a PR from one of your fork's branches, all |
39 | 36 | subsequent commits to that branch will be added to the open pull request |
40 | | - automatically. Each commit added to the PR will be validated for mergeability, |
41 | | - compilation and test suite compliance; the results of these tests will be |
42 | | - visible on the PR page. |
43 | | -* If you're providing a new feature, you must add test cases and documentation. |
44 | | -* When the code is ready to go, make sure you run the full or relevant portion |
45 | | - of the test suite on your local machine to check that nothing is broken. |
46 | | -* When you're ready to be considered for merging, check the "Ready to go" |
47 | | - box on the PR page to let the maintainer team know that the changes are complete. |
| 37 | + automatically. |
| 38 | + Each commit added to the PR will be validated for mergeability, compilation |
| 39 | + and test suite compliance; the results of these tests will be visible on the |
| 40 | + PR page. |
| 41 | +* The title of your pull request should be marked with `[WIP]` if it’s a work |
| 42 | + in progress. Feel free to use as many labels as you think necessary! |
| 43 | +* Update the [`CHANGELOG.md`] file. We follow the conventions and recommendations detailed at |
| 44 | + [keepachangelog.com] |
| 45 | +* When the code is ready to go, make sure you run the full test suite on your |
| 46 | + local machine to check that nothing is broken. Read [here for further details on testing] |
| 47 | +* When you're ready to be considered for merging, check the "Ready to go" box |
| 48 | + on the PR page to let the CMake Cookbook team know that the changes are complete. |
48 | 49 | The code will not be merged until this box is checked, the continuous |
49 | | - integration (Travis for Linux and Mac, AppVeyor for Windows) returns checkmarks, |
50 | | - and multiple core developers give "Approved" reviews. |
51 | | - |
52 | | -### Conventions |
53 | | - |
54 | | -- Folders for recipes are named `chapter-N/recipe-M`, where `N` is the chapter number and `M` is a number, _i.e._ |
55 | | - `01`, `02`, etc. In each chapter we restart the recipe counter. |
56 | | -- Each recipe can have more than one example subfolder. These subfolders are |
57 | | - named `*example*`. Any code must reside in these subfolders. |
58 | | - |
59 | | - |
60 | | -### Updating the table of contents and generate README files |
61 | | - |
62 | | -The README files that form the table of contents (main README.md, chapter READMEs and recipe READMEs |
63 | | -are generated from title.txt and abstract.md files. |
64 | | - |
65 | | -This means that you should not modify README.md files but rather only edit title.txt and abstract.md files. |
66 | | - |
67 | | -To update the README files, run `python contributing/generate-readmes.py` - this file updates READMEs in place. |
68 | | - |
69 | | - |
70 | | -### Coding style |
71 | | - |
72 | | -#### Indentation |
73 | | - |
74 | | -We use 2 spaces instead of 4 spaces to reduce the printed page width. |
75 | | -No tabs. |
76 | | - |
77 | | - |
78 | | -#### Case of commands |
79 | | - |
80 | | -We use lowercase for commands, i.e.: |
81 | | -```cmake |
82 | | -cmake_minimum_required(VERSION 3.5 FATAL_ERROR) |
83 | | -``` |
84 | | -and not: |
85 | | -```cmake |
86 | | -CMAKE_MINIMUM_REQUIRED(VERSION 3.5 FATAL_ERROR) |
87 | | -``` |
88 | | - |
89 | | - |
90 | | -#### Line continuation |
91 | | - |
92 | | -It is OK to put commands on one line if it improves readability, e.g.: |
93 | | -```cmake |
94 | | -list(APPEND CXX_BASIC_FLAGS "-g3" "-O1") |
95 | | -``` |
96 | | - |
97 | | -For line continuation we use the following style: |
98 | | -```cmake |
99 | | -target_compile_options(asan-example |
100 | | - PUBLIC |
101 | | - ${CXX_BASIC_FLAGS} |
102 | | - ${_asan_flags} |
103 | | - ) |
104 | | -
|
105 | | -set(_whathaveyou |
106 | | - item1 |
107 | | - item2 |
108 | | - item3 |
109 | | - ) |
110 | | -``` |
111 | | - |
112 | | - |
113 | | -#### Variable names |
| 50 | + integration services return passing checkmarks, and maintainers give "Approved" reviews. |
114 | 51 |
|
115 | | -Start an internal variable (i.e. one that is not exposed to the user) with an |
116 | | -underscore: |
117 | | -```cmake |
118 | | -set(PUBLIC_VARIABLE "this one is exposed") |
| 52 | +## Licensing |
119 | 53 |
|
120 | | -set(_temp "this one is internal") |
121 | | -``` |
| 54 | +* We do not require any formal copyright assignment or contributor license agreement. |
| 55 | +* **Any contributions intentionally sent upstream are presumed to be offered under the terms of the OSI-approved [MIT License].** |
| 56 | +* You should read the [DCO] and certify that you agree to it by **signing off** your patch using the [`git commit -s` command]. |
| 57 | + Note that signing off and GPG-signing a commit are not the same thing and **we do not require** [GPG-signing] your commits. |
| 58 | + We use a [DCO bot] to ensure that submitted patches are signed off. The bot |
| 59 | + will block merging and suggest actions to resolve the block. |
122 | 60 |
|
123 | 61 | # Additional Resources |
124 | 62 |
|
125 | 63 | * [General GitHub documentation](https://help.github.com/) |
126 | 64 | * [PR best practices](http://codeinthehole.com/writing/pull-requests-and-other-good-practices-for-teams-using-github/) |
127 | 65 | * [A guide to contributing to software packages](http://www.contribution-guide.org) |
128 | 66 | * [Thinkful PR example](http://www.thinkful.com/learn/github-pull-request-tutorial/#Time-to-Submit-Your-First-PR) |
| 67 | +* [Developer Certificate of Origin versus Contributor License Agreements](https://julien.ponge.org/blog/developer-certificate-of-origin-versus-contributor-license-agreements/) |
| 68 | + |
| 69 | + |
| 70 | +[GitHub account]: https://github.com/signup/free |
| 71 | +[Fork]: https://help.github.com/articles/fork-a-repo/ |
| 72 | +[dev-cafe/cmake-cookbook]: https://github.com/dev-cafe/cmake-cookbook |
| 73 | +[clone]: https://help.github.com/articles/cloning-a-repository/ |
| 74 | +[good idea]: http://blog.jasonmeridth.com/posts/do-not-issue-pull-requests-from-your-master-branch/ |
| 75 | +[branch]: https://help.github.com/articles/creating-and-deleting-branches-within-your-repository/ |
| 76 | +[STYLE_GUIDE.md file]: ../STYLE_GUIDE.md |
| 77 | +[`git commit -s` command]: https://git-scm.com/docs/git-commit#git-commit---signoff |
| 78 | +[Developer Certificate of Origin]: https://developercertificate.org/ |
| 79 | +[pull request]: https://help.github.com/articles/using-pull-requests/ |
| 80 | +[`CHANGELOG.md`]: ../CHANGELOG.md |
| 81 | +[keepachangelog.com]: https://keepachangelog.com/en/1.0.0/ |
| 82 | +[here for further details on testing]: ../testing/README.md |
| 83 | +[MIT License]: ../LICENSE |
| 84 | +[DCO]: https://developercertificate.org/ |
| 85 | +[GPG-signing]: https://git-scm.com/docs/git-commit#git-commit---gpg-signltkeyidgt |
| 86 | +[DCO bot]: https://github.com/probot/dco |
0 commit comments