From 255efa729dcc3b57901516133481f9fca66f5226 Mon Sep 17 00:00:00 2001 From: Stephen Finucane Date: Tue, 18 Oct 2016 21:03:41 +0100 Subject: doc: Convert CONTRIBUTING to rST Signed-off-by: Stephen Finucane Signed-off-by: Russell Bryant --- CONTRIBUTING.md | 414 -------------------------- CONTRIBUTING.rst | 444 ++++++++++++++++++++++++++++ Documentation/committer-responsibilities.md | 4 +- Makefile.am | 2 +- OPENFLOW-1.1+.md | 2 +- SECURITY.rst | 2 +- 6 files changed, 449 insertions(+), 419 deletions(-) delete mode 100644 CONTRIBUTING.md create mode 100644 CONTRIBUTING.rst diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index f848536d1..000000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,414 +0,0 @@ -How to Submit Patches for Open vSwitch -====================================== - -Send changes to Open vSwitch as patches to dev@openvswitch.org. -One patch per email, please. More details are included below. - -If you are using Git, then `git format-patch` takes care of most of -the mechanics described below for you. - -Before You Start ----------------- - -Before you send patches at all, make sure that each patch makes sense. -In particular: - - - A given patch should not break anything, even if later - patches fix the problems that it causes. The source tree - should still build and work after each patch is applied. - (This enables `git bisect` to work best.) - - - A patch should make one logical change. Don't make - multiple, logically unconnected changes to disparate - subsystems in a single patch. - - - A patch that adds or removes user-visible features should - also update the appropriate user documentation or manpages. - Check "Feature Deprecation Guidelines" section in this document - if you intend to remove user-visible feature. - -Testing is also important: - - - A patch that modifies existing code should be tested with `make - check` before submission. Please see INSTALL.rst, under - "Self-Tests", for more information. - - - A patch that adds or deletes files should also be tested with - `make distcheck` before submission. - - - A patch that modifies Linux kernel code should be at least - build-tested on various Linux kernel versions before - submission. I suggest versions 3.10 and whatever - the current latest release version is at the time. - - - A patch that modifies the ofproto or vswitchd code should be - tested in at least simple cases before submission. - - - A patch that modifies xenserver code should be tested on - XenServer before submission. - -If you are using GitHub, then you may utilize the travis-ci.org CI build -system by linking your GitHub repository to it. This will run some of -the above tests automatically when you push changes to your repository. -See the "Continuous Integration with Travis-CI" in the [INSTALL.rst] file -for details on how to set it up. - -Email Subject -------------- - -The subject line of your email should be in the following format: -`[PATCH /] : ` - - - `[PATCH /]` indicates that this is the nth of a series - of m patches. It helps reviewers to read patches in the - correct order. You may omit this prefix if you are sending - only one patch. - - - `:` indicates the area of the Open vSwitch to which the - change applies (often the name of a source file or a - directory). You may omit it if the change crosses multiple - distinct pieces of code. - - - `` briefly describes the change. - -The subject, minus the `[PATCH /]` prefix, becomes the first line -of the commit's change log message. - -Description ------------ - -The body of the email should start with a more thorough description of -the change. This becomes the body of the commit message, following -the subject. There is no need to duplicate the summary given in the -subject. - -Please limit lines in the description to 79 characters in width. - -The description should include: - - - The rationale for the change. - - - Design description and rationale (but this might be better - added as code comments). - - - Testing that you performed (or testing that should be done - but you could not for whatever reason). - - - Tags (see below). - -There is no need to describe what the patch actually changed, if the -reader can see it for himself. - -If the patch refers to a commit already in the Open vSwitch -repository, please include both the commit number and the subject of -the patch, e.g. 'commit 632d136c (vswitch: Remove restriction on -datapath names.)'. - -If you, the person sending the patch, did not write the patch -yourself, then the very first line of the body should take the form -`From: `, followed by a blank line. This -will automatically cause the named author to be credited with -authorship in the repository. - -Tags ----- - -The description ends with a series of tags, written one to a line as -the last paragraph of the email. Each tag indicates some property of -the patch in an easily machine-parseable manner. - -Examples of common tags follow. - - Signed-off-by: Author Name - - Informally, this indicates that Author Name is the author or - submitter of a patch and has the authority to submit it under - the terms of the license. The formal meaning is to agree to - the Developer's Certificate of Origin (see below). - - If the author and submitter are different, each must sign off. - If the patch has more than one author, all must sign off. - - Signed-off-by: Author Name - Signed-off-by: Submitter Name - - Co-authored-by: Author Name - - Git can only record a single person as the author of a given - patch. In the rare event that a patch has multiple authors, - one must be given the credit in Git and the others must be - credited via Co-authored-by: tags. (All co-authors must also - sign off.) - - Acked-by: Reviewer Name - - Reviewers will often give an Acked-by: tag to code of which - they approve. It is polite for the submitter to add the tag - before posting the next version of the patch or applying the - patch to the repository. Quality reviewing is hard work, so - this gives a small amount of credit to the reviewer. - - Not all reviewers give Acked-by: tags when they provide - positive reviews. It's customary only to add tags from - reviewers who actually provide them explicitly. - - Tested-by: Tester Name - - When someone tests a patch, it is customary to add a - Tested-by: tag indicating that. It's rare for a tester to - actually provide the tag; usually the patch submitter makes - the tag himself in response to an email indicating successful - testing results. - - Tested-at: - - When a test report is publicly available, this provides a way - to reference it. Typical s would be build logs from - autobuilders or references to mailing list archives. - - Some autobuilders only retain their logs for a limited amount - of time. It is less useful to cite these because they may be - dead links for a developer reading the commit message months - or years later. - - Reported-by: Reporter Name - - When a patch fixes a bug reported by some person, please - credit the reporter in the commit log in this fashion. Please - also add the reporter's name and email address to the list of - people who provided helpful bug reports in the AUTHORS file at - the top of the source tree. - - Fairly often, the reporter of a bug also tests the fix. - Occasionally one sees a combined "Reported-and-tested-by:" tag - used to indicate this. It is also acceptable, and more - common, to include both tags separately. - - (If a bug report is received privately, it might not always be - appropriate to publicly credit the reporter. If in doubt, - please ask the reporter.) - - Requested-by: Requester Name - Suggested-by: Suggester Name - - When a patch implements a request or a suggestion made by some - person, please credit that person in the commit log in this - fashion. For a helpful suggestion, please also add the - person's name and email address to the list of people who - provided suggestions in the AUTHORS file at the top of the - source tree. - - (If a suggestion or a request is received privately, it might - not always be appropriate to publicly give credit. If in - doubt, please ask.) - - CC: Person - - This is a way to tag a patch for the attention of a person - when no more specific tag is appropriate. One use is to - request a review from a particular person. It doesn't make - sense to include the same person in CC and another tag, so - e.g. if someone who is CCed later provides an Acked-by, add - the Acked-by and remove the CC at the same time. - - Reported-at: - - If a patch fixes or is otherwise related to a bug reported in - a public bug tracker, please include a reference to the bug in - the form of a URL to the specific bug, e.g.: - - Reported-at: https://bugs.debian.org/743635 - - This is also an appropriate way to refer to bug report emails - in public email archives, e.g.: - - Reported-at: http://openvswitch.org/pipermail/dev/2014-June/040952.html - - Submitted-at: - - If a patch was submitted somewhere other than the Open vSwitch - development mailing list, such as a GitHub pull request, this header can - be used to reference the source. - - Submitted-at: https://github.com/openvswitch/ovs/pull/92 - - VMware-BZ: #1234567 - ONF-JIRA: EXT-12345 - - If a patch fixes or is otherwise related to a bug reported in - a private bug tracker, you may include some tracking ID for - the bug for your own reference. Please include some - identifier to make the origin clear, e.g. "VMware-BZ" refers - to VMware's internal Bugzilla instance and "ONF-JIRA" refers - to the Open Networking Foundation's JIRA bug tracker. - - Bug #1234567. - Issue: 1234567 - - These are obsolete forms of VMware-BZ: that can still be seen - in old change log entries. (They are obsolete because they do - not tell the reader what bug tracker is referred to.) - - Fixes: 63bc9fb1c69f (“packets: Reorder CS_* flags to remove gap.”) - - If you would like to record which commit introduced a bug being fixed, - you may do that with a “Fixes” header. This assists in determining - which OVS releases have the bug, so the patch can be applied to all - affected versions. The easiest way to generate the header in the - proper format is with this git command. This command also CCs the - author of the commit being fixed, which makes sense unless the - author also made the fix or is already named in another tag: - - git log -1 --pretty=format:"CC: %an <%ae>%nFixes: %h (\"%s\")" --abbrev=12 COMMIT_REF - - Vulnerability: CVE-2016-2074 - - Specifies that the patch fixes or is otherwise related to a - security vulnerability with the given CVE identifier. Other - identifiers in public vulnerability databases are also - suitable. - - If the vulnerability was reported publicly, then it is also - appropriate to cite the URL to the report in a Reported-at - tag. Use a Reported-by tag to acknowledge the reporters. - -Developer's Certificate of Origin ---------------------------------- - -To help track the author of a patch as well as the submission chain, -and be clear that the developer has authority to submit a patch for -inclusion in openvswitch please sign off your work. The sign off -certifies the following: - - Developer's Certificate of Origin 1.1 - - 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. - -Feature Deprecation Guidelines ------------------------------- - -Open vSwitch is intended to be user friendly. This means that under -normal circumstances we don't abruptly remove features from OVS that -some users might still be using. Otherwise, if we would, then we would -possibly break our user setup when they upgrade and would receive bug -reports. - -Typical process to deprecate a feature in Open vSwitch is to: - - (a) Mention deprecation of a feature in the NEWS file. Also, mention - expected release or absolute time when this feature would be removed - from OVS altogether. Don't use relative time (e.g. "in 6 months") - because that is not clearly interpretable. - - (b) If Open vSwitch is configured to use deprecated feature it should print - a warning message to the log files clearly indicating that feature is - deprecated and that use of it should be avoided. - - (c) If this feature is mentioned in man pages, then add "Deprecated" keyword - to it. - -Also, if there is alternative feature to the one that is about to be marked -as deprecated, then mention it in (a), (b) and (c) as well. - -Remember to followup and actually remove the feature from OVS codebase -once deprecation grace period has expired and users had opportunity to -use at least one OVS release that would have informed them about feature -deprecation! - -Comments --------- - -If you want to include any comments in your email that should not be -part of the commit's change log message, put them after the -description, separated by a line that contains just `---`. It may be -helpful to include a diffstat here for changes that touch multiple -files. - -Patch ------ - -The patch should be in the body of the email following the description, -separated by a blank line. - -Patches should be in `diff -up` format. We recommend that you use Git -to produce your patches, in which case you should use the `-M -C` -options to `git diff` (or other Git tools) if your patch renames or -copies files. Quilt (http://savannah.nongnu.org/projects/quilt) might -be useful if you do not want to use Git. - -Patches should be inline in the email message. Some email clients -corrupt white space or wrap lines in patches. There are hints on how -to configure many email clients to avoid this problem at: - http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=blob_plain;f=Documentation/email-clients.txt -If you cannot convince your email client not to mangle patches, then -sending the patch as an attachment is a second choice. - -Please follow the style used in the code that you are modifying. The -[CodingStyle] file describes the coding style used in most of Open -vSwitch. Use Linux kernel coding style for Linux kernel code. - -If your code is non-datapath code, you may use the -`utilities/checkpatch.py` utility as a quick check for certain commonly -occuring mistakes (improper leading/trailing whitespace, missing signoffs, -some improper formatted patch files). For linux datapath code, it is -a good idea to use the linux script `checkpatch.pl`. - -Example -------- - -``` -From fa29a1c2c17682879e79a21bb0cdd5bbe67fa7c0 Mon Sep 17 00:00:00 2001 -From: Jesse Gross -Date: Thu, 8 Dec 2011 13:17:24 -0800 -Subject: [PATCH] datapath: Alphabetize include/net/ipv6.h compat header. - -Signed-off-by: Jesse Gross ---- - datapath/linux/Modules.mk | 2 +- - 1 files changed, 1 insertions(+), 1 deletions(-) - -diff --git a/datapath/linux/Modules.mk b/datapath/linux/Modules.mk -index fdd952e..f6cb88e 100644 ---- a/datapath/linux/Modules.mk -+++ b/datapath/linux/Modules.mk -@@ -56,11 +56,11 @@ openvswitch_headers += \ - linux/compat/include/net/dst.h \ - linux/compat/include/net/genetlink.h \ - linux/compat/include/net/ip.h \ -+ linux/compat/include/net/ipv6.h \ - linux/compat/include/net/net_namespace.h \ - linux/compat/include/net/netlink.h \ - linux/compat/include/net/protocol.h \ - linux/compat/include/net/route.h \ -- linux/compat/include/net/ipv6.h \ - linux/compat/genetlink.inc - - both_modules += brcompat --- -1.7.7.3 -``` - -[INSTALL.rst]:INSTALL.rst -[CodingStyle]: CodingStyle.rst diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst new file mode 100644 index 000000000..867562ef3 --- /dev/null +++ b/CONTRIBUTING.rst @@ -0,0 +1,444 @@ +.. + 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. + + Convention for heading levels in Open vSwitch documentation: + + ======= Heading 0 (reserved for the title in a document) + ------- Heading 1 + ~~~~~~~ Heading 2 + +++++++ Heading 3 + ''''''' Heading 4 + + Avoid deeper levels because they do not render well. + +============================ +Contributing to Open vSwitch +============================ + +Send changes to Open vSwitch as patches to dev@openvswitch.org. One patch per +email. More details are included below. + +If you are using Git, then `git format-patch` takes care of most of the +mechanics described below for you. + +Before You Start +---------------- + +Before you send patches at all, make sure that each patch makes sense. In +particular: + +- A given patch should not break anything, even if later patches fix the + problems that it causes. The source tree should still build and work after + each patch is applied. (This enables `git bisect` to work best.) + +- A patch should make one logical change. Don't make multiple, logically + unconnected changes to disparate subsystems in a single patch. + +- A patch that adds or removes user-visible features should also update the + appropriate user documentation or manpages. Check "Feature Deprecation + Guidelines" section in this document if you intend to remove user-visible + feature. + +Testing is also important: + +- A patch that modifies existing code should be tested with ``make + check`` before submission. Please see the `install guide `__, + under "Self-Tests", for more information. + +- A patch that adds or deletes files should also be tested with ``make + distcheck`` before submission. + +- A patch that modifies Linux kernel code should be at least build-tested on + various Linux kernel versions before submission. I suggest versions 3.10 and + whatever the current latest release version is at the time. + +- A patch that modifies the ofproto or vswitchd code should be tested in at + least simple cases before submission. + +- A patch that modifies xenserver code should be tested on XenServer before + submission. + +If you are using GitHub, then you may utilize the travis-ci.org CI build system +by linking your GitHub repository to it. This will run some of the above tests +automatically when you push changes to your repository. See the "Continuous +Integration with Travis-CI" in the `install guide `__ for details +on how to set it up. + +Email Subject +------------- + +The subject line of your email should be in the following format: + + [PATCH /] : + +Where: + +``[PATCH /]``: + indicates that this is the nth of a series of m patches. It helps reviewers + to read patches in the correct order. You may omit this prefix if you are + sending only one patch. + +````: + indicates the area of the Open vSwitch to which the change applies (often the + name of a source file or a directory). You may omit it if the change crosses + multiple distinct pieces of code. + +````: + briefly describes the change. + +The subject, minus the ``[PATCH /]`` prefix, becomes the first line of +the commit's change log message. + +Description +----------- + +The body of the email should start with a more thorough description of the +change. This becomes the body of the commit message, following the subject. +There is no need to duplicate the summary given in the subject. + +Please limit lines in the description to 79 characters in width. + +The description should include: + +- The rationale for the change. + +- Design description and rationale (but this might be better added as code + comments). + +- Testing that you performed (or testing that should be done but you could not + for whatever reason). + +- Tags (see below). + +There is no need to describe what the patch actually changed, if the reader can +see it for himself. + +If the patch refers to a commit already in the Open vSwitch repository, please +include both the commit number and the subject of the patch, e.g. 'commit +632d136c (vswitch: Remove restriction on datapath names.)'. + +If you, the person sending the patch, did not write the patch yourself, then +the very first line of the body should take the form ``From: +``, followed by a blank line. This will automatically cause the +named author to be credited with authorship in the repository. + +Tags +---- + +The description ends with a series of tags, written one to a line as the last +paragraph of the email. Each tag indicates some property of the patch in an +easily machine-parseable manner. + +Examples of common tags follow. + +``Signed-off-by: Author Name `` + + Informally, this indicates that Author Name is the author or submitter of a + patch and has the authority to submit it under the terms of the license. The + formal meaning is to agree to the Developer's Certificate of Origin (see + below). + + If the author and submitter are different, each must sign off. If the patch + has more than one author, all must sign off. + + :: + + Signed-off-by: Author Name + Signed-off-by: Submitter Name + +``Co-authored-by: Author Name `` + + Git can only record a single person as the author of a given patch. In the + rare event that a patch has multiple authors, one must be given the credit in + Git and the others must be credited via Co-authored-by: tags. (All + co-authors must also sign off.) + +``Acked-by: Reviewer Name `` + + Reviewers will often give an ``Acked-by:`` tag to code of which they approve. + It is polite for the submitter to add the tag before posting the next version + of the patch or applying the patch to the repository. Quality reviewing is + hard work, so this gives a small amount of credit to the reviewer. + + Not all reviewers give ``Acked-by:`` tags when they provide positive reviews. + It's customary only to add tags from reviewers who actually provide them + explicitly. + +``Tested-by: Tester Name `` + + When someone tests a patch, it is customary to add a Tested-by: tag + indicating that. It's rare for a tester to actually provide the tag; usually + the patch submitter makes the tag himself in response to an email indicating + successful testing results. + +``Tested-at: `` + + When a test report is publicly available, this provides a way to reference + it. Typical s would be build logs from autobuilders or references to + mailing list archives. + + Some autobuilders only retain their logs for a limited amount of time. It is + less useful to cite these because they may be dead links for a developer + reading the commit message months or years later. + +``Reported-by: Reporter Name `` + + When a patch fixes a bug reported by some person, please credit the reporter + in the commit log in this fashion. Please also add the reporter's name and + email address to the list of people who provided helpful bug reports in the + AUTHORS file at the top of the source tree. + + Fairly often, the reporter of a bug also tests the fix. Occasionally one + sees a combined "Reported-and-tested-by:" tag used to indicate this. It is + also acceptable, and more common, to include both tags separately. + + (If a bug report is received privately, it might not always be appropriate to + publicly credit the reporter. If in doubt, please ask the reporter.) + +``Requested-by: Requester Name `` + + When a patch implements a request or a suggestion made by some + person, please credit that person in the commit log in this + fashion. For a helpful suggestion, please also add the + person's name and email address to the list of people who + provided suggestions in the AUTHORS file at the top of the + source tree. + + (If a suggestion or a request is received privately, it might + not always be appropriate to publicly give credit. If in + doubt, please ask.) + +``Suggested-by: Suggester Name `` + + See ``Requested-by:``. + +``CC: Person `` + + This is a way to tag a patch for the attention of a person + when no more specific tag is appropriate. One use is to + request a review from a particular person. It doesn't make + sense to include the same person in CC and another tag, so + e.g. if someone who is CCed later provides an Acked-by, add + the Acked-by and remove the CC at the same time. + +``Reported-at: `` + + If a patch fixes or is otherwise related to a bug reported in + a public bug tracker, please include a reference to the bug in + the form of a URL to the specific bug, e.g.: + + :: + + Reported-at: https://bugs.debian.org/743635 + + This is also an appropriate way to refer to bug report emails + in public email archives, e.g.: + + :: + + Reported-at: http://openvswitch.org/pipermail/dev/2014-June/040952.html + +``Submitted-at: `` + + If a patch was submitted somewhere other than the Open vSwitch + development mailing list, such as a GitHub pull request, this header can + be used to reference the source. + + :: + + Submitted-at: https://github.com/openvswitch/ovs/pull/92 + +``VMware-BZ: #1234567`` + + If a patch fixes or is otherwise related to a bug reported in + a private bug tracker, you may include some tracking ID for + the bug for your own reference. Please include some + identifier to make the origin clear, e.g. "VMware-BZ" refers + to VMware's internal Bugzilla instance and "ONF-JIRA" refers + to the Open Networking Foundation's JIRA bug tracker. + +``ONF-JIRA: EXT-12345`` + + See ``VMware-BZ:``. + +``Bug #1234567.`` + + These are obsolete forms of VMware-BZ: that can still be seen + in old change log entries. (They are obsolete because they do + not tell the reader what bug tracker is referred to.) + +``Issue: 1234567`` + + See ``Bug:``. + +``Fixes: 63bc9fb1c69f (“packets: Reorder CS_* flags to remove gap.”)`` + + If you would like to record which commit introduced a bug being fixed, + you may do that with a “Fixes” header. This assists in determining + which OVS releases have the bug, so the patch can be applied to all + affected versions. The easiest way to generate the header in the + proper format is with this git command. This command also CCs the + author of the commit being fixed, which makes sense unless the + author also made the fix or is already named in another tag: + + :: + + $ git log -1 --pretty=format:"CC: %an <%ae>%nFixes: %h (\"%s\")" \ + --abbrev=12 COMMIT_REF + +``Vulnerability: CVE-2016-2074`` + + Specifies that the patch fixes or is otherwise related to a + security vulnerability with the given CVE identifier. Other + identifiers in public vulnerability databases are also + suitable. + + If the vulnerability was reported publicly, then it is also + appropriate to cite the URL to the report in a Reported-at + tag. Use a Reported-by tag to acknowledge the reporters. + +Developer's Certificate of Origin +--------------------------------- + +To help track the author of a patch as well as the submission chain, and be +clear that the developer has authority to submit a patch for inclusion in +openvswitch please sign off your work. The sign off certifies the following: + +:: + + Developer's Certificate of Origin 1.1 + + 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. + +Feature Deprecation Guidelines +------------------------------ + +Open vSwitch is intended to be user friendly. This means that under normal +circumstances we don't abruptly remove features from OVS that some users might +still be using. Otherwise, if we would, then we would possibly break our user +setup when they upgrade and would receive bug reports. + +Typical process to deprecate a feature in Open vSwitch is to: + +(a) Mention deprecation of a feature in the NEWS file. Also, mention expected + release or absolute time when this feature would be removed from OVS + altogether. Don't use relative time (e.g. "in 6 months") because that is + not clearly interpretable. + +(b) If Open vSwitch is configured to use deprecated feature it should print + a warning message to the log files clearly indicating that feature is + deprecated and that use of it should be avoided. + +(c) If this feature is mentioned in man pages, then add "Deprecated" keyword + to it. + +Also, if there is alternative feature to the one that is about to be marked as +deprecated, then mention it in (a), (b) and (c) as well. + +Remember to follow-up and actually remove the feature from OVS codebase once +deprecation grace period has expired and users had opportunity to use at least +one OVS release that would have informed them about feature deprecation! + +Comments +-------- + +If you want to include any comments in your email that should not be part of +the commit's change log message, put them after the description, separated by a +line that contains just `---`. It may be helpful to include a diffstat here +for changes that touch multiple files. + +Patch +----- + +The patch should be in the body of the email following the description, +separated by a blank line. + +Patches should be in ``diff -up`` format. We recommend that you use Git to +produce your patches, in which case you should use the ``-M -C`` options to +``git diff`` (or other Git tools) if your patch renames or copies files. +`Quilt `__ might be useful if you do +not want to use Git. + +Patches should be inline in the email message. Some email clients corrupt +white space or wrap lines in patches. There are hints on how to configure many +email clients to avoid this problem on `kernel.org +`__. +If you cannot convince your email client not to mangle patches, then sending +the patch as an attachment is a second choice. + +Please follow the style used in the code that you are modifying. The +`CodingStyle `__ file describes the coding style used in most +of Open vSwitch. Use Linux kernel coding style for Linux kernel code. + +If your code is non-datapath code, you may use the ``utilities/checkpatch.py`` +utility as a quick check for certain commonly occuring mistakes (improper +leading/trailing whitespace, missing signoffs, some improper formatted patch +files). For linux datapath code, it is a good idea to use the linux script +``checkpatch.pl``. + +Example +------- + +:: + + From fa29a1c2c17682879e79a21bb0cdd5bbe67fa7c0 Mon Sep 17 00:00:00 2001 + From: Jesse Gross + Date: Thu, 8 Dec 2011 13:17:24 -0800 + Subject: [PATCH] datapath: Alphabetize include/net/ipv6.h compat header. + + Signed-off-by: Jesse Gross + --- + datapath/linux/Modules.mk | 2 +- + 1 files changed, 1 insertions(+), 1 deletions(-) + + diff --git a/datapath/linux/Modules.mk b/datapath/linux/Modules.mk + index fdd952e..f6cb88e 100644 + --- a/datapath/linux/Modules.mk + +++ b/datapath/linux/Modules.mk + @@ -56,11 +56,11 @@ openvswitch_headers += \ + linux/compat/include/net/dst.h \ + linux/compat/include/net/genetlink.h \ + linux/compat/include/net/ip.h \ + + linux/compat/include/net/ipv6.h \ + linux/compat/include/net/net_namespace.h \ + linux/compat/include/net/netlink.h \ + linux/compat/include/net/protocol.h \ + linux/compat/include/net/route.h \ + - linux/compat/include/net/ipv6.h \ + linux/compat/genetlink.inc + + both_modules += brcompat + -- + 1.7.7.3 diff --git a/Documentation/committer-responsibilities.md b/Documentation/committer-responsibilities.md index 9e93c4e67..40ffb51fb 100644 --- a/Documentation/committer-responsibilities.md +++ b/Documentation/committer-responsibilities.md @@ -5,7 +5,7 @@ Prerequisites ------------- Be familiar with [CodingStyle.md](../CodingStyle.md) and -[CONTRIBUTING.md](../CONTRIBUTING.md). +[CONTRIBUTING.rst](../CONTRIBUTING.rst). Review ------ @@ -70,7 +70,7 @@ the use of "Signed-off-by:" to a new developer, explain not just how but why, since the intended meaning of "Signed-off-by:" is more important than the syntax. As part of your explanation, quote or provide a URL to the Developer's Certificate of Origin in -[CONTRIBUTING.md](../CONTRIBUTING.md). +[CONTRIBUTING.rst](../CONTRIBUTING.rst). Use Reported-by: and Tested-by: tags in commit messages to indicate the source of a bug report. diff --git a/Makefile.am b/Makefile.am index a08e7e0e0..7424c17ed 100644 --- a/Makefile.am +++ b/Makefile.am @@ -66,7 +66,7 @@ PYCOV_CLEAN_FILES = build-aux/check-structs,cover # A list of Markdown- or reStructuredText-formatted documentation that will # automatically be included in the "make dist-docs" output. docs = \ - CONTRIBUTING.md \ + CONTRIBUTING.rst \ CodingStyle.rst \ DESIGN.md \ DocumentationStyle.rst \ diff --git a/OPENFLOW-1.1+.md b/OPENFLOW-1.1+.md index cebaa1701..a1905f3d0 100644 --- a/OPENFLOW-1.1+.md +++ b/OPENFLOW-1.1+.md @@ -304,7 +304,7 @@ Please consider the following: * Coding style (see the [CodingStyle] file at the top of the source tree). - * The patch submission guidelines (see [CONTRIBUTING.md]). I + * The patch submission guidelines (see [CONTRIBUTING.rst]). I recommend using "git send-email", which automatically follows a lot of those guidelines. diff --git a/SECURITY.rst b/SECURITY.rst index 5061e53bd..32b79f580 100644 --- a/SECURITY.rst +++ b/SECURITY.rst @@ -178,7 +178,7 @@ sections for the document include: * Patch: If a patch or patches are available, and it is practical to include them in the email, put them at the end. Format them - as described in CONTRIBUTING.md, that is, as output by "git + as described in CONTRIBUTING.rst, that is, as output by "git format-patch". The patch subjects should include the version for which they are -- cgit v1.2.1