* [gentoo-commits] proj/devmanual:master commit in: ebuild-maintenance/git/
@ 2018-01-03 4:51 Göktürk Yüksek
2018-01-03 5:57 ` [gentoo-commits] proj/devmanual:codesample-indent-fix " Göktürk Yüksek
0 siblings, 1 reply; 4+ messages in thread
From: Göktürk Yüksek @ 2018-01-03 4:51 UTC (permalink / raw
To: gentoo-commits
commit: 30c77a7b4c4beab3e93ab32756a2047c6e2d0d77
Author: Michał Górny <mgorny <AT> gentoo <DOT> org>
AuthorDate: Sat Oct 14 18:27:48 2017 +0000
Commit: Göktürk Yüksek <gokturk <AT> gentoo <DOT> org>
CommitDate: Wed Jan 3 04:38:30 2018 +0000
URL: https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=30c77a7b
ebuild-maintenance/git: Add new section on repoman commit/full
ebuild-maintenance/git/text.xml | 43 ++++++++++++++++++++++++++++++++++-------
1 file changed, 36 insertions(+), 7 deletions(-)
diff --git a/ebuild-maintenance/git/text.xml b/ebuild-maintenance/git/text.xml
index 59f1833..dfc3d5b 100644
--- a/ebuild-maintenance/git/text.xml
+++ b/ebuild-maintenance/git/text.xml
@@ -112,12 +112,46 @@ the historical commits after the initial git commit.
<body>
<subsection>
+<title>Committing and verifying commits</title>
+<body>
+
+<p>
+The recommended way of committing to the Gentoo repository is to use <c>repoman
+commit</c>. It automatically performs the necessary QA checks on the package
+being committed and has other features helping with the Gentoo workflow.
+However, it is currently limited to creating a single commit to a single
+package.
+</p>
+
+<p>
+For any other use case, <c>git commit</c> and other git commands need to be
+used. The valid uses of git include:
+</p>
+
+<ul>
+<li>creating commits spanning multiple packages and/or multiple areas
+of the Gentoo repository (eclasses, licenses, profiles…),</li>
+<li>amending a commit created via <c>repoman commit</c> with additional files
+or fixups,</li>
+<li>combining multiple commits created via <c>repoman commit</c> using <c>git
+rebase</c>.</li>
+</ul>
+
+<p>
+Whenever repoman is not used to commit, you need to manually verify all
+packages affected by the commit using <c>repoman full</c>. Since repoman
+is not aware of staged changes, please make sure that all files are included
+in the commit.
+</p>
+
+</body>
+</subsection>
+
+<subsection>
<title>Git Commit Policy</title>
<body>
<ul>
-<li>Always run <c>repoman scan</c> before you commit.</li>
-<li>Please run <c>repoman full</c> before you commit.</li>
<li>Always test that <path>package.mask</path> is okay by doing
<c>emerge --pretend mypkg</c> before you commit and check
that it doesn't contain any conflicts.</li>
@@ -128,11 +162,6 @@ or that is masked, then first commit the revised <path>package.mask</path> and/o
then commit the ebuild, patches
and <uri link="::ebuild-writing/misc-files/metadata">metadata.xml</uri> all in <b>one</b> go
.</li>
-<note> Although the set of changes in a single git commit is atomic, and
-combining <path>package.mask</path>/license changes with ebuild changes in a
-single commit wouldn't break atomicity, it is not currently possible to do so
-using <c>repoman commit</c>.</note>
-<!-- See: https://bugs.gentoo.org/show_bug.cgi?id=390651 -->
</ul>
</body>
^ permalink raw reply related [flat|nested] 4+ messages in thread
* [gentoo-commits] proj/devmanual:codesample-indent-fix commit in: ebuild-maintenance/git/
2018-01-03 4:51 [gentoo-commits] proj/devmanual:master " Göktürk Yüksek
@ 2018-01-03 5:57 ` Göktürk Yüksek
0 siblings, 0 replies; 4+ messages in thread
From: Göktürk Yüksek @ 2018-01-03 5:57 UTC (permalink / raw
To: gentoo-commits
commit: 8f6095d523d5e36ddff1f089cf612fd5fe74e75a
Author: Michał Górny <mgorny <AT> gentoo <DOT> org>
AuthorDate: Sat Oct 14 10:18:42 2017 +0000
Commit: Göktürk Yüksek <gokturk <AT> gentoo <DOT> org>
CommitDate: Wed Jan 3 04:29:35 2018 +0000
URL: https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=8f6095d5
ebuild-maintenance/git: Include instructions for setting up the checkout
ebuild-maintenance/git/text.xml | 102 ++++++++++++++++++++++++++++++++++++++--
1 file changed, 99 insertions(+), 3 deletions(-)
diff --git a/ebuild-maintenance/git/text.xml b/ebuild-maintenance/git/text.xml
index 172e22c..2070217 100644
--- a/ebuild-maintenance/git/text.xml
+++ b/ebuild-maintenance/git/text.xml
@@ -5,12 +5,108 @@
<body>
<p>
-This guide covers git usage instructions and policies specific to Gentoo
-ebuild development. It assumes that the readers possess basic git
-knowledge. For a generic guide, please see the official
+This guide covers git usage instructions and policies specific to Gentoo ebuild
+development. It assumes that the readers possess basic git knowledge.
+For a generic guide, please see the official
<uri link="https://git-scm.com/book/">git book</uri>.
</p>
+
+<section>
+<title>Preparing a development checkout</title>
+<body>
+
+<subsection>
+<title>Cloning the gentoo.git repository</title>
+<body>
+
+<p>
+The ebuild development happens on the official git repository. You can push
+your changes only through the SSH protocol. Therefore, clone the repository
+using:
+</p>
+
+<pre>
+git clone git@git.gentoo.org:repo/gentoo.git
+</pre>
+
+<p>
+If you do not have SSH access to the Gentoo git service, you can use the anongit
+mirror for read-only access instead:
+</p>
+
+<pre>
+git clone https://anongit.gentoo.org/git/repo/gentoo.git
+</pre>
+
+<p>
+Normally git will fetch the complete history from the start of git repository
+(Aug 2015). This can require a significant amount of disk space. If you do not
+need the full history, you can use the <c>--depth</c> option to create a shallow
+clone, including only a subset containing the the newest commits. For example,
+<c>--depth=50</c> will include the 50 newest commits.
+</p>
+
+<p>
+Please note that git version 1.9 or newer is required to push when using
+a shallow clone.
+</p>
+
+</body>
+</subsection>
+
+<subsection>
+<title>Configuration specific to the Gentoo repository</title>
+<body>
+
+<p>
+To ensure that the Gentoo policies are followed, you should set the following
+configuration variables:
+</p>
+
+<pre caption="Configuring git for the Gentoo repository">
+git config --local user.name "${YOUR_FULL_NAME}"
+# use your @gentoo.org address even if you have a different default
+git config --local user.email "${YOUR_NICKNAME}@gentoo.org"
+
+# enable commit and push signing
+git config --local user.signingkey "0x${LONG_OPENPGP_KEY_ID}"
+git config --local commit.gpgsign 1
+git config --local push.gpgsign 1
+
+# prevent implicit merges on 'git pull'
+git config --local pull.ff only
+</pre>
+
+</body>
+</subsection>
+
+<subsection>
+<title>Grafting converted CVS history into the clone</title>
+<body>
+
+<p>
+To include the converted CVS history in the git repository, you can
+graft it into the repository:
+</p>
+
+<pre caption="Grafting the history into git">
+git remote add history https://anongit.gentoo.org/git/repo/gentoo/historical.git/
+git fetch history
+git replace --graft 56bd759df1d0c750a065b8c845e93d5dfa6b549d history/master
+</pre>
+
+<p>
+Once this is done, git commands such as <c>git log</c> will include
+the historical commits after the initial git commit.
+</p>
+
+</body>
+</subsection>
+
+</body>
+</section>
+
</body>
</chapter>
</guide>
^ permalink raw reply related [flat|nested] 4+ messages in thread
* [gentoo-commits] proj/devmanual:codesample-indent-fix commit in: ebuild-maintenance/git/
2018-01-03 4:51 [gentoo-commits] proj/devmanual:master commit in: ebuild-maintenance/git/ Göktürk Yüksek
@ 2018-01-03 5:57 ` Göktürk Yüksek
0 siblings, 0 replies; 4+ messages in thread
From: Göktürk Yüksek @ 2018-01-03 5:57 UTC (permalink / raw
To: gentoo-commits
commit: 30c77a7b4c4beab3e93ab32756a2047c6e2d0d77
Author: Michał Górny <mgorny <AT> gentoo <DOT> org>
AuthorDate: Sat Oct 14 18:27:48 2017 +0000
Commit: Göktürk Yüksek <gokturk <AT> gentoo <DOT> org>
CommitDate: Wed Jan 3 04:38:30 2018 +0000
URL: https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=30c77a7b
ebuild-maintenance/git: Add new section on repoman commit/full
ebuild-maintenance/git/text.xml | 43 ++++++++++++++++++++++++++++++++++-------
1 file changed, 36 insertions(+), 7 deletions(-)
diff --git a/ebuild-maintenance/git/text.xml b/ebuild-maintenance/git/text.xml
index 59f1833..dfc3d5b 100644
--- a/ebuild-maintenance/git/text.xml
+++ b/ebuild-maintenance/git/text.xml
@@ -112,12 +112,46 @@ the historical commits after the initial git commit.
<body>
<subsection>
+<title>Committing and verifying commits</title>
+<body>
+
+<p>
+The recommended way of committing to the Gentoo repository is to use <c>repoman
+commit</c>. It automatically performs the necessary QA checks on the package
+being committed and has other features helping with the Gentoo workflow.
+However, it is currently limited to creating a single commit to a single
+package.
+</p>
+
+<p>
+For any other use case, <c>git commit</c> and other git commands need to be
+used. The valid uses of git include:
+</p>
+
+<ul>
+<li>creating commits spanning multiple packages and/or multiple areas
+of the Gentoo repository (eclasses, licenses, profiles…),</li>
+<li>amending a commit created via <c>repoman commit</c> with additional files
+or fixups,</li>
+<li>combining multiple commits created via <c>repoman commit</c> using <c>git
+rebase</c>.</li>
+</ul>
+
+<p>
+Whenever repoman is not used to commit, you need to manually verify all
+packages affected by the commit using <c>repoman full</c>. Since repoman
+is not aware of staged changes, please make sure that all files are included
+in the commit.
+</p>
+
+</body>
+</subsection>
+
+<subsection>
<title>Git Commit Policy</title>
<body>
<ul>
-<li>Always run <c>repoman scan</c> before you commit.</li>
-<li>Please run <c>repoman full</c> before you commit.</li>
<li>Always test that <path>package.mask</path> is okay by doing
<c>emerge --pretend mypkg</c> before you commit and check
that it doesn't contain any conflicts.</li>
@@ -128,11 +162,6 @@ or that is masked, then first commit the revised <path>package.mask</path> and/o
then commit the ebuild, patches
and <uri link="::ebuild-writing/misc-files/metadata">metadata.xml</uri> all in <b>one</b> go
.</li>
-<note> Although the set of changes in a single git commit is atomic, and
-combining <path>package.mask</path>/license changes with ebuild changes in a
-single commit wouldn't break atomicity, it is not currently possible to do so
-using <c>repoman commit</c>.</note>
-<!-- See: https://bugs.gentoo.org/show_bug.cgi?id=390651 -->
</ul>
</body>
^ permalink raw reply related [flat|nested] 4+ messages in thread
* [gentoo-commits] proj/devmanual:codesample-indent-fix commit in: ebuild-maintenance/git/
2018-01-03 4:51 [gentoo-commits] proj/devmanual:master " Göktürk Yüksek
@ 2018-01-03 5:57 ` Göktürk Yüksek
0 siblings, 0 replies; 4+ messages in thread
From: Göktürk Yüksek @ 2018-01-03 5:57 UTC (permalink / raw
To: gentoo-commits
commit: 5121332b708a733b2b52975a1100b847dcb0c60a
Author: Michał Górny <mgorny <AT> gentoo <DOT> org>
AuthorDate: Sat Oct 14 18:45:55 2017 +0000
Commit: Göktürk Yüksek <gokturk <AT> gentoo <DOT> org>
CommitDate: Wed Jan 3 04:42:55 2018 +0000
URL: https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=5121332b
ebuild-maintenance/git: Try to describe atomic commits better (GLEP 66)
ebuild-maintenance/git/text.xml | 50 ++++++++++++++++++++++++++++++-----------
1 file changed, 37 insertions(+), 13 deletions(-)
diff --git a/ebuild-maintenance/git/text.xml b/ebuild-maintenance/git/text.xml
index dfc3d5b..c61589d 100644
--- a/ebuild-maintenance/git/text.xml
+++ b/ebuild-maintenance/git/text.xml
@@ -148,21 +148,45 @@ in the commit.
</subsection>
<subsection>
-<title>Git Commit Policy</title>
+<title>Atomic commits</title>
<body>
-<ul>
-<li>Always test that <path>package.mask</path> is okay by doing
-<c>emerge --pretend mypkg</c> before you commit and check
-that it doesn't contain any conflicts.</li>
-<li>Always commit the updated <path>package.mask</path> before
-the updated package.</li>
-<li>Always do atomic commits; if you commit a package with a new license,
-or that is masked, then first commit the revised <path>package.mask</path> and/or license,
-then commit the ebuild, patches
-and <uri link="::ebuild-writing/misc-files/metadata">metadata.xml</uri> all in <b>one</b> go
-.</li>
-</ul>
+<p>
+Whenever possible, use atomic commits. Try to split your changes into logical
+commits, abiding by the following three rules as much as possible:
+</p>
+
+<ol>
+<li>
+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.
+</li>
+
+<li>
+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.
+</li>
+
+<li>
+Avoid creating commits introducing a temporary breakage. Unless impossible,
+add packages in dependency install order. Add licenses before the packages
+needing them. Commit <path>package.mask</path> 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.
+</li>
+</ol>
+
+<p>
+Please note that revision bumps count as side effects of the changes requiring
+them and do not belong in separate commits. When doing multiple irrelevant
+changes that require a revision bump, it is only necessary to bump the revision
+in the first commit in the series introduced by a single push.
+</p>
</body>
</subsection>
^ permalink raw reply related [flat|nested] 4+ messages in thread
end of thread, other threads:[~2018-01-03 5:57 UTC | newest]
Thread overview: 4+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2018-01-03 4:51 [gentoo-commits] proj/devmanual:master commit in: ebuild-maintenance/git/ Göktürk Yüksek
2018-01-03 5:57 ` [gentoo-commits] proj/devmanual:codesample-indent-fix " Göktürk Yüksek
-- strict thread matches above, loose matches on Subject: below --
2018-01-03 4:51 [gentoo-commits] proj/devmanual:master " Göktürk Yüksek
2018-01-03 5:57 ` [gentoo-commits] proj/devmanual:codesample-indent-fix " Göktürk Yüksek
2018-01-03 4:51 [gentoo-commits] proj/devmanual:master " Göktürk Yüksek
2018-01-03 5:57 ` [gentoo-commits] proj/devmanual:codesample-indent-fix " Göktürk Yüksek
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox