Networking Guide: Implement Versioning¶

Problem description¶

The networking guide currently uses a continuous deployment mechanism for publication. In other words, only the master branch resides on docs.openstack.org. Several releases after initial publication of the networking guide, the following issues with continuous deployment became apparent:

• Using wording such as “In Kilo…” or “In Liberty…” is confusing and often difficult to find if a search leads to a specific page within the content for a particular feature available in a certain release of OpenStack. For example, a chapter has a note indicating that the Liberty release includes a particular feature, but sections within the chapter lack a note about it.
• Maintaining the deployment scenarios is difficult because features and configuration options change with each release. For example, DVR in Juno only supports GRE and VXLAN networks, but DVR in Kilo and newer releases also supports VLAN networks. Trying to use “In Kilo…” or “In Liberty…” in configuration snippets makes them increasingly confusing.

Proposed change¶

Publish stable releases of the networking guide with OpenStack releases. With the exception of bug fixes, patches apply to the master branch and require additional consideration for backporting to prior releases.

Stable release tags already exist for the networking guide. However, updates to the networking guide for a particular release usually occur after that release. For example, patches for the deployment scenarios in Kilo mostly merged several months after the Kilo release. Therefore, the existing stable/kilo tag primarily includes content that applies to Juno and the stable/liberty tag primarily includes content that applies to Kilo. Aligning content for prior releases requires careful backporting of a significant quantity of patches.

After implementation of this specification, updates for a future release should occur prior to that release similar to the installation guide.

Implementation¶

Dependencies¶

None.

Testing¶

• Verify correct publication prior to moving to the next phase and ultimately implementing the specification.

References¶

• Discussion can occur using any official medium including IRC in #openstack-doc, openstack-docs mailing list, weekly documentation team meeting, bi-weekly networking guide sub-team meeting, and potentially etherpads.