Git for Gentoo Developers

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.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by finch.gentoo.org (Postfix) with ESMTPS id 2CE181382C5 for ; Tue, 30 Mar 2021 16:10:12 +0000 (UTC) Received: from pigeon.gentoo.org (localhost [127.0.0.1]) by pigeon.gentoo.org (Postfix) with SMTP id 7D171E0AE7; Tue, 30 Mar 2021 16:10:11 +0000 (UTC) Received: from smtp.gentoo.org (smtp.gentoo.org [140.211.166.183]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by pigeon.gentoo.org (Postfix) with ESMTPS id 553AAE0AE7 for ; Tue, 30 Mar 2021 16:10:11 +0000 (UTC) Received: from oystercatcher.gentoo.org (oystercatcher.gentoo.org [148.251.78.52]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.gentoo.org (Postfix) with ESMTPS id 35982335D59 for ; Tue, 30 Mar 2021 16:10:10 +0000 (UTC) Received: from localhost.localdomain (localhost [IPv6:::1]) by oystercatcher.gentoo.org (Postfix) with ESMTP id 5CAD463D for ; Tue, 30 Mar 2021 16:10:07 +0000 (UTC) From: "Ulrich Müller" To: gentoo-commits@lists.gentoo.org Content-Transfer-Encoding: 8bit Content-type: text/plain; charset=UTF-8 Reply-To: gentoo-dev@lists.gentoo.org, "Ulrich Müller" Message-ID: <1617120581.1536e0fe2f087a555580b9f21de8162e08caa890.ulm@gentoo> Subject: [gentoo-commits] proj/devmanual:master commit in: ebuild-maintenance/git/ X-VCS-Repository: proj/devmanual X-VCS-Files: ebuild-maintenance/git/text.xml X-VCS-Directories: ebuild-maintenance/git/ X-VCS-Committer: ulm X-VCS-Committer-Name: Ulrich Müller X-VCS-Revision: 1536e0fe2f087a555580b9f21de8162e08caa890 X-VCS-Branch: master Date: Tue, 30 Mar 2021 16:10:07 +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: c82dafa2-7cdf-44a2-8a26-b31aa8c9efd1 X-Archives-Hash: a88ef461a48bba6df7b87523d159e676 commit: 1536e0fe2f087a555580b9f21de8162e08caa890 Author: Ulrich Müller gentoo org> AuthorDate: Tue Mar 30 16:09:41 2021 +0000 Commit: Ulrich Müller gentoo org> CommitDate: Tue Mar 30 16:09:41 2021 +0000 URL: https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=1536e0fe ebuild-maintenance/git: Formatting fixes Signed-off-by: Ulrich Müller gentoo.org> ebuild-maintenance/git/text.xml | 125 ++++++++++++++++++++++------------------ 1 file changed, 69 insertions(+), 56 deletions(-) diff --git a/ebuild-maintenance/git/text.xml b/ebuild-maintenance/git/text.xml index fc2738a..0cad9bf 100644 --- a/ebuild-maintenance/git/text.xml +++ b/ebuild-maintenance/git/text.xml @@ -2,8 +2,8 @@ Git for Gentoo Developers - +

This guide covers git usage instructions and policies specific to Gentoo ebuild development. It assumes that the readers possess basic git knowledge. @@ -125,12 +125,18 @@ used. The valid uses of git include:

creating commits spanning multiple packages and/or multiple areas -of the Gentoo repository (eclasses, licenses, profiles…),
amending a commit created via repoman commit or pkgdev commit -with additional files or fixups,
combining multiple commits created via repoman commit or -pkgdev commit using git rebase.
+ creating commits spanning multiple packages and/or multiple areas of the + Gentoo repository (eclasses, licenses, profiles…), +
+ amending a commit created via repoman commit or pkgdev commit + with additional files or fixups, +
+ combining multiple commits created via repoman commit or + pkgdev commit using git rebase. +

@@ -138,8 +144,8 @@ Whenever repoman or pkgdev is not used to commit, you need to manually verify all packages affected by the commit using repoman full or pkgcheck scan --commits. When using repoman, it won't be aware of staged changes, so ensure that all files are included in the commit. -Also, when using git manually, you must perform a manual sign-off -to the +Also, when using git manually, you must perform a manual sign-off to the + Certificate of Origin using the -s or --signoff option with your git commit commands. Make sure you have read and understand the actual Certificate. @@ -158,28 +164,26 @@ commits, abiding by the following three rules as much as possible:

-Do not include multiple irrelevant changes in a single commit. However, make -sure not to split relevant changes unnecessarily. For example, if a version bump -requires changes in the ebuild, it is correct to perform them in a single -commit. However, if you are fixing an additional bug that has been present -in the previous version, the fix belongs in a separate commit. -
-Split commits at logical unit boundaries. When updating multiple packages, -preferably use a single commit for each package. Avoid combining changes -to ebuilds, eclasses, licenses, profiles etc. in a single commit. However, -do not split relevant or interdependent changes within a single package. -
-Avoid creating commits introducing a temporary breakage. Unless impossible, -add packages in dependency install order. Add licenses before the packages -needing them. Commit package.mask and other profile changes before -ebuilds relying on them. Usually it is also acceptable to include those changes -along with the commit adding the package. -
+ Do not include multiple irrelevant changes in a single commit. However, + make sure not to split relevant changes unnecessarily. For example, if a + version bump requires changes in the ebuild, it is correct to perform them + in a single commit. However, if you are fixing an additional bug that has + been present in the previous version, the fix belongs in a separate commit. +
+ Split commits at logical unit boundaries. When updating multiple packages, + preferably use a single commit for each package. Avoid combining changes + to ebuilds, eclasses, licenses, profiles etc. in a single commit. However, + do not split relevant or interdependent changes within a single package. +
+ Avoid creating commits introducing a temporary breakage. Unless impossible, + add packages in dependency install order. Add licenses before the packages + needing them. Commit package.mask and other profile changes before + ebuilds relying on them. Usually it is also acceptable to include those + changes along with the commit adding the package. +

@@ -220,13 +224,15 @@ appropriately:

${CATEGORY}/${PN}: Single Package (Note that repoman commit -and pkgdev commit will automatically insert this for you)
${CATEGORY}: Package Category
profiles: Profile Directory
${ECLASS}.eclass: Eclass Directotry
licenses: Licenses Directory
metadata: Metadata Directory
+ ${CATEGORY}/${PN}: Single Package (Note that repoman commit + and pkgdev commit will automatically insert this for you) +
${CATEGORY}: Package Category
profiles: Profile Directory
${ECLASS}.eclass: Eclass Directotry
licenses: Licenses Directory
metadata: Metadata Directory

@@ -266,24 +272,31 @@ are optionally used in Gentoo:

Bug: Use this to reference bugs without closing them. -The value is a URL to the bug. If multiple bugs need to be referenced, -each one should be listed in a separate Bug tag. If a bug -on Gentoo Bugzilla, or an issue or a pull request on GitHub -is referenced, a reference to the commit will be added -automatically.
Closes: Use this to reference bugs and close them -automatically. Alike Bug:, the value is a single URL to the bug, -and multiple tags can be used to close multiple bugs. If a bug on Gentoo -Bugzilla, or an issue or a pull request on a GitHub repository -mirrored by Gentoo is referenced, it will be closed (as fixed) -automatically with reference to the commit.
Package-Manager: This is automatically inserted by -repoman commit and it specifies the version of -sys-apps/portage on the system.
RepoMan-Options: This is automatically inserted by -repoman commit and records the options passed to repoman (such -as --force) for the commit.
+ Bug: Use this to reference bugs without closing them. + The value is a URL to the bug. If multiple bugs need to be referenced, + each one should be listed in a separate Bug tag. If a bug on + Gentoo Bugzilla, or an issue or a pull request on GitHub is referenced, + a reference to the commit will be added automatically. +
+ Closes: Use this to reference bugs and close them automatically. + Alike Bug:, the value is a single URL to the bug, and multiple tags + can be used to close multiple bugs. If a bug on Gentoo Bugzilla, or an + issue or a pull request on a GitHub repository mirrored by Gentoo is + referenced, it will be closed (as fixed) automatically with reference + to the commit. +
+ Package-Manager: This is automatically inserted by + repoman commit and it specifies the version of + sys-apps/portage on the system. +
+ RepoMan-Options: This is automatically inserted by + repoman commit and records the options passed to repoman (such as + --force) for the commit. +