summaryrefslogtreecommitdiff
path: root/Documentation/internals
Commit message (Collapse)AuthorAgeFilesLines
* Documentation: Remove reference to RST online editor.David Marchand2023-01-111-4/+0
| | | | | | | | 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>
* Documentation: Fix links in maintainers.rst.Ilya Maximets2023-01-061-0/+5
| | | | | | | | | | | | | | | | | | | | | | | 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>
* travis: Drop support.David Marchand2022-12-211-4/+3
| | | | | | | | | | | | | | 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>
* Prepare for 3.0.0.Ilya Maximets2022-07-152-3/+3
| | | | | | Acked-by: Simon Horman <simon.horman@corigine.com> Acked-by: Ian Stokes <ian.stokes@intel.com> Signed-off-by: Ilya Maximets <i.maximets@ovn.org>
* Documentation: Remove kernel module documentation.Greg Rose2022-07-151-0/+7
| | | | | | | | | 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>
* Documentation: Fix use of rst verbatim code chunk syntax.Kevin Traynor2022-05-041-2/+0
| | | | | | | | | 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>
* docs: fix wrong quoteYunjian Wang2021-07-062-9/+9
| | | | | | | Remove the coma character by using ' or " character. Signed-off-by: Yunjian Wang <wangyunjian@huawei.com> Signed-off-by: Ben Pfaff <blp@ovn.org>
* Documentation: Simplify the website main page.Flavio Leitner2021-01-076-18/+18
| | | | | | | | | | | | | | | | | | | | 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>
* security.rst: Add more information about the Downstream mailing list.Justin Pettit2020-12-261-4/+7
| | | | | Signed-off-by: Justin Pettit <jpettit@ovn.org> Acked-by: Flavio Leitner <fbl@sysclose.org>
* github: Add GitHub Actions workflow.Ilya Maximets2020-11-261-5/+4
| | | | | | | | | | | | | | | | | | | | | | | | 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>
* release-process: Policy for unmaintained branches.Ilya Maximets2020-11-102-1/+11
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | 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>
* release-process: Standardize designation of new LTS releases.Ilya Maximets2020-11-101-6/+26
| | | | | | | | | | | | | | | | | | | 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>
* release-process: Add transition period for LTS releases.Ilya Maximets2020-11-101-4/+7
| | | | | | | | | | | | | | | | | | | | | | | 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>
* release-process: Fix indentation.Ben Pfaff2020-03-061-1/+1
| | | | Signed-off-by: Ben Pfaff <blp@ovn.org>
* release-process: Describe how to branch and how to make a release.Ben Pfaff2020-03-061-0/+57
| | | | | Acked-by: Justin Pettit <jpettit@ovn.org> Signed-off-by: Ben Pfaff <blp@ovn.org>
* docs: Correct links in mailing-lists.rstLars Kellogg-Stedman2020-01-151-7/+7
| | | | | | | | | | 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>
* Documentation: Document a useful pre-push hook for committers.Ben Pfaff2019-10-011-0/+50
| | | | | | | | 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>
* Documentation: Fix security mailing list address.Ben Pfaff2019-09-231-1/+1
| | | | | | | | 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>
* coding-style: Few visual enhancements for the document.Ilya Maximets2018-11-161-50/+50
| | | | | | | | 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>
* coding-style: Remove redundant symbols from the examples.Ilya Maximets2018-11-151-2/+2
| | | | | | | | | | | 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>
* contributing: Signed-off-by tags should come last.Ben Pfaff2018-10-311-0/+6
| | | | | | | Acked-by: Flavio Leitner <fbl@sysclose.org> Reviewed-by: Greg Rose <gvrose8192@gmail.com> Suggested-by: Gregory Rose <gvrose8192@gmail.com> Signed-off-by: Ben Pfaff <blp@ovn.org>
* submitting-patches: Advise not to wrap tags across multiple lines.Ben Pfaff2018-10-311-0/+3
| | | | | | | | 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>
* release-process.rst: Add "soft freeze" stage.Ben Pfaff2018-07-311-39/+49
| | | | | | | | | | 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>
* docs: Fix sphinx urls.Ian Stokes2018-04-211-1/+2
| | | | | | | | | | | 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>
* docs: Fix style guide url in DocumentationStyle.rst.Ian Stokes2018-04-211-2/+2
| | | | | | | | | | | 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>
* Clean up some minor spelling and typos.Justin Pettit2018-03-145-11/+11
| | | | | Signed-off-by: Justin Pettit <jpettit@ovn.org> Acked-by: Ben Pfaff <blp@ovn.org>
* doc: Fix mailing list addresses.Jakub Sitnicki2018-01-091-5/+5
| | | | | | | Correct typo in the email domain. Signed-off-by: Jakub Sitnicki <jkbs@redhat.com> Signed-off-by: Ben Pfaff <blp@ovn.org>
* coding-style: Remove caveats about mixing statements and declarations.Ben Pfaff2017-12-221-3/+2
| | | | | | | | | | OVS practice has evolved over time to mix code and data more freely. See also: https://mail.openvswitch.org/pipermail/ovs-dev/2017-November/341032.html Signed-off-by: Ben Pfaff <blp@ovn.org> Acked-by: Justin Pettit <jpettit@ovn.org>
* coding-style: Explain when to break lines before or after binary operators.Ben Pfaff2017-12-041-21/+31
| | | | | | | | | | | | 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>
* Update mailing list archive pointers to the current server.Justin Pettit2017-11-272-2/+2
| | | | | Signed-off-by: Justin Pettit <jpettit@ovn.org> Acked-by: Ben Pfaff <blp@ovn.org>
* Documentation: Add the Open vSwitch project charter.Ben Pfaff2017-11-022-0/+205
| | | | | | | | 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>
* Introduce Emeritus Committer status.Russell Bryant2017-10-273-59/+68
| | | | | | | | | | | | | | | | | | | | | | | 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>
* docs: Add references to git-pwStephen Finucane2017-09-281-14/+37
| | | | | | | | | | | 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>
* submitting-patches: Update test and documentation recommendations.Ben Pfaff2017-07-131-15/+15
| | | | | | | | | | | | | | | | | 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>
* coding-style: Fix typo.Ben Pfaff2017-05-191-1/+1
| | | | | Signed-off-by: Ben Pfaff <blp@ovn.org> Acked-by: Greg Rose <gvrose8192@gmail.com>
* libopenvswitch: Rename to libfoo-X.Y.Joe Stringer2017-05-171-7/+9
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | 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>
* doc: Convert ovs-vlan-test to rSTStephen Finucane2017-04-211-1/+2
| | | | | | | | | | | | | | | 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>
* doc: Add man page section to documentation guideStephen Finucane2017-04-211-8/+76
| | | | | | | We also replace 'reST' with the far more common 'rST'. Signed-off-by: Stephen Finucane <stephen@that.guru> Signed-off-by: Ben Pfaff <blp@ovn.org>
* doc: Describe how docs.openvswitch.org worksStephen Finucane2017-04-063-0/+85
| | | | | Signed-off-by: Stephen Finucane <stephen@that.guru> Signed-off-by: Russell Bryant <russell@ovn.org>
* Documentation: fix typo in documentation-style.rstTimothy Redaelli2017-03-291-1/+1
| | | | | | | s/indenation/indentation/ Signed-off-by: Timothy Redaelli <tredaelli@redhat.com> Signed-off-by: Ben Pfaff <blp@ovn.org>
* Documentation: Remove external dependence on pygments.Ilya Maximets2017-03-171-4/+6
| | | | | | | | | | | | | | 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>
* doc: Describe backporting process.Joe Stringer2017-02-212-0/+237
| | | | | | | | | | | | 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>
* libX: add new release / version info tagsAaron Conole2017-01-183-0/+124
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | 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>
* docs: Fix formatting of patch comments line.Joe Stringer2017-01-051-1/+1
| | | | | | | | | | 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>
* docs: Resolve broken URLsStephen Finucane2016-12-234-13/+14
| | | | | | | | 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>
* doc: Minor formatting fixes to documentation-styleStephen Finucane2016-12-221-8/+11
| | | | | Signed-off-by: Stephen Finucane <stephen@that.guru> Signed-off-by: Ben Pfaff <blp@ovn.org>
* doc: Recommend compressed PNG images where possibleStephen Finucane2016-12-221-3/+12
| | | | | | | | 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>
* doc: Document Patchwork instanceStephen Finucane2016-12-212-0/+62
| | | | | | | I know more than a little bit about this :) Signed-off-by: Stephen Finucane <stephen@that.guru> Signed-off-by: Ben Pfaff <blp@ovn.org>
* doc: Misc fixes to 'documentation-style'Stephen Finucane2016-12-211-9/+9
| | | | | | | | 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>
* doc: Add some useful tools for doc editingStephen Finucane2016-12-211-3/+26
| | | | | | | This has come up on the mailing list. Let's document it! Signed-off-by: Stephen Finucane <stephen@that.guru> Signed-off-by: Ben Pfaff <blp@ovn.org>
View Lorry Controller Status