diff options
authorMichał Górny <>2020-01-21 18:09:33 +0100
committerSam James <>2023-01-14 18:45:01 +0000
commit23ddd2ec2b5d5066e3a049e7b13f73f3cce2afdf (patch)
parentebuild-format: D in other phases is reported by pkgcheck (diff)
Add a section on editing and publishing
Signed-off-by: Michał Górny <> Closes: Signed-off-by: Sam James <>
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.
+- 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, and available
+via `proj/policy-guide.git gitweb`_. To clone it::
+ # via https
+ git clone
+ # via ssh
+ git clone
+Non-developers wishing to send pull requests may prefer to fork
+the GitHub `gentoo/policy-guide repository`_ and clone their own fork
+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
+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 \
+ _build/html
+Commit and push all the changes after rebuilding the Guide.
+.. _proj/policy-guide.git gitweb:
+.. _gentoo/policy-guide repository:
+.. _Policy Manual Gentoo Bugzilla component:
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.
+ editing