From: John Spray <john.spray@redhat.com>
Date: Tue, 18 Jul 2017 13:47:06 +0000 (+0100)
Subject: doc: add doc requirements on PR submitters
X-Git-Tag: v12.1.2~131^2
X-Git-Url: http://git-server-git.apps.pok.os.sepia.ceph.com/?a=commitdiff_plain;h=b0b931858d9bbc32d93ba3420a3ff44cb57cf44a;p=ceph.git

doc: add doc requirements on PR submitters

Signed-off-by: John Spray <john.spray@redhat.com>
---

diff --git a/SubmittingPatches.rst b/SubmittingPatches.rst
index bccade3d1e8..0f20155b766 100644
--- a/SubmittingPatches.rst
+++ b/SubmittingPatches.rst
@@ -470,15 +470,31 @@ in your patch description.
 If you cannot condense your patch set into a smaller set of patches,
 then only post say 15 or so at a time and wait for review and integration.
 
+5. Document your changes
+------------------------
+
+If you have added or modified any user-facing functionality, such
+as CLI commands or their output, then the patch series or pull request
+must include appropriate updates to documentation.
+
+It is the submitter's responsibility to make the changes, and the reviewer's
+responsibility to make sure they are not merging changes that do not 
+have the needed updates to documentation.
+
+Where there are areas that have absent documentation, or there is no
+clear place to note the change that is being made, the reviewer should
+contact the component lead, who should arrange for the missing section
+to be created with sufficient detail for the patch submitter to
+document their changes.
 
-5. Style check your changes
+6. Style check your changes
 ---------------------------
 
 Check your patch for basic style violations, details of which can be
 found in CodingStyle.
 
 
-6. No MIME, no links, no compression, no attachments.  Just plain text
+7. No MIME, no links, no compression, no attachments.  Just plain text
 ----------------------------------------------------------------------
 
 Developers need to be able to read and comment on the changes you are
diff --git a/doc/dev/documenting.rst b/doc/dev/documenting.rst
index 602f3c769c4..63e1f191f7b 100644
--- a/doc/dev/documenting.rst
+++ b/doc/dev/documenting.rst
@@ -2,6 +2,28 @@
  Documenting Ceph
 ==================
 
+User documentation
+==================
+
+The documentation on docs.ceph.com is generated from the restructuredText
+sources in ``/doc/`` in the Ceph git repository.
+
+Please make sure that your changes are written in a way that is intended
+for end users of the software, unless you are making additions in
+``/doc/dev/``, which is the section for developers.
+
+All pull requests that modify user-facing functionality must
+include corresponding updates to documentation: see 
+`Submitting Patches`_ for more detail.
+
+Check your .rst syntax is working as expected by using the "View"
+button in the github user interface when looking at a diff on
+an .rst file, or build the docs locally using the ``admin/build-doc``
+script.
+
+For more information about the Ceph documentation, see 
+:doc:`/start/documenting-ceph`.
+
 Code Documentation
 ==================
 
@@ -48,7 +70,7 @@ You can use Graphviz_, as explained in the `Graphviz extension documentation`_.
    digraph "example" {
      foo -> bar;
      bar -> baz;
-     bar -> thud;
+     bar -> th
    }
 
 Most of the time, you'll want to put the actual DOT source in a
@@ -106,3 +128,5 @@ By committing the SVG file, others will be able to update the
 SVG diagrams using Inkscape.
 
 HTML5 will support SVG inline.
+
+.. _Submitting Patches: /SubmittingPatches.rst