Merge pull request #502 from robertodr/contributing-md

Update CONTRIBUTING.md
dev-cafe · Sep 24, 2018 · ab06d91 · ab06d91
2 parents 387931a + 9810973
commit ab06d91
Show file tree

Hide file tree

Showing 4 changed files with 77 additions and 121 deletions.
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
@@ -1,128 +1,86 @@
 # How to contribute
 
-We welcome contributions from external contributors, and this document describes
-how to merge code changes. The procedure for contributing code is exactly the
-same for the core development team and for external contributors:
+We welcome contributions from external contributors.
+This document describes the contribution process: from proposing a change to
+getting it merged into CMake Cookbook.
+The process for contributing is exactly the same for the core development team
+and for external contributors:
 
 * Maintainers do not push directly to the repository.
 * Maintainers do not review their own patches.
 * Approval of one or more maintainers is sufficient for trivial patches.
-  Trivial patches are (typos and trivial bugfixes)
-* For any patch that is not trivial, two maintainers need to sign off the patch.
-
-Finally, we do not require any formal copyright assignment or contributor
-license agreement. Any contributions intentionally sent upstream are presumed
-to be offered under terms of the [MIT license](https://tldrlegal.com/license/mit-license)
+  Trivial patches are typos and trivial bugfixes
+* For any patch that is not trivial, two maintainers need to review and approve the patch.
 
 ## Getting Started
 
-* Make sure you have a [GitHub account](https://github.com/signup/free).
-* [Fork](https://help.github.com/articles/fork-a-repo/) the
-  [dev-cafe/cmake-cookbook](https://github.com/dev-cafe/cmake-cookbook) repository on GitHub.
-* On your local machine,
-  [clone](https://help.github.com/articles/cloning-a-repository/) your fork of
-  the repository.
-* The Psi4 documentation has more detailed instructions for interacting with your fork which can be found
+* Make sure you have a [GitHub account].
+* [Fork] the [dev-cafe/cmake-cookbook] repository on GitHub.
+* On your local machine, [clone] your fork of the CMake Cookbook repository.
+* The [Psi4](http://psicode.org/) documentation has more detailed instructions for interacting with your fork which can be found
   [here](http://psicode.org/psi4manual/master/build_obtaining.html#faq-forkpsi4public).
   and [here](http://psicode.org/psi4manual/master/build_obtaining.html#faq-githubworkflow).
 
 ## Making Changes
 
-* Add some really awesome code to your local fork.  It's usually a [good
-  idea](http://blog.jasonmeridth.com/posts/do-not-issue-pull-requests-from-your-master-branch/)
-  to make changes on a
-  [branch](https://help.github.com/articles/creating-and-deleting-branches-within-your-repository/)
-  with the branch name relating to the feature you are going to add.
+* Add some really awesome code to your local fork. It's usually a [good idea] to
+  make changes on a [branch] with the branch name relating to the feature you
+  are going to add. A style guide is available in the [STYLE_GUIDE.md file].
+* **Signoff** your patches by using the [`git commit -s` command] to commit them.
+  This will show the CMake Cookbook team that you have read and agreed to the
+  [Developer Certificate of Origin] (DCO).
 * When you are ready for others to examine and comment on your new feature,
-  navigate to your fork on GitHub and open a [pull request](https://help.github.com/articles/using-pull-requests/) (PR). 
+  navigate to your fork of CMake Cookbook on GitHub and open a [pull request] (PR)
+  __towards the `master` branch__.
   Note that after you launch a PR from one of your fork's branches, all
   subsequent commits to that branch will be added to the open pull request
-  automatically. Each commit added to the PR will be validated for mergeability,
-  compilation and test suite compliance; the results of these tests will be
-  visible on the PR page.
-* If you're providing a new feature, you must add test cases and documentation.
-* When the code is ready to go, make sure you run the full or relevant portion
-  of the test suite on your local machine to check that nothing is broken.
-* When you're ready to be considered for merging, check the "Ready to go"
-  box on the PR page to let the maintainer team know that the changes are complete.
+  automatically.
+  Each commit added to the PR will be validated for mergeability, compilation
+  and test suite compliance; the results of these tests will be visible on the
+  PR page.
+* The title of your pull request should be marked with `[WIP]` if it’s a work
+  in progress. Feel free to use as many labels as you think necessary!
+* Update the [`CHANGELOG.md`] file. We follow the conventions and recommendations detailed at
+  [keepachangelog.com]
+* When the code is ready to go, make sure you run the full test suite on your
+  local machine to check that nothing is broken. Read [here for further details on testing]
+* When you're ready to be considered for merging, check the "Ready to go" box
+  on the PR page to let the CMake Cookbook team know that the changes are complete.
   The code will not be merged until this box is checked, the continuous
-  integration (Travis for Linux and Mac, AppVeyor for Windows) returns checkmarks,
-  and multiple core developers give "Approved" reviews.
-
-### Conventions
-
-- Folders for recipes are named `chapter-N/recipe-M`, where `N` is the chapter number and `M` is a number, _i.e._
-  `01`, `02`, etc. In each chapter we restart the recipe counter.
-- Each recipe can have more than one example subfolder. These subfolders are
-  named `*example*`. Any code must reside in these subfolders.
-
-
-### Updating the table of contents and generate README files
-
-The README files that form the table of contents (main README.md, chapter READMEs and recipe READMEs
-are generated from title.txt and abstract.md files.
-
-This means that you should not modify README.md files but rather only edit title.txt and abstract.md files.
-
-To update the README files, run `python contributing/generate-readmes.py` - this file updates READMEs in place.
-
-
-### Coding style
-
-#### Indentation
-
-We use 2 spaces instead of 4 spaces to reduce the printed page width.
-No tabs.
-
-
-#### Case of commands
-
-We use lowercase for commands, i.e.:
-```cmake
-cmake_minimum_required(VERSION 3.5 FATAL_ERROR)
-```
-and not:
-```cmake
-CMAKE_MINIMUM_REQUIRED(VERSION 3.5 FATAL_ERROR)
-```
-
-
-#### Line continuation
-
-It is OK to put commands on one line if it improves readability, e.g.:
-```cmake
-list(APPEND CXX_BASIC_FLAGS "-g3" "-O1")
-```
-
-For line continuation we use the following style:
-```cmake
-target_compile_options(asan-example
-  PUBLIC
-    ${CXX_BASIC_FLAGS}
-    ${_asan_flags}
-  )
-
-set(_whathaveyou
-  item1
-  item2
-  item3
-  )
-```
-
-
-#### Variable names
+  integration services return passing checkmarks, and maintainers give "Approved" reviews.
 
-Start an internal variable (i.e. one that is not exposed to the user) with an
-underscore:
-```cmake
-set(PUBLIC_VARIABLE "this one is exposed")
+## Licensing
 
-set(_temp "this one is internal")
-```
+* We do not require any formal copyright assignment or contributor license agreement.
+* **Any contributions intentionally sent upstream are presumed to be offered under the terms of the OSI-approved [MIT License].**
+* You should read the [DCO] and certify that you agree to it by **signing off** your patch using the [`git commit -s` command].
+  Note that signing off and GPG-signing a commit are not the same thing and **we do not require** [GPG-signing] your commits.
+  We use a [DCO bot] to ensure that submitted patches are signed off. The bot
+  will block merging and suggest actions to resolve the block.
 
 # Additional Resources
 
 * [General GitHub documentation](https://help.github.com/)
 * [PR best practices](http://codeinthehole.com/writing/pull-requests-and-other-good-practices-for-teams-using-github/)
 * [A guide to contributing to software packages](http://www.contribution-guide.org)
 * [Thinkful PR example](http://www.thinkful.com/learn/github-pull-request-tutorial/#Time-to-Submit-Your-First-PR)
+* [Developer Certificate of Origin versus Contributor License Agreements](https://julien.ponge.org/blog/developer-certificate-of-origin-versus-contributor-license-agreements/)
+
+
+[GitHub account]: https://github.com/signup/free
+[Fork]: https://help.github.com/articles/fork-a-repo/
+[dev-cafe/cmake-cookbook]: https://github.com/dev-cafe/cmake-cookbook
+[clone]: https://help.github.com/articles/cloning-a-repository/
+[good idea]: http://blog.jasonmeridth.com/posts/do-not-issue-pull-requests-from-your-master-branch/
+[branch]: https://help.github.com/articles/creating-and-deleting-branches-within-your-repository/
+[STYLE_GUIDE.md file]: ../STYLE_GUIDE.md
+[`git commit -s` command]: https://git-scm.com/docs/git-commit#git-commit---signoff
+[Developer Certificate of Origin]: https://developercertificate.org/
+[pull request]: https://help.github.com/articles/using-pull-requests/
+[`CHANGELOG.md`]: ../CHANGELOG.md
+[keepachangelog.com]: https://keepachangelog.com/en/1.0.0/
+[here for further details on testing]: ../testing/README.md
+[MIT License]: ../LICENSE
+[DCO]: https://developercertificate.org/
+[GPG-signing]: https://git-scm.com/docs/git-commit#git-commit---gpg-signltkeyidgt
+[DCO bot]: https://github.com/probot/dco
diff --git a/README.md b/README.md
@@ -17,8 +17,8 @@ This repository collects sources for the recipes contained in the
 published by Packt and authored by [Radovan Bast](https://github.com/bast) and
 [Roberto Di Remigio](https://github.com/robertodr)
 
+- [Contributing](.github/CONTRIBUTING.md)
 - [Testing](testing/README.md)
-- [Contributing](contributing/README.md)
 
 
 ## Table of contents

diff --git a/contributing/README.md → STYLE_GUIDE.md b/contributing/README.md → STYLE_GUIDE.md
@@ -1,37 +1,35 @@
+# Style Guide
 
-
-## Contributing
-
-### Conventions
+## Conventions
 
 - Folders for recipes are named `chapter-N/recipe-M`, where `N` is the chapter number and `M` is a number, _i.e._
   `01`, `02`, etc. In each chapter we restart the recipe counter.
 - Each recipe can have more than one example subfolder. These subfolders are
   named `*example*`. Any code must reside in these subfolders.
 
 
-### Updating the table of contents and generate README files
+## Updating the table of contents and generate README files
 
-The README files that form the table of contents (main README.md, chapter READMEs and recipe READMEs
-are generated from title.txt and abstract.md files.
+The `README.md` files that form the table of contents (main `README.md`, chapter `README.md`s and recipe `README.md`s)
+are generated from `title.txt` and `abstract.md` files.
 
-This means that you should not modify README.md files but rather only edit title.txt and abstract.md files.
+This means that you **should not** modify `README.md` files but rather only edit `title.txt` and `abstract.md` files.
 
-To update the README files, run `python contributing/generate-readmes.py` - this file updates READMEs in place.
+To update the `README.md` files, run `python tools/generate-readmes.py` - this file updates `README.md` in place.
 
 
-### Coding style
+## CMake Coding style
 
-#### Indentation
+### Indentation
 
 We use 2 spaces instead of 4 spaces to reduce the printed page width. No tabs.
 Get the integration for [EditorConfig](https://editorconfig.org/) in your
-favorite editor to help you keep the conventions.
+favorite editor to help you keep this convention.
 
 
-#### Case of commands
+### Case of commands
 
-We use lowercase for commands, i.e.:
+We use lowercase for commands, _i.e._:
 ```cmake
 cmake_minimum_required(VERSION 3.5 FATAL_ERROR)
 ```
@@ -41,9 +39,9 @@ CMAKE_MINIMUM_REQUIRED(VERSION 3.5 FATAL_ERROR)
 ```
 
 
-#### Line continuation
+### Line continuation
 
-It is OK to put commands on one line if it improves readability, e.g.:
+It is OK to put commands on one line if it improves readability, _e.g._:
 ```cmake
 list(APPEND CXX_BASIC_FLAGS "-g3" "-O1")
 ```
@@ -64,9 +62,9 @@ set(_whathaveyou
 ```
 
 
-#### Variable names
+### Variable names
 
-Start an internal variable (i.e. one that is not exposed to the user) with an
+Start an internal variable (_i.e._ one that is not exposed to the user) with an
 underscore:
 ```cmake
 set(PUBLIC_VARIABLE "this one is exposed")

diff --git a/contributing/generate-readmes.py → tools/generate-readmes.py b/contributing/generate-readmes.py → tools/generate-readmes.py
@@ -74,8 +74,8 @@ def generate_main_readme(directory_of_this_script, chapters, chapter_titles,
 published by Packt and authored by [Radovan Bast](https://github.com/bast) and
 [Roberto Di Remigio](https://github.com/robertodr)
 
+- [Contributing](.github/CONTRIBUTING.md)
 - [Testing](testing/README.md)
-- [Contributing](contributing/README.md)
 
 
 ## Table of contents