mir/ovs
2
0
Fork 0
mirror of https://github.com/openvswitch/ovs synced 2025-08-22 09:58:01 +00:00
Code Issues Releases Wiki Activity

doc: Populate 'internals' section

Browse Source 
This is mostly docs moved from the top-level directory and content
scraped from the Open vSwitch website source [1].

[1] https://github.com/openvswitch/openvswitch.github.io/

Signed-off-by: Stephen Finucane <stephen@that.guru>
Signed-off-by: Ben Pfaff <blp@ovn.org>
This commit is contained in:
Stephen Finucane 2016-12-08 12:55:23 +00:00 committed by Ben Pfaff
parent 4f6ec357cd
commit d0e53b1532
19 changed files with 720 additions and 455 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

430
CONTRIBUTING.rst
View File

@ -25,428 +25,10 @@
Contributing to Open vSwitch Contributing to Open vSwitch
============================ ============================
Send changes to Open vSwitch as patches to dev@openvswitch.org. One patch per As an open source project, we welcome contributions of any kind. These can
email. More details are included below. range from bug reports and code reviews, to signficant code or documentation
features.
If you are using Git, then `git format-patch` takes care of most of the Extensive guidelines are provided in the docs at
mechanics described below for you. ``docs/internals/contributing``, or `online
<https://docs.openvswitch.org/en/dev/internals/contributing>`__.
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 <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 guide <INSTALL.rst>`__ for details
on how to set it up.
Email Subject
-------------
The subject line of your email should be in the following format:
[PATCH <n>/<m>] <area>: <summary>
Where:
``[PATCH <n>/<m>]``:
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.
``<area>``:
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.
``<summary>``:
briefly describes the change. Use the the imperative form,
e.g. "Force SNAT for multiple gateway routers." or "Fix daemon exit
for bad datapaths or flows." Try to keep the summary short, about
50 characters wide.
The subject, minus the ``[PATCH <n>/<m>]`` 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 75 characters in width. That
allows the description to format properly even when indented (e.g. by
"git log" or in email quotations).
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: <author name>
<author email>``, 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 <author.name@email.address...>``
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 <author.name@email.address...>
Signed-off-by: Submitter Name <submitter.name@email.address...>
``Co-authored-by: Author Name <author.name@email.address...>``
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 <reviewer.name@email.address...>``
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 <reviewer.name@email.address...>``
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: <URL>``
When a test report is publicly available, this provides a way to reference
it. Typical <URL>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 <reporter.name@email.address...>``
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 <requester.name@email.address...>``
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 <suggester.name@email.address...>``
See ``Requested-by:``.
``CC: Person <name@email>``
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: <URL>``
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: <URL>``
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.
See also http://developercertificate.org/.
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 <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 on `kernel.org
<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 <CodingStyle.rst>`__ 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 <jesse@nicira.com>
Date: Thu, 8 Dec 2011 13:17:24 -0800
Subject: [PATCH] datapath: Alphabetize include/net/ipv6.h compat header.
Signed-off-by: Jesse Gross <jesse@nicira.com>
---
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

20
Documentation/automake.mk
View File

@ -1,9 +1,6 @@
docs += \ docs += \
Documentation/committer-responsibilities.rst \
Documentation/committer-grant-revocation.rst \
Documentation/group-selection-method-property.txt \ Documentation/group-selection-method-property.txt \
Documentation/OVSDB-replication.rst \ Documentation/OVSDB-replication.rst
Documentation/release-process.rst
EXTRA_DIST += \ EXTRA_DIST += \
Documentation/_static/logo.png \ Documentation/_static/logo.png \
@ -17,7 +14,20 @@ EXTRA_DIST += \
Documentation/howto/index.rst \ Documentation/howto/index.rst \
Documentation/ref/index.rst \ Documentation/ref/index.rst \
Documentation/faq/index.rst \ Documentation/faq/index.rst \
Documentation/internals/index.rst Documentation/internals/index.rst \
Documentation/internals/authors.rst \
Documentation/internals/bugs.rst \
Documentation/internals/committer-grant-revocation.rst \
Documentation/internals/committer-responsibilities.rst \
Documentation/internals/mailing-lists.rst \
Documentation/internals/maintainers.rst \
Documentation/internals/release-process.rst \
Documentation/internals/security.rst \
Documentation/internals/contributing/index.rst \
Documentation/internals/contributing/coding-style.rst \
Documentation/internals/contributing/coding-style-windows.rst \
Documentation/internals/contributing/documentation-style.rst \
Documentation/internals/contributing/submitting-patches.rst
# You can set these variables from the command line. # You can set these variables from the command line.
SPHINXOPTS = SPHINXOPTS =

16
Documentation/index.rst
View File

@ -57,7 +57,21 @@ The Open vSwitch Project
Learn more about the Open vSwitch project and about how you can contribute: Learn more about the Open vSwitch project and about how you can contribute:
**TODO** - **Community:** :doc:`internals/release-process` |
:doc:`internals/authors` |
:doc:`internals/mailing-lists` |
:doc:`internals/bugs` |
:doc:`internals/security`
- **Contributing:** :doc:`internals/contributing/submitting-patches` |
:doc:`internals/contributing/coding-style` |
:doc:`internals/contributing/coding-style-windows`
- **Maintaining:** :doc:`internals/maintainers` |
:doc:`internals/committer-responsibilities` |
:doc:`internals/committer-grant-revocation`
- **Documentation:** :doc:`internals/contributing/documentation-style`
Getting Help Getting Help
------------- -------------

24
Documentation/internals/authors.rst Normal file
View File

@ -0,0 +1,24 @@
..
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.
.. include:: ../../AUTHORS.rst

2
REPORTING-BUGS.rst → Documentation/internals/bugs.rst
View File

@ -31,7 +31,7 @@ they can be fixed as quickly as possible.
Please report bugs by sending email to bugs@openvswitch.org. Please report bugs by sending email to bugs@openvswitch.org.
For reporting security vulnerabilities, please read SECURITY.rst. For reporting security vulnerabilities, please read :doc:`security`.
The most important parts of your bug report are the following: The most important parts of your bug report are the following:

2
Documentation/committer-grant-revocation.rst → Documentation/internals/committer-grant-revocation.rst
View File

@ -269,7 +269,7 @@ Invitation to Accepted Committer
Developers with commit access must agree to fulfill specific Developers with commit access must agree to fulfill specific
responsibilities described in the source repository: responsibilities described in the source repository:
/Documentation/committer-responsibilities.rst /Documentation/internals/committer-responsibilities.rst
Please let us know if you would like to accept commit access and if so that Please let us know if you would like to accept commit access and if so that
you agree to fulfill these responsibilities. Once we receive your response you agree to fulfill these responsibilities. Once we receive your response

8
Documentation/committer-responsibilities.rst → Documentation/internals/committer-responsibilities.rst
View File

@ -28,8 +28,8 @@ Expectations for Developers with Open vSwitch Repo Access
Pre-requisites Pre-requisites
-------------- --------------
Be familiar with the `coding style <../../CodingStyle.rst>`__ and `contributing Be familar with the guidlines and standards defined in
<../../CONTRIBUTING.rst>`__ guides. :doc:`contributing/index`.
Review Review
------ ------
@ -88,9 +88,9 @@ bring it up on the mailing list. If you explain the use of "Signed-off-by:" to
a new developer, explain not just how but why, since the intended meaning of 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 "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 explanation, quote or provide a URL to the Developer's Certificate of Origin in
the `contributing guide <../../CONTRIBUTING.rst>`__. :doc:`contributing/submitting-patches`.
Use Reported-by: and Tested-by: tags in commit messages to indicate the Use Reported-by: and Tested-by: tags in commit messages to indicate the
source of a bug report. source of a bug report.
Keep the `AUTHORS <../../AUTHORS>`__ file up to date. Keep the ``AUTHORS.rst`` file up to date.

8
datapath-windows/CodingStyle.rst → Documentation/internals/contributing/coding-style-windows.rst
View File

@ -25,10 +25,10 @@
Open vSwitch Windows Datapath Coding Style Open vSwitch Windows Datapath Coding Style
========================================== ==========================================
The coding style described in the Open vSwitch distribution gives the The :doc:`coding style <coding-style>` guide gives the flexiblity for each
flexiblity for each platform to use its own coding style for the kernel platform to use its own coding style for the kernel datapath. This file
datapath. This file describes the specific coding style used in most of the C describes the specific coding style used in most of the C files in the Windows
files in the Windows kernel datapath of the Open vSwitch distribution. kernel datapath of the Open vSwitch distribution.
Most of the coding conventions applicable for the Open vSwitch distribution are Most of the coding conventions applicable for the Open vSwitch distribution are
applicable to the Windows kernel datapath as well. There are some exceptions applicable to the Windows kernel datapath as well. There are some exceptions

2
CodingStyle.rst → Documentation/internals/contributing/coding-style.rst
View File

@ -28,7 +28,7 @@ Open vSwitch Coding Style
This file describes the coding style used in most C files in the Open vSwitch This file describes the coding style used in most C files in the Open vSwitch
distribution. However, Linux kernel code datapath directory follows the Linux distribution. However, Linux kernel code datapath directory follows the Linux
kernel's established coding conventions. For the Windows kernel datapath code, kernel's established coding conventions. For the Windows kernel datapath code,
use the coding style described in datapath-windows/CodingStyle. use the coding style described in :doc:`coding-style-windows`.
The following GNU indent options approximate this style. The following GNU indent options approximate this style.

4
DocumentationStyle.rst → Documentation/internals/contributing/documentation-style.rst
View File

@ -47,8 +47,8 @@ reST Conventions
Basics Basics
~~~~~~ ~~~~~~
Many of the basic documentation guidelines match those of the `coding style Many of the basic documentation guidelines match those of the
guide <CodingStyle.rst>`__. :doc:`coding-style`.
- Use reStructuredText (reST) for all documentation. - Use reStructuredText (reST) for all documentation.

36
Documentation/internals/contributing/index.rst Normal file
View File

@ -0,0 +1,36 @@
..
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
============================
The below guides provide information on contributing to Open vSwitch itself.
.. toctree::
:maxdepth: 2
submitting-patches
coding-style
coding-style-windows
documentation-style

452
Documentation/internals/contributing/submitting-patches.rst Normal file
View File

@ -0,0 +1,452 @@
..
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.
==================
Submitting Patches
==================
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. Refer to 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 <n>/<m>] <area>: <summary>
Where:
``[PATCH <n>/<m>]``:
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.
``<area>``:
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.
``<summary>``:
briefly describes the change. Use the the imperative form,
e.g. "Force SNAT for multiple gateway routers." or "Fix daemon exit
for bad datapaths or flows." Try to keep the summary short, about
50 characters wide.
The subject, minus the ``[PATCH <n>/<m>]`` 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 75 characters in width. That
allows the description to format properly even when indented (e.g. by
"git log" or in email quotations).
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: <author name>
<author email>``, 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 <author.name@email.address...>``
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 <author.name@email.address...>
Signed-off-by: Submitter Name <submitter.name@email.address...>
``Co-authored-by: Author Name <author.name@email.address...>``
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 <reviewer.name@email.address...>``
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 <reviewer.name@email.address...>``
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: <URL>``
When a test report is publicly available, this provides a way to reference
it. Typical <URL>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 <reporter.name@email.address...>``
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 <requester.name@email.address...>``
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 <suggester.name@email.address...>``
See ``Requested-by:``.
``CC: Person <name@email>``
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: <URL>``
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: <URL>``
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.
See also http://developercertificate.org/.
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 <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 on `kernel.org
<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.
Follow the style used in the code that you are modifying. :doc:`coding-style`
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 <jesse@nicira.com>
Date: Thu, 8 Dec 2011 13:17:24 -0800
Subject: [PATCH] datapath: Alphabetize include/net/ipv6.h compat header.
Signed-off-by: Jesse Gross <jesse@nicira.com>
---
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

10
Documentation/internals/index.rst
View File

@ -32,3 +32,13 @@ itself and how they might involved.
.. toctree:: .. toctree::
:maxdepth: 2 :maxdepth: 2
contributing/index
mailing-lists
release-process
bugs
security
committer-responsibilities
committer-grant-revocation
authors
maintainers

96
Documentation/internals/mailing-lists.rst Normal file
View File

@ -0,0 +1,96 @@
..
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.
=============
Mailing Lists
=============
.. important::
Report security issues **only** to security@openvswitch.org. For more
information, refer to our :doc:`security policies <security>`.
ovs-announce
------------
The `ovs-announce`__ mailing list is used to announce new versions of Open
vSwitch and is extremely low-volume. `(subscribe)`__ `(archives)`__
__ ovs-announce@openvwitch.org
__ https://mail.openvswitch.org/mailman/listinfo/ovs-announce/
__ https://mail.openvswitch.org/pipermail/ovs-announce/
ovs-discuss
-----------
The `ovs-discuss`__ mailing list is used to discuss plans and design decisions
for Open vSwitch. It is also an appropriate place for user questions.
`(subscribe)`__ `(archives)`__
__ ovs-discuss@openvwitch.org
__ https://mail.openvswitch.org/mailman/listinfo/ovs-discuss/
__ https://mail.openvswitch.org/pipermail/ovs-discuss/
ovs-dev
-------
The `ovs-dev`__ mailing list is used to discuss development and review code
before being committed. `(subscribe)`__ `(archives)`__
__ ovs-dev@openvwitch.org
__ https://mail.openvswitch.org/mailman/listinfo/ovs-dev/
__ https://mail.openvswitch.org/pipermail/ovs-dev/
ovs-git
-------
The `ovs-git`__ mailing list hooks into Open vSwitch's version control system
to receive commits. `(subscribe)`__ `(archives)`__
__ ovs-git@openvwitch.org
__ https://mail.openvswitch.org/mailman/listinfo/ovs-git/
__ https://mail.openvswitch.org/pipermail/ovs-git/
ovs-build
---------
The `ovs-build`__ mailing list hooks into Open vSwitch's continuous integration
system to receive build reports. `(subscribe)`__ `(archives)`__
__ ovs-build@openvwitch.org
__ https://mail.openvswitch.org/mailman/listinfo/ovs-build/
__ https://mail.openvswitch.org/pipermail/ovs-build/
bugs
-----
The `bugs`__ mailing list is an alias for the discuss mailing list.
__ bugs@openvswitch.org
security
--------
The `security`__ mailing list is for submitting security vulnerabilities to the
security team.
__ security@ovs.org

24
Documentation/internals/maintainers.rst Normal file
View File

@ -0,0 +1,24 @@
..
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.
.. include:: ../../MAINTAINERS.rst

0
Documentation/release-process.rst → Documentation/internals/release-process.rst
View File

36
SECURITY.rst → Documentation/internals/security.rst
View File

@ -1,6 +1,29 @@
================ ..
Security Process 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.
===============================
Open vSwitch's Security Process
===============================
This is a proposed security vulnerability reporting and handling process for This is a proposed security vulnerability reporting and handling process for
Open vSwitch. It is based on the OpenStack vulnerability management process Open vSwitch. It is based on the OpenStack vulnerability management process
@ -61,8 +84,7 @@ mailing list (see contact_ at the end of this document). A security team
member should reply to the reporter acknowledging that the report has been member should reply to the reporter acknowledging that the report has been
received. received.
Consider reporting the information mentioned in `REPORTING-BUGS.rst Consider reporting the information mentioned in :doc:`bugs`, where relevant.
<REPORTING-BUGS.rst>`__, where relevant.
Reporters may ask for a GPG key while initiating contact with the security team Reporters may ask for a GPG key while initiating contact with the security team
to deliver more sensitive reports. to deliver more sensitive reports.
@ -178,8 +200,8 @@ sections for the document include:
* Patch: If a patch or patches are available, and it is practical * 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 to include them in the email, put them at the end. Format them
as described in CONTRIBUTING.rst, that is, as output by "git as described in :doc:`contributing/submitting-patches`, that is, as
format-patch". output by "git format-patch".
The patch subjects should include the version for which they are The patch subjects should include the version for which they are
suited, e.g. "[PATCH branch-2.3]" for a patch against Open suited, e.g. "[PATCH branch-2.3]" for a patch against Open

4
Makefile.am
View File

@ -68,9 +68,7 @@ PYCOV_CLEAN_FILES = build-aux/check-structs,cover
docs = \ docs = \
AUTHORS.rst \ AUTHORS.rst \
CONTRIBUTING.rst \ CONTRIBUTING.rst \
CodingStyle.rst \
DESIGN.rst \ DESIGN.rst \
DocumentationStyle.rst \
FAQ.rst \ FAQ.rst \
INSTALL.rst \ INSTALL.rst \
INSTALL.Debian.rst \ INSTALL.Debian.rst \
@ -94,8 +92,6 @@ docs = \
README.rst \ README.rst \
README-lisp.rst \ README-lisp.rst \
README-native-tunneling.rst \ README-native-tunneling.rst \
REPORTING-BUGS.rst \
SECURITY.rst \
WHY-OVS.rst WHY-OVS.rst
EXTRA_DIST = \ EXTRA_DIST = \
$(docs) \ $(docs) \

1
datapath-windows/automake.mk
View File

@ -1,5 +1,4 @@
EXTRA_DIST += \ EXTRA_DIST += \
datapath-windows/CodingStyle.rst \
datapath-windows/DESIGN.rst \ datapath-windows/DESIGN.rst \
datapath-windows/Package/package.VcxProj \ datapath-windows/Package/package.VcxProj \
datapath-windows/Package/package.VcxProj.user \ datapath-windows/Package/package.VcxProj.user \