Skip to content

Latest commit

 

History

History
86 lines (61 loc) · 2.6 KB

editing.rst

File metadata and controls

86 lines (61 loc) · 2.6 KB
Raw

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.