summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorMichał Górny <mgorny@gentoo.org>2020-01-21 18:09:33 +0100
committerSam James <sam@gentoo.org>2023-01-14 18:45:01 +0000
commit23ddd2ec2b5d5066e3a049e7b13f73f3cce2afdf (patch)
treee7e670cb9b7d4d8e2614847df54a3358fe136376
parentebuild-format: D in other phases is reported by pkgcheck (diff)
downloadpolicy-guide-23ddd2ec2b5d5066e3a049e7b13f73f3cce2afdf.tar.gz
policy-guide-23ddd2ec2b5d5066e3a049e7b13f73f3cce2afdf.tar.bz2
policy-guide-23ddd2ec2b5d5066e3a049e7b13f73f3cce2afdf.zip
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>
-rw-r--r--editing.rst86
-rw-r--r--index.rst1
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
*