mirror of
https://github.com/openvswitch/ovs
synced 2025-08-22 01:51:26 +00:00
doc: Populate 'internals' section
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
Ben Pfaff
parent
4f6ec357cd
commit
d0e53b1532
430
CONTRIBUTING.rst
430
CONTRIBUTING.rst
@ -25,428 +25,10 @@
|
||||
Contributing to Open vSwitch
|
||||
============================
|
||||
|
||||
Send changes to Open vSwitch as patches to dev@openvswitch.org. One patch per
|
||||
email. More details are included below.
|
||||
As an open source project, we welcome contributions of any kind. These can
|
||||
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
|
||||
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 <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
|
||||
Extensive guidelines are provided in the docs at
|
||||
``docs/internals/contributing``, or `online
|
||||
<https://docs.openvswitch.org/en/dev/internals/contributing>`__.
|
||||
|
||||
@ -1,9 +1,6 @@
|
||||
docs += \
|
||||
Documentation/committer-responsibilities.rst \
|
||||
Documentation/committer-grant-revocation.rst \
|
||||
Documentation/group-selection-method-property.txt \
|
||||
Documentation/OVSDB-replication.rst \
|
||||
Documentation/release-process.rst
|
||||
Documentation/OVSDB-replication.rst
|
||||
|
||||
EXTRA_DIST += \
|
||||
Documentation/_static/logo.png \
|
||||
@ -17,7 +14,20 @@ EXTRA_DIST += \
|
||||
Documentation/howto/index.rst \
|
||||
Documentation/ref/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.
|
||||
SPHINXOPTS =
|
||||
|
||||
@ -57,7 +57,21 @@ The Open vSwitch Project
|
||||
|
||||
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
|
||||
-------------
|
||||
|
||||
24
Documentation/internals/authors.rst
Normal file
24
Documentation/internals/authors.rst
Normal 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
|
||||
@ -31,7 +31,7 @@ they can be fixed as quickly as possible.
|
||||
|
||||
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:
|
||||
|
||||
@ -269,7 +269,7 @@ Invitation to Accepted Committer
|
||||
Developers with commit access must agree to fulfill specific
|
||||
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
|
||||
you agree to fulfill these responsibilities. Once we receive your response
|
||||
@ -28,8 +28,8 @@ Expectations for Developers with Open vSwitch Repo Access
|
||||
Pre-requisites
|
||||
--------------
|
||||
|
||||
Be familiar with the `coding style <../../CodingStyle.rst>`__ and `contributing
|
||||
<../../CONTRIBUTING.rst>`__ guides.
|
||||
Be familar with the guidlines and standards defined in
|
||||
:doc:`contributing/index`.
|
||||
|
||||
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
|
||||
"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
|
||||
the `contributing guide <../../CONTRIBUTING.rst>`__.
|
||||
:doc:`contributing/submitting-patches`.
|
||||
|
||||
Use Reported-by: and Tested-by: tags in commit messages to indicate the
|
||||
source of a bug report.
|
||||
|
||||
Keep the `AUTHORS <../../AUTHORS>`__ file up to date.
|
||||
Keep the ``AUTHORS.rst`` file up to date.
|
||||
@ -25,10 +25,10 @@
|
||||
Open vSwitch Windows Datapath Coding Style
|
||||
==========================================
|
||||
|
||||
The coding style described in the Open vSwitch distribution gives the
|
||||
flexiblity for each platform to use its own coding style for the kernel
|
||||
datapath. This file describes the specific coding style used in most of the C
|
||||
files in the Windows kernel datapath of the Open vSwitch distribution.
|
||||
The :doc:`coding style <coding-style>` guide gives the flexiblity for each
|
||||
platform to use its own coding style for the kernel datapath. This file
|
||||
describes the specific coding style used in most of the C files in the Windows
|
||||
kernel datapath of the Open vSwitch distribution.
|
||||
|
||||
Most of the coding conventions applicable for the Open vSwitch distribution are
|
||||
applicable to the Windows kernel datapath as well. There are some exceptions
|
||||
@ -28,7 +28,7 @@ Open vSwitch Coding Style
|
||||
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
|
||||
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.
|
||||
|
||||
@ -47,8 +47,8 @@ reST Conventions
|
||||
Basics
|
||||
~~~~~~
|
||||
|
||||
Many of the basic documentation guidelines match those of the `coding style
|
||||
guide <CodingStyle.rst>`__.
|
||||
Many of the basic documentation guidelines match those of the
|
||||
:doc:`coding-style`.
|
||||
|
||||
- Use reStructuredText (reST) for all documentation.
|
||||
|
||||
36
Documentation/internals/contributing/index.rst
Normal file
36
Documentation/internals/contributing/index.rst
Normal 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
452
Documentation/internals/contributing/submitting-patches.rst
Normal 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
|
||||
@ -32,3 +32,13 @@ itself and how they might involved.
|
||||
|
||||
.. toctree::
|
||||
: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
96
Documentation/internals/mailing-lists.rst
Normal 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
24
Documentation/internals/maintainers.rst
Normal 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
|
||||
@ -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
|
||||
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
|
||||
received.
|
||||
|
||||
Consider reporting the information mentioned in `REPORTING-BUGS.rst
|
||||
<REPORTING-BUGS.rst>`__, where relevant.
|
||||
Consider reporting the information mentioned in :doc:`bugs`, where relevant.
|
||||
|
||||
Reporters may ask for a GPG key while initiating contact with the security team
|
||||
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
|
||||
to include them in the email, put them at the end. Format them
|
||||
as described in CONTRIBUTING.rst, that is, as output by "git
|
||||
format-patch".
|
||||
as described in :doc:`contributing/submitting-patches`, that is, as
|
||||
output by "git format-patch".
|
||||
|
||||
The patch subjects should include the version for which they are
|
||||
suited, e.g. "[PATCH branch-2.3]" for a patch against Open
|
||||
@ -68,9 +68,7 @@ PYCOV_CLEAN_FILES = build-aux/check-structs,cover
|
||||
docs = \
|
||||
AUTHORS.rst \
|
||||
CONTRIBUTING.rst \
|
||||
CodingStyle.rst \
|
||||
DESIGN.rst \
|
||||
DocumentationStyle.rst \
|
||||
FAQ.rst \
|
||||
INSTALL.rst \
|
||||
INSTALL.Debian.rst \
|
||||
@ -94,8 +92,6 @@ docs = \
|
||||
README.rst \
|
||||
README-lisp.rst \
|
||||
README-native-tunneling.rst \
|
||||
REPORTING-BUGS.rst \
|
||||
SECURITY.rst \
|
||||
WHY-OVS.rst
|
||||
EXTRA_DIST = \
|
||||
$(docs) \
|
||||
|
||||
@ -1,5 +1,4 @@
|
||||
EXTRA_DIST += \
|
||||
datapath-windows/CodingStyle.rst \
|
||||
datapath-windows/DESIGN.rst \
|
||||
datapath-windows/Package/package.VcxProj \
|
||||
datapath-windows/Package/package.VcxProj.user \
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user