Recently OVS adopted a policy of using the inclusive naming word list v1
[1, 2].
In keeping with this policy rename the primary development branch from
'master' to 'main'. This patch does not actually make that change, but
rather updates references to the branch in documentation in the source
tree. It is intended to be applied at (approximately) the same time
that the change is made.
OVS is currently hosted on GitHub. We can expect the following behaviour
after the rename:
1. GitHub pull requests against are renamed branch are automatically
re-homed on new branch
2. GitHub Issues do not seem to be affected - at least the test issue I
created had no association with a branch
3. URLs accessed via the GitHub web UI are automatically renamed
(so long as a new branch called master is not created).
4. Using the git cli command, fetch will fetch the new branch (main),
and fetch -p will remove (prune) the old branch (master)
[1] df5e5cf4318a ("Documentation: Add section on inclusive language.")
[2] https://inclusivenaming.org/word-lists/
Signed-off-by: Simon Horman <horms@ovn.org>
Acked-by: Eelco Chaudron <echaudro@redhat.com>
Acked-by: Aaron Conole <aconole@redhat.com>
Acked-by: Ilya Maximets <i.maximets@ovn.org>
---
Notes:
* Now is the time to raise any concerns regarding this patch.
It is planned to implement this change next week.
* If you have an automation that fetches the master branch then
the suggested action is:
1. Before the branch rename occurs: update the automation to pull main an
fall back to pulling master if that fails
2. After the rename occurs: Update the automation to only fetch main
* After the change it may be necessary to update your local
git configuration for checked out branches.
For example:
# Fetch origin: new remote main branch; remote master branch is deleted
git fetch -tp origin
# Rename local branch
git branch -m master main
# Update local main branch to use remote main branch as it's upstream
git branch --set-upstream-to=origin/main main
* As a follow-up, after the rename, I plan to post a patch which removes
references to master in CI jobs
The Kernel datapath is no longer present in the primary development
branch of the OVS tree. Update documentation to more clearly reflect
this.
Documentation relating to the kernel datapath in the OVS tree can
be removed once 2.17 is EOL.
Also, update wording of affected text as there is more than one upstream
networking maintainer these days.
Signed-off-by: Simon Horman <horms@ovn.org>
Acked-by: Ilya Maximets <i.maximets@ovn.org>
Recently OVS adopted a policy of using the inclusive naming word list v1
[1, 2].
This patch addresses the use of the term master repository by
using the term main repository instead.
This is as distinct from addressing the use of a master branch,
which remains as a follow-up task.
[1] df5e5cf ("Documentation: Add section on inclusive language.")
[2] https://inclusivenaming.org/word-lists/
Signed-off-by: Simon Horman <horms@ovn.org>
Acked-by: Kevin Traynor <ktraynor@redhat.com>
Acked-by: Eelco Chaudron <echaudro@redhat.com>
This updates links to several upstream Kernel documents.
1. Lore is now the canonical archive for the netdev mailing list
2. net-next is now maintained by the netdev team,
of which David Miller is currently a member,
rather than only by David.
Also, use HTTPS rather than HTTP.
3. The Netdev FAQ has evolved into the Netdev Maintainer Handbook.
4. The Kernel security document link was dead,
provide the current canonical location for this document instead.
1., 2. & 3. Found by inspection
4. Flagged by check-docs
Signed-off-by: Simon Horman <horms@ovn.org>
Acked-by: Mike Pattrick <mkp@redhat.com>
Acked-by: Eelco Chaudron <echaudro@redhat.com>
As a community we should strive to be inclusive.
As such it seems appropriate to adopt an word list,
to help guide the use of inclusive language.
This patch proposes use of the Inclusive Naming Word List v1.0.
Link: https://inclusivenaming.org/word-lists/
Signed-off-by: Simon Horman <horms@ovn.org>
Acked-by: Eelco Chaudron <echaudro@redhat.com>
Acked-by: Aaron Conole <aconole@redhat.com>
It is an example and the dates are not set in stone, so updating
the table it is not very important. But it's nice to see currently
supported releases there as well as the near future plans.
Acked-by: Kevin Traynor <ktraynor@redhat.com>
Acked-by: Simon Horman <horms@ovn.org>
Acked-by: Eelco Chaudron <echaudro@redhat.com>
Signed-off-by: Ilya Maximets <i.maximets@ovn.org>
rst.ninjs.org is not available anymore, but there are alternatives
listed in this doc.
Signed-off-by: David Marchand <david.marchand@redhat.com>
Signed-off-by: Ilya Maximets <i.maximets@ovn.org>
GitHub and Sphinx are parsing links differently. Sphinx knows about
the overall documentation structure and all the sections defined in
other docs, while GitHub is using direct rst 2 html conversion and
doesn't know any of that. Sphinx wants links to sections in other
docs to be defined with a :doc: field, but GitHub can't parse that
and requires having a direct link to the other rST document.
The problem is that we have a top level MAINTAINERS.rst, that should
be parseable by GitHub, included in the maintainers.rst in the
main documentation section that is used by Sphinx to generate html,
pdf and other docs. So, it's hard to make links work in both.
Working around that limitation by using rST substitutions for the
links. Cutting off the substitutions for actual links and adding
:doc: links instead during the file inclusion for Sphinx.
Reported-by: Igor Zhukov <ivzhukov@sbercloud.ru>
Acked-by: Han Zhou <hzhou@ovn.org>
Acked-by: Eelco Chaudron <echaudro@redhat.com>
Signed-off-by: Ilya Maximets <i.maximets@ovn.org>
Following a change in the terms of use, free Travis credits are really
too low for a realistic usage by OVS contributors.
As a consequence, testing OVS with Travis has been abandoned by most
(if not all) contributors to the project.
Drop the Travis configuration from our repository, clean references in
the documentation and move GHA specifics to the association yml.
Acked-by: Aaron Conole <aconole@redhat.com>
Signed-off-by: David Marchand <david.marchand@redhat.com>
Signed-off-by: Ilya Maximets <i.maximets@ovn.org>
As of Open vSwitch release 2.18 the OVS kernel module is no longer
supported. Pull the documentation references.
Reviewed-by: David Marchand <david.marchand@redhat.com>
Signed-off-by: Greg Rose <gvrose8192@gmail.com>
Signed-off-by: Ilya Maximets <i.maximets@ovn.org>
In some places it is using Markdown syntax and in others
it is not needed as there is already a code block.
Signed-off-by: Kevin Traynor <ktraynor@redhat.com>
Reviewed-by: David Marchand <david.marchand@redhat.com>
Signed-off-by: Ilya Maximets <i.maximets@ovn.org>
The initial website page is difficult to read because of
the large amount of links from different parts of the whole
documentation. Most of all those links come from their
index page referenced in the section 'Contents' on the side.
Another issue is that because the page is static, new links
might not get included.
This patch simplifies the main page by highlighting the project
level documentation. The static part is reduced to the main
level index pages.
All the links are available by clicking on 'Full Table of
Contents' at the end of Documentation section.
Signed-off-by: Flavio Leitner <fbl@sysclose.org>
Signed-off-by: Ben Pfaff <blp@ovn.org>
This is an initial version of GitHub Actions support. It mostly
mimics our current Travis CI build matrix with slight differences.
The main issue is that we don't have ARM support here.
Minor difference that we can not install 32-bit versions of libunwind
and libunbound since those are not avaialble in repository.
Higher concurrency level allows to finish all tests less than in 20
minutes. Which is 3 times faster than in Travis.
.travis folder renamed to .ci to highlight that it used not only for
Travis CI. Travis CI support will be reduced to only test ARM builds
soon and will be completely removed when travis-ci.org will be turned
into read-only mode.
What happened to Travis CI:
https://mail.openvswitch.org/pipermail/ovs-dev/2020-November/377773.html
Acked-by: Simon Horman <simon.horman@netronome.com>
Signed-off-by: Ilya Maximets <i.maximets@ovn.org>
While only 2 branches are formally maintained (LTS and latest release),
OVS team usually provides stable releases for other branches too, at
least for branches between LTS and latest.
When transition period ends for an old LTS, we, according to
backporting-patches.rst, could stop backporting bug fixes to branches
older than new LTS. While this might be OK for an upstream project
it doesn't sound like a user-friendly policy just because it means
that we're dropping support for branches released less than a year
ago.
Below addition to the release process might make the process a bit
smoother in terms that we will not drop support for not so old branches
even after the transition period, if committers will follow the
"as far as it goes" backporting policy. And we will provide stable
releases for these branches for at least 2 years (these releases could
be less frequent than releases on LTS branches).
After 2 year period (4 releases) committers are still free to backport
fixes they think are needed on older branches, however we will likely
not provide actual releases on these branches, unless it's specially
requested and discussed.
Additionally, "4 releases" policy aligns with the DPDK LTS support
policy, i.e. we will be able to validate and release last OVS releases
with the last available DPDK LTS, e.g. OVS 2.11 last stable release
will likely be released with the 18.11 EOL release validated.
Signed-off-by: Ilya Maximets <i.maximets@ovn.org>
Acked-by: Flavio Leitner <fbl@sysclose.org>
Acked-by: Kevin Traynor <ktraynor@redhat.com>
Standardize that we will mark a new release as LTS every two years
to avoid situation where we have a really old LTS branch that no-one
actually uses, but we have to support and provide releases for it.
This will also make release process more predictable, so users will
be able to rely on it and plan their upgrades accordingly.
As a bonus, 2 years support cycle kind of aligns with 2 years support
cycle of DPDK LTS releases.
Still keeping a window for us to discuss and avoid marking some
particular release as LTS in case of significant issues with it.
Signed-off-by: Ilya Maximets <i.maximets@ovn.org>
Acked-by: Flavio Leitner <fbl@sysclose.org>
Acked-by: Kevin Traynor <ktraynor@redhat.com>
While LTS change happens, according to release-process.rst, we're
immediately dropping support for the old LTS and, according to
backporting-patches.rst could stop backporting bug fixes to branches
older than new LTS. While this might be OK for an upstream project
(some upstream projects like QEMU doesn't support anything at all
except the last release) it doesn't sound like a user-friendly policy.
Below addition to the release process might make the process a bit
smoother in terms that we will continue support of branches a little
bit longer even after changing current LTS, i.e. providing at least a
minimal transition period (1 release frame) for users of old LTS.
Effectively, this change means that we will support branch-2.5 until
2.15 release, i.e. we will provide the last release, if any, on
branch-2.5 somewhere around Feb 2021. (I don't actually expect many
fixes there)
Signed-off-by: Ilya Maximets <i.maximets@ovn.org>
Acked-by: Flavio Leitner <fbl@sysclose.org>
Acked-by: Kevin Traynor <ktraynor@redhat.com>
Adds `mailto:` to email address links in mailing-lists.rst. The
existing syntax resulted in broken links of the form
`http://docs.openvswitch.org/en/latest/internals/mailing-lists/<address>`,
which would result in a 404 error.
Signed-off-by: Lars Kellogg-Stedman <lars@redhat.com>
Signed-off-by: Ben Pfaff <blp@ovn.org>
Someone else wrote this script originally, I think, but I've extended
it quite a bit.
Reviewed-by: Simon Horman <simon.horman@netronome.com>
Signed-off-by: Ben Pfaff <blp@ovn.org>
We don't own ovs.org, and I doubt Ojai Valley School would enjoy
receiving our email.
Reviewed-by: Greg Rose <gvrose8192@gmail.com>
Signed-off-by: Ben Pfaff <blp@ovn.org>
Some keywords and numbers highlighted. Added few spaces to
the examples.
Signed-off-by: Ilya Maximets <i.maximets@samsung.com>
Signed-off-by: Ben Pfaff <blp@ovn.org>
Some backslashes was added while converting from .md to .rst.
These symbols are printable in both pdf and html docs and
should be removed.
CC: Stephen Finucane <stephen@that.guru>
Fixes: d124a408a4bc ("doc: Convert CodingStyle to rST")
Signed-off-by: Ilya Maximets <i.maximets@samsung.com>
Signed-off-by: Ben Pfaff <blp@ovn.org>
It makes parsing them more difficult.
Acked-by: Flavio Leitner <fbl@sysclose.org>
Reviewed-by: Greg Rose <gvrose8192@gmail.com>
Signed-off-by: Ben Pfaff <blp@ovn.org>
The last few OVS releases have included a "soft freeze" stage in the
release process, but this stage has never been formalized in the
documentation. This adds a description.
Signed-off-by: Ben Pfaff <blp@ovn.org>
Acked-by: Ian Stokes <ian.stokes@intel.com>
Signed-off-by: Ben Pfaff <blp@ovn.org>
Update dead url links for sphinx documentation to avoid
make check-docs failing.
Cc: Stephen Finucane <stephen@that.guru>
Fixes: 26ea2d409 ("docs: Add writing guide")
Fixes: 73c76b447 ("doc: Add info on building documentation")
Signed-off-by: Ian Stokes <ian.stokes@intel.com>
Acked-by: Stephen Finucane <stephen@that.guru>
The link used for IBM Style Guide is no longer valid. As there is no
longer a valid link via redbooks remove the url to avoid make
check-docs failing.
Cc: Stephen Finucane <stephen@that.guru>
Fixes: 26ea2d409 ("docs: Add writing guide")
Signed-off-by: Ian Stokes <ian.stokes@intel.com>
Acked-by: Stephen Finucane <stephen@that.guru>
The coding style has never been explicit about this. This commit adds some
explanation of why one position or the other might be favored in a given
situation.
Suggested-by: Flavio Leitner <fbl@sysclose.org>
Suggested-at: https://mail.openvswitch.org/pipermail/ovs-dev/2017-November/341091.html
Signed-off-by: Ben Pfaff <blp@ovn.org>
Acked-by: Flavio Leitner <fbl@sysclose.org>
Acked-by: Tiago Lam <tiagolam@gmail.com>
It always seems odd that this isn't in the repo, so this adds it, with
internal links properly directed.
Signed-off-by: Ben Pfaff <blp@ovn.org>
Acked-by: Mark Michelson <mmichels@redhat.com>
This patch introduces an Emeritus status for OVS committers. An
Emeritus Committer is recognized as having made a significant impact
to the project and having been a committer in the past. It is
intended as an option for those that do not currently have the time or
interest to fulfill committer responsibilities based on their current
responsibilities. While in this status, they are not included in
voting for governance purposes.
An emeritus committer may be re-instated as a full committer at any
time.
The OVS committers voted approval of this change.
See documentation contents for full details.
Suggested-by: Ethan J. Jackson <ejj@eecs.berkeley.edu>
Acked-by: Justin Pettit <jpettit@ovn.org>
Acked-by: Ethan J. Jackson <ethan@kelda.io>
Signed-off-by: Russell Bryant <russell@ovn.org>
Signed-off-by: Ben Pfaff <blp@ovn.org>
Now that Patchwork 2.0 is out, folks can start to take advantage of some
of the new features that it offers. Chief among these is series support,
which is only exposed via the web UI and new REST API and which, in
turn, necessitates using git-pw rather than pwclient. As such, this tool
is slightly documented.
Signed-off-by: Stephen Finucane <stephen@that.guru>
Signed-off-by: Ben Pfaff <blp@ovn.org>
Rationale:
- "make distcheck" is not as necessary anymore because we have a build-time
check that fails if files in the repository are not distributed.
- xenserver has not been important for years, so remove the specific
callout.
- We already have an informal custom of adding tests for new feaures and
bug fixes, so codify it.
- Add note about updating NEWS.
Signed-off-by: Ben Pfaff <blp@ovn.org>
The current intent for Open vSwitch is to maintain libopenvswitch ABI
stability for minor versions, for example each release within the 2.7.z
series. According to the following documentation, no changes to exported
headers should be made.
http://docs.openvswitch.org/en/latest/internals/contributing/libopenvswitch-abi/
However, it is occasionally necessary to make changes to
{include/openvswitch,lib}/*.h headers to fix issues within a given
release series. The current libtool tagging mechanism in the build
system does not allow for this without creating a conflict between the
libtool 'current' version and the next minor release of OVS.
This patch modifies libopenvswitch build to include the MAJOR.MINOR
release version in the libX name, and include the libtool CURRENT and
OVS MICRO release in the libtool versioning tags to indicate library
stability. The resulting format is "libfoo-X.Y.so.CURRENT.0.Z" for OVS
release "X.Y.Z".
Developers should still attempt to avoid introducing ABI-breaking changes
within a particular OVS-X.Y release series, but if this is not possible
this patch introduced a mechanism to allow an ABI-breaking fix to be
introduced. In such a case, developers may update the libtool CURRENT
version to indicate this breakage to library users.
Signed-off-by: Joe Stringer <joe@ovn.org>
Acked-by: Ben Pfaff <blp@ovn.org>
Let's start with a simple one that lets us focus on setting up most of
the required "infrastructure" for building man pages using Sphinx.
This changes the 'check-htmldocs' target to 'check-docs' as its now
responsible for building man page docs too.
Other than that, hurrah for (mostly) legible syntaxes.
[1] http://www.tldp.org/HOWTO/Man-Page/q2.html
Signed-off-by: Stephen Finucane <stephen@that.guru>
Signed-off-by: Ben Pfaff <blp@ovn.org>
Current documentation uses syntax highlighting in 'sphinx'
via 'pygments' library. This leads to build failures on the
systems with old version of this library.
In fact that only 'windows.rst' uses highlighting it's a
very simple change. This helps us to avoid build issues
on different systems and allows to remove painful external
dependency.
Signed-off-by: Ilya Maximets <i.maximets@samsung.com>
Signed-off-by: Ben Pfaff <blp@ovn.org>
This patch documents the backporting process, and provides a walkthrough
for developers who would like to backport upstream Linux patches into
the Open vSwitch tree. Nothing in this documentation should be
surprising or new; it merely puts the existing process into words.
Signed-off-by: Joe Stringer <joe@ovn.org>
Acked-by: Ben Pfaff <blp@ovn.org>
Acked-by: Jarno Rajahalme <jarno@ovn.org>
Acked-by: Stephen Finucane <stephen@that.guru>
This commit uses the $PACKAGE_VERSION automake variable to construct a
release and version info combination which sets the library name to be:
libfoo-$(OVS_MAJOR_VERSION).so.$(OVS_MINOR_VERSION).0.$(OVS_MICRO_VERSION)
where formerly, it was always:
libfoo.so.1.0.0
This allows releases of Open vSwitch libraries to reflect which specific
versions they came with, and sets up a psuedo ABI-versioning scheme. In
this fashion, future releases of Open vSwitch could be installed
alongside older releases, allowing 3rd party utilities linked against
previous versions to continue to function.
ex:
$ ldd /path/to/utility
linux-vdso.so.1 (0x00007ffe92cf6000)
libopenvswitch-2.so.6 => /lib64/libopenvswitch-2.so.6 (0x00007f733b7a3000)
libssl.so.10 => /lib64/libssl.so.10 (0x00007f733b530000)
...
Note the library name and version information.
Signed-off-by: Aaron Conole <aconole@redhat.com>
Signed-off-by: Ben Pfaff <blp@ovn.org>
Sphinx was formatting the `---` as an extended dash, not verbatim as
three hyphens (which is what is necessary for git to determine that it's
a comment, and ignore it when applying the patch).
Signed-off-by: Joe Stringer <joe@ovn.org>
Acked-by: Ben Pfaff <blp@ovn.org>
Acked-by: Stephen Finucane <stephen@that.guru>
