From c0998744231bd0d6c37e8bb189e4123a059e3a0e Mon Sep 17 00:00:00 2001 From: Alexandra Settle Date: Wed, 30 Nov 2016 14:14:47 +0000 Subject: [PATCH] [contrib-guide] Adding vendor specific info Documenting this in the contrib guide is important as there is a lot of vendor content coming in. Reference: http://specs.openstack.org/openstack/docs-specs/specs/kilo/move-driver-docs.html Change-Id: I0a67a46a2ddb8eca8b200d02bfbf6c2c550e72e0 --- .../source/vendor-drivers.rst | 97 +++++++++++++++++++ doc/contributor-guide/source/writing-docs.rst | 1 + 2 files changed, 98 insertions(+) create mode 100644 doc/contributor-guide/source/vendor-drivers.rst diff --git a/doc/contributor-guide/source/vendor-drivers.rst b/doc/contributor-guide/source/vendor-drivers.rst new file mode 100644 index 0000000000..9a0aeade80 --- /dev/null +++ b/doc/contributor-guide/source/vendor-drivers.rst @@ -0,0 +1,97 @@ +======================= +Proprietary driver docs +======================= + +Many OpenStack projects include drivers to support specific hardware or +software. Examples are: + +* Cinder: block storage drivers +* Neutron: network plug-ins +* Nova: hypervisors +* Trove: different databases + +The documentation team documents the following reference drivers in the +Configuration Reference Guide: + +* For cinder: volume drivers - document LVM and NFS, backup drivers - document + swift +* For glance: document local storage, cinder, and swift as back ends +* For neutron: document ML2 plug-in with the mechanisms drivers Open vSwitch + and Linux bridge +* For nova: document KVM (mostly), send Xen open source call for help +* For sahara: Apache Hadoop +* For trove: document all supported Open Source database engines like MySQL. + +If a vendor wants to document their driver, they are invited - but not forced - +to include their documentation in the Configuration Reference if they commit +to maintain the documentation. + +.. important:: + + Other documentation (including the Cloud Admin Guide and Networking + Guide) will not contain content for third-party drivers. In these books, + where third party drivers exist, add the statement: + “For other drivers, see Chapter X in the Configuration Reference Guide”. + +Guidelines +~~~~~~~~~~ + +The following are guidelines for drivers documented by the OpenStack community: + +* The complete solution must be open source and use standard hardware +* The driver must be part of the respective OpenStack repository +* The driver is considered one of the reference drivers + +For documentation of other drivers, the following guidelines apply: + +* The Configuration Reference contains a small section for each driver, + see below for details. +* Only drivers are covered that are contained in the official OpenStack + project repository for drivers (for example in the main project repository or + the official third-party repository). + +If a vendor wants to add more than the minimal documentation, they need to +commit to the following guidelines: + +* Assign an editor that is responsible for the content. +* Review and, if necessary, update their driver for each release cycle. + +Default section format for external drivers +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +For each external driver, the driver is briefly documented in a way that +is version independent and includes the current configuration options. + +Each section should follow this format: + +* A short paragraph explaining the driver. +* A link with detailed instructions to the vendor site (if there is one). +* A default paragraph, for example: + + .. code-block:: ini + + Set the following in your ``cinder.conf``, and use the following options + to configure it. + + volume_driver = cinder.volume.drivers.smbfs.SmbfsDriver + +* And finally, the autogenerated configuration options. + +Driver vendors can send in patches for these, or create bugs. + +Full documentation by vendors +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If a vendor wants full documentation in the Configuration Reference, they +have to add to the `wiki page `_ +a contact editor that will take care of the +vendor driver documentation. The Documentation team will assign bugs to the +contact person, include the contact person in reviews for the vendor driver, +and expects timely responses. + +If vendor driver documentation becomes outdated and the contact person is not +reacting to requests, the Documentation team will change the full documentation +to a minimal version. + +The documentation team will review vendor drivers and ensure that the various +driver documents follow a consistent standard. diff --git a/doc/contributor-guide/source/writing-docs.rst b/doc/contributor-guide/source/writing-docs.rst index 8a95f6ce47..3dd11ad044 100644 --- a/doc/contributor-guide/source/writing-docs.rst +++ b/doc/contributor-guide/source/writing-docs.rst @@ -21,3 +21,4 @@ to determine if your change renders properly. topic-structure.rst topic-tags.rst additional-git-workflow.rst + vendor-drivers.rst