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>
These were found using the 'linkcheck' builder.
Signed-off-by: Stephen Finucane <stephen@that.guru>
Cc: Ben Pfaff <blp@ovn.org>
Signed-off-by: Ben Pfaff <blp@ovn.org>
ASCII images take up less space but are significantly less readable than
proper images.
Signed-off-by: Stephen Finucane <stephen@that.guru>
Signed-off-by: Ben Pfaff <blp@ovn.org>
The table headers are unnecessary and make the doc harder to read, while
the headers guide was not displaying very well.
Signed-off-by: Stephen Finucane <stephen@that.guru>
Signed-off-by: Ben Pfaff <blp@ovn.org>
