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.
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 firstname.lastname@example.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.
A tox-file is provided to build the Guide in a virtualenv, installing all necessary dependencies. To build the HTML version, run:
Another format (as well as other make arguments) can be specified as a command-line argument, e.g.:
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:
The built version of Policy Guide is currently published via a git
repository. The recommended method is to clone the repository
_build/html in order to make Sphinx output into the checkout:
rm -r _build/html git clone email@example.com:sites/projects/qa/policy-guide.git \ _build/html
Commit and push all the changes after rebuilding the Guide.