diff options
| -rw-r--r-- | editing.rst | 86 | ||||
| -rw-r--r-- | index.rst | 1 |
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 @@ -17,6 +17,7 @@ in which the policy can be updated. motivation basics other-docs + editing * |