commit: 23ddd2ec2b5d5066e3a049e7b13f73f3cce2afdf Author: Michał Górny <mgorny <AT> gentoo <DOT> org> AuthorDate: Tue Jan 21 17:09:33 2020 +0000 Commit: Sam James <sam <AT> gentoo <DOT> org> CommitDate: Sat Jan 14 18:45:01 2023 +0000 URL: https://gitweb.gentoo.org/proj/policy-guide.git/commit/?id=23ddd2ec
Add a section on editing and publishing Signed-off-by: Michał Górny <mgorny <AT> gentoo.org> Closes: https://github.com/gentoo/policy-guide/pull/10 Signed-off-by: Sam James <sam <AT> gentoo.org> editing.rst | 86 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ index.rst | 1 + 2 files changed, 87 insertions(+) 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 [email protected]: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 [email protected]: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 *
