From d9274f8f9b91792865c345865d9af3a53a5b4135 Mon Sep 17 00:00:00 2001 From: Andreas Maier Date: Wed, 31 Aug 2016 12:07:04 +0200 Subject: [PATCH 1/2] Integrated CONTRIBUTING.rst content in Development section of docs. Signed-off-by: Andreas Maier --- CONTRIBUTING.rst | 116 ------------------------------------------- README.rst | 8 +-- docs/development.rst | 96 +++++++++++++++++++++++++++++++++-- 3 files changed, 97 insertions(+), 123 deletions(-) delete mode 100644 CONTRIBUTING.rst diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst deleted file mode 100644 index 49ba76e0..00000000 --- a/CONTRIBUTING.rst +++ /dev/null @@ -1,116 +0,0 @@ -.. Copyright 2016 IBM Corp. All Rights Reserved. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -Contributing to the zhmcclient project -====================================== - -Third party contributions to this project are welcome! - -In order to contribute, create a `Git pull request`_, considering this: - -.. _Git pull request: https://help.github.com/articles/using-pull-requests/ - -* Test is required. -* Each commit should only contain one "logical" change. -* A "logical" change should be put into one commit, and not split over multiple - commits. -* Large new features should be split into stages. -* The commit message should not only summarize what you have done, but explain - why the change is useful. -* The commit message must follow the format explained below. - -What comprises a "logical" change is subject to sound judgement. Sometimes, it -makes sense to produce a set of commits for a feature (even if not large). -For example, a first commit may introduce a (presumably) compatible API change -without exploitation of that feature. With only this commit applied, it should -be demonstrable that everything is still working as before. The next commit may -be the exploitation of the feature in other components. - -For further discussion of good and bad practices regarding commits, see: - -* `OpenStack Git Commit Good Practice`_ -* `How to Get Your Change Into the Linux Kernel`_ - -.. _OpenStack Git Commit Good Practice: https://wiki.openstack.org/wiki/GitCommitMessages -.. _How to Get Your Change Into the Linux Kernel: https://www.kernel.org/doc/Documentation/SubmittingPatches - -Development and test --------------------- - -See the `README.rst `_ file. - -Format of commit messages -------------------------- - -A commit message must start with a short summary line, followed by a blank -line. - -Optionally, the summary line may start with an identifier that helps -identifying the type of change or the component that is affected, followed by -a colon. - -It can include a more detailed description after the summary line. This is -where you explain why the change was done, and summarize what was done. - -It must end with the DCO (Developer Certificate of Origin) sign-off line in the -format shown in the example below, using your name and a valid email address of -yours. The DCO sign-off line certifies that you followed the rules stated in -`DCO1.1.txt `_. In short, you certify that you wrote the patch or -otherwise have the right to pass it on as an open-source patch. - -We use `GitCop`_ during creation of a pull request to check whether the commit -messages in the pull request comply to this format. -If the commit messages do not comply, GitCop will add a comment to the pull -request with a description of what was wrong. - -.. _GitCop: http://gitcop.com/ - -Example commit message: - -:: - - cookies: Add support for delivering cookies - - Cookies are important for many people. This change adds a pluggable API for - delivering cookies to the user, and provides a default implementation. - - Signed-off-by: Random J Developer - -Use ``git commit --amend`` to edit the commit message, if you need to. - -Use the ``--signoff`` (``-s``) option of ``git commit`` to append a sign-off -line to the commit message with your name and email as known by Git. - -If you like filling out the commit message in an editor instead of using -the ``-m`` option of ``git commit``, you can automate the presence of the -sign-off line by using a commit template file: - -* Create a file outside of the repo (say, ``~/.git-signoff.template``) - that contains, for example: - - :: - - - - - - Signed-off-by: Random J Developer - -* Configure Git to use that file as a commit template for your repo: - - :: - - git config commit.template ~/.git-signoff.template - diff --git a/README.rst b/README.rst index f38a9c75..254193cd 100644 --- a/README.rst +++ b/README.rst @@ -121,12 +121,12 @@ The zhmcclient documentation is on RTD: .. _Documentation for version on Pypi: http://python-zhmcclient.readthedocs.io/en/stable/ .. _Documentation for master branch in Git repo: http://python-zhmcclient.readthedocs.io/en/latest/ -Contributing -============ +Development, test, and contributing +=================================== -Contribution rules are described in `CONTRIBUTING.rst`_. +For more details, see the `Development section`_ in the documentation. -.. _CONTRIBUTING.rst: https://github.com/zhmcclient/python-zhmcclient/tree/master/CONTRIBUTING.rst +.. _Development section: http://python-zhmcclient.readthedocs.io/en/stable/development.html License ======= diff --git a/docs/development.rst b/docs/development.rst index 72b6487a..075c2c95 100644 --- a/docs/development.rst +++ b/docs/development.rst @@ -112,7 +112,97 @@ syntax of its ``-k`` option. Contributing ------------ -You are welcome to contribute to the project! The rules for contributing are -described in the file `CONTRIBUTING.rst`_. +Third party contributions to this project are welcome! -.. _CONTRIBUTING.rst: https://github.com/zhmcclient/python-zhmcclient/tree/master/CONTRIBUTING.rst +In order to contribute, create a `Git pull request`_, considering this: + +.. _Git pull request: https://help.github.com/articles/using-pull-requests/ + +* Test is required. +* Each commit should only contain one "logical" change. +* A "logical" change should be put into one commit, and not split over multiple + commits. +* Large new features should be split into stages. +* The commit message should not only summarize what you have done, but explain + why the change is useful. +* The commit message must follow the format explained below. + +What comprises a "logical" change is subject to sound judgement. Sometimes, it +makes sense to produce a set of commits for a feature (even if not large). +For example, a first commit may introduce a (presumably) compatible API change +without exploitation of that feature. With only this commit applied, it should +be demonstrable that everything is still working as before. The next commit may +be the exploitation of the feature in other components. + +For further discussion of good and bad practices regarding commits, see: + +* `OpenStack Git Commit Good Practice`_ +* `How to Get Your Change Into the Linux Kernel`_ + +.. _OpenStack Git Commit Good Practice: https://wiki.openstack.org/wiki/GitCommitMessages +.. _How to Get Your Change Into the Linux Kernel: https://www.kernel.org/doc/Documentation/SubmittingPatches + +Format of commit messages +------------------------- + +A commit message must start with a short summary line, followed by a blank +line. + +Optionally, the summary line may start with an identifier that helps +identifying the type of change or the component that is affected, followed by +a colon. + +It can include a more detailed description after the summary line. This is +where you explain why the change was done, and summarize what was done. + +It must end with the DCO (Developer Certificate of Origin) sign-off line in the +format shown in the example below, using your name and a valid email address of +yours. The DCO sign-off line certifies that you followed the rules stated in +`DCO 1.1`_. In short, you certify that you wrote the patch or otherwise have +the right to pass it on as an open-source patch. + +.. _DCO 1.1: https://raw.githubusercontent.com/zhmcclient/python-zhmcclient/master/DCO1.1.txt + +We use `GitCop`_ during creation of a pull request to check whether the commit +messages in the pull request comply to this format. +If the commit messages do not comply, GitCop will add a comment to the pull +request with a description of what was wrong. + +.. _GitCop: http://gitcop.com/ + +Example commit message: + +:: + + cookies: Add support for delivering cookies + + Cookies are important for many people. This change adds a pluggable API for + delivering cookies to the user, and provides a default implementation. + + Signed-off-by: Random J Developer + +Use ``git commit --amend`` to edit the commit message, if you need to. + +Use the ``--signoff`` (``-s``) option of ``git commit`` to append a sign-off +line to the commit message with your name and email as known by Git. + +If you like filling out the commit message in an editor instead of using +the ``-m`` option of ``git commit``, you can automate the presence of the +sign-off line by using a commit template file: + +* Create a file outside of the repo (say, ``~/.git-signoff.template``) + that contains, for example: + + :: + + + + + + Signed-off-by: Random J Developer + +* Configure Git to use that file as a commit template for your repo: + + :: + + git config commit.template ~/.git-signoff.template From 81d9f4f2f19234342d972b88acebc5400f0460b7 Mon Sep 17 00:00:00 2001 From: Andreas Maier Date: Wed, 31 Aug 2016 14:26:24 +0200 Subject: [PATCH 2/2] Editorial update in dev heading of README. Signed-off-by: Andreas Maier --- README.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.rst b/README.rst index 254193cd..48282a38 100644 --- a/README.rst +++ b/README.rst @@ -121,8 +121,8 @@ The zhmcclient documentation is on RTD: .. _Documentation for version on Pypi: http://python-zhmcclient.readthedocs.io/en/stable/ .. _Documentation for master branch in Git repo: http://python-zhmcclient.readthedocs.io/en/latest/ -Development, test, and contributing -=================================== +Development, testing, and contributing +====================================== For more details, see the `Development section`_ in the documentation.