From 1f5d328511bc657e8203087b88d490fe8403253f Mon Sep 17 00:00:00 2001 From: Roberto Di Remigio Date: Sun, 23 Sep 2018 16:57:56 -0400 Subject: [PATCH] Add CONTRIBUTING.md This explains how DCO works and what it implies for contributors Signed-off-by: Roberto Di Remigio --- .github/CONTRIBUTING.md | 163 +++++++------------- README.md | 2 +- contributing/README.md => STYLE_GUIDE.md | 34 ++-- {contributing => tools}/generate-readmes.py | 2 +- 4 files changed, 74 insertions(+), 127 deletions(-) rename contributing/README.md => STYLE_GUIDE.md (57%) rename {contributing => tools}/generate-readmes.py (99%) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index a2e5c4f56..58250b5aa 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -1,124 +1,52 @@ # 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: - -* 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) +We welcome contributions from external contributors. +This document describes the contribution process: from proposing a change to +getting it merged into CMake Cookbook. +Our contribution guide is based on [Psi4 contribution guide]. ## 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 - [here](http://psicode.org/psi4manual/master/build_obtaining.html#faq-forkpsi4public). - and [here](http://psicode.org/psi4manual/master/build_obtaining.html#faq-githubworkflow). +* 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. ## 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 @@ -126,3 +54,24 @@ set(_temp "this one is internal") * [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/) + + +[Psi4 contribution guide]: https://github.com/psi4/psi4/blob/master/.github/CONTRIBUTING.md +[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 index dd601377f..70653a921 100644 --- 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 b/STYLE_GUIDE.md similarity index 57% rename from contributing/README.md rename to STYLE_GUIDE.md index 1d739bc76..6536abe04 100644 --- a/contributing/README.md +++ b/STYLE_GUIDE.md @@ -1,8 +1,6 @@ +# 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. @@ -10,28 +8,28 @@ 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 b/tools/generate-readmes.py similarity index 99% rename from contributing/generate-readmes.py rename to tools/generate-readmes.py index e56a8ada9..d5308aedf 100644 --- a/contributing/generate-readmes.py +++ b/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