Add a section on editing and publishing

Signed-off-by: Michał Górny <mgorny@gentoo.org>
Closes: https://github.com/gentoo/policy-guide/pull/10
Signed-off-by: Sam James <sam@gentoo.org>

2 files changed, 87 insertions, 0 deletions

diff --git a/editing.rst b/editing.rst
new file mode 100644
index 0000000..a12ff0b
--- /dev/null
+++ b/editing.rst
@@ -0,0 +1,86 @@
+Editing and publishing updates to this Guide
+============================================
+
+Formatting and style
+--------------------
+While editing the Guide, please respect the existing formatting rules.
+Notably:
+
+- wrap lines at 72 characters
+- two spaces between sentences (after full stop), one space otherwise
+- one empty line between titles and paragraphs, two empty lines between
+  text and next section
+- indent using spaces, aligning to previous line
+
+When adding a new rule, use the chapter with a fitting topic.  Some
+rules match multiple chapters, choose the one that fits it best.  Make
+sure to match existing keywords in index.
+
+
+Getting sources
+---------------
+The reference repository is hosted at git.gentoo.org, and available
+via `proj/policy-guide.git gitweb`_.  To clone it::
+
+    # via https
+    git clone https://anongit.gentoo.org/git/proj/policy-guide.git
+    # via ssh
+    git clone git@git.gentoo.org:proj/policy-guide.git
+
+Non-developers wishing to send pull requests may prefer to fork
+the GitHub `gentoo/policy-guide repository`_ and clone their own fork
+instead.
+
+
+Building
+--------
+A tox-file is provided to build the Guide in a virtualenv, installing
+all necessary dependencies.  To build the HTML version, run::
+
+    tox
+
+Another format (as well as other make arguments) can be specified
+as a command-line argument, e.g.::
+
+    tox latexpdf
+
+
+Sending contributions
+---------------------
+Changes to this document can be either submitted to `Policy Manual
+Gentoo Bugzilla component`_ as git-format patches attached to the bugs,
+or to `gentoo/policy-guide repository`_ as pull requests.
+
+
+Merging pull requests
+---------------------
+The recommended way to merge pull requests is to use
+``app-portage/pram``.  To configure the remote before the first use,
+run the following command in your checkout::
+
+    git config --replace-all pram.repo gentoo/policy-guide
+
+Afterwards, call the tool to merge pull request by number::
+
+    pram N
+
+
+Publishing
+----------
+The built version of Policy Guide is currently published via a git
+repository.  The recommended method is to clone the repository
+into ``_build/html`` in order to make Sphinx output into the checkout::
+
+    rm -r _build/html
+    git clone git@git.gentoo.org:sites/projects/qa/policy-guide.git \
+        _build/html
+
+Commit and push all the changes after rebuilding the Guide.
+
+
+.. _proj/policy-guide.git gitweb:
+   https://gitweb.gentoo.org/proj/policy-guide.git/
+.. _gentoo/policy-guide repository:
+   https://github.com/gentoo/policy-guide
+.. _Policy Manual Gentoo Bugzilla component:
+   https://bugs.gentoo.org/enter_bug.cgi?product=Documentation&component=Policy+Guide
diff --git a/index.rst b/index.rst
index b3bcddc..1978cc8 100644
--- a/index.rst
+++ b/index.rst
@@ -17,6 +17,7 @@ in which the policy can be updated.
    motivation
    basics
    other-docs
+   editing
    *