From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from lists.gentoo.org (pigeon.gentoo.org [208.92.234.80]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits)) (No client certificate requested) by finch.gentoo.org (Postfix) with ESMTPS id 8884D15800F for ; Sat, 14 Jan 2023 18:46:05 +0000 (UTC) Received: from pigeon.gentoo.org (localhost [127.0.0.1]) by pigeon.gentoo.org (Postfix) with SMTP id D3C5DE07EA; Sat, 14 Jan 2023 18:46:04 +0000 (UTC) Received: from smtp.gentoo.org (mail.gentoo.org [IPv6:2001:470:ea4a:1:5054:ff:fec7:86e4]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits)) (No client certificate requested) by pigeon.gentoo.org (Postfix) with ESMTPS id BA8EBE07EA for ; Sat, 14 Jan 2023 18:46:04 +0000 (UTC) Received: from oystercatcher.gentoo.org (oystercatcher.gentoo.org [148.251.78.52]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits)) (No client certificate requested) by smtp.gentoo.org (Postfix) with ESMTPS id 08305335C9A for ; Sat, 14 Jan 2023 18:46:04 +0000 (UTC) Received: from localhost.localdomain (localhost [IPv6:::1]) by oystercatcher.gentoo.org (Postfix) with ESMTP id 9E0C37DE for ; Sat, 14 Jan 2023 18:46:02 +0000 (UTC) From: "Sam James" To: gentoo-commits@lists.gentoo.org Content-Transfer-Encoding: 8bit Content-type: text/plain; charset=UTF-8 Reply-To: gentoo-dev@lists.gentoo.org, "Sam James" Message-ID: <1673721901.23ddd2ec2b5d5066e3a049e7b13f73f3cce2afdf.sam@gentoo> Subject: [gentoo-commits] proj/policy-guide:master commit in: / X-VCS-Repository: proj/policy-guide X-VCS-Files: editing.rst index.rst X-VCS-Directories: / X-VCS-Committer: sam X-VCS-Committer-Name: Sam James X-VCS-Revision: 23ddd2ec2b5d5066e3a049e7b13f73f3cce2afdf X-VCS-Branch: master Date: Sat, 14 Jan 2023 18:46:02 +0000 (UTC) Precedence: bulk List-Post: List-Help: List-Unsubscribe: List-Subscribe: List-Id: Gentoo Linux mail X-BeenThere: gentoo-commits@lists.gentoo.org X-Auto-Response-Suppress: DR, RN, NRN, OOF, AutoReply X-Archives-Salt: d3d1893d-0635-4564-ae02-899d1ffcf5e3 X-Archives-Hash: 239a83f54c5c882ed5bdeab25ce1af97 commit: 23ddd2ec2b5d5066e3a049e7b13f73f3cce2afdf Author: Michał Górny gentoo org> AuthorDate: Tue Jan 21 17:09:33 2020 +0000 Commit: Sam James gentoo 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 gentoo.org> Closes: https://github.com/gentoo/policy-guide/pull/10 Signed-off-by: Sam James 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 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 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 *