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.