Move the developer-centric bits from handbook/mirrors to committers-g…

…uide The developer centric bits of how to interact with the project belong in the committer's guide, not in the handbook, so move it there. Reviewed by: gjb,debdrup Sponsored by: Netflix Differential Revision: https://reviews.freebsd.org/D30739
freebsd · Jun 11, 2021 · bcbdcf5 · bcbdcf5
1 parent 102c844
commit bcbdcf5
Show file tree

Hide file tree

Showing 2 changed files with 101 additions and 102 deletions.
diff --git a/documentation/content/en/articles/committers-guide/_index.adoc b/documentation/content/en/articles/committers-guide/_index.adoc
@@ -302,6 +302,105 @@ The goal of this section is to highlight those bits of Git needed to track sourc
 They assume a basic understanding of Git.
 There are many primers for Git on the web, but the https://git-scm.com/book/en/v2[Git Book] provides one of the better treatments.
 
+[[git-mini-primer-getting-started]]
+==== Getting Started For Developers
+
+This section describes the read-write access for committers to push the commits from developers or contributors.
+
+===== Daily use
+
+* Clone the repository:
++
+[source,shell]
+....
+% git clone -o freebsd --config remote.freebsd.fetch='+refs/notes/*:refs/notes/*' https://git.freebsd.org/${repo}.git
+....
++
+Then you should have the official mirrors as your remote:
++
+[source,shell]
+....
+% git remote -v
+freebsd  https://git.freebsd.org/${repo}.git (fetch)
+freebsd  https://git.freebsd.org/${repo}.git (push)
+....
+
+* Configure the FreeBSD committer data:
++
+The commit hook in repo.freebsd.org checks the "Commit" field matches the committer's information in FreeBSD.org.
+The easiest way to get the suggested config is by executing `/usr/local/bin/gen-gitconfig.sh` script on freefall:
++
+[source,shell]
+....
+% gen-gitconfig.sh
+[...]
+% git config user.name (your name in gecos)
+% git config user.email (your login)@FreeBSD.org
+....
+
+* Set the push URL:
++
+[source,shell]
+....
+% git remote set-url --push freebsd git@gitrepo.freebsd.org:${repo}.git
+....
++
+Then you should have separated fetch and push URLs as the most efficient setup:
++
+[source,shell]
+....
+% git remote -v
+freebsd  https://git.freebsd.org/${repo}.git (fetch)
+freebsd  git@gitrepo.freebsd.org:${repo}.git (push)
+....
++
+Again, note that `gitrepo.freebsd.org` will be canonicalized to `repo.freebsd.org` in the future.
+
+* Install commit message template hook:
++
+[source,shell]
+....
+% fetch https://cgit.freebsd.org/src/plain/tools/tools/git/hooks/prepare-commit-msg -o .git/hooks
+% chmod 755 .git/hooks/prepare-commit-msg
+....
+
+[[admin-branch]]
+===== "admin" branch
+
+The `access` and `mentors` files are stored in an orphan branch, `internal/admin`, in each repository.
+
+Following example is how to check out the `internal/admin` branch to a local branch named `admin`:
+
+[source,shell]
+....
+% git config --add remote.freebsd.fetch '+refs/internal/*:refs/internal/*'
+% git fetch
+% git checkout -b admin internal/admin
+....
+Alternatively, you can add a worktree for the `admin` branch:
+
+[source,shell]
+....
+git worktree add -b admin ../${repo}-admin internal/admin
+....
+
+For browsing `internal/admin` branch on web:
+https://cgit.freebsd.org/${repo}/log/?h=internal/admin
+
+For pushing, either specify the full refspec:
+
+[source,shell]
+....
+git push freebsd HEAD:refs/internal/admin
+....
+
+Or set `push.default` to `freebsd` which will make `git push` to push the current branch back to its upstream by default, which is more suitable for our workflow:
+
+[source,shell]
+....
+git config push.default freebsd
+....
+
 ==== Keeping Current With The FreeBSD src Tree
 [[keeping_current]]
 First step: cloning a tree.
@@ -2483,7 +2582,7 @@ Document that approval with an `Approved by:` line in the commit message.
 
 When the mentor decides that a mentee has learned the ropes and is ready to commit on their own, the mentor announces it with a commit to [.filename]#mentors#.
 This file is in the [.filename]#admin# orphan branch of each repository.
-Detailed information on how to access these branches can be found in link:{handbook}mirror/#admin-branch["admin" branch].
+Detailed information on how to access these branches can be found in <<admin-branch>>.
 
 [[pre-commit-review]]
 == Pre-Commit Review

diff --git a/documentation/content/en/books/handbook/mirrors/_index.adoc b/documentation/content/en/books/handbook/mirrors/_index.adoc
@@ -571,107 +571,7 @@ The GeoDNS should direct you to the nearest mirror to you.
 
 === For Developers
 
-This section describes the read-write access for committers to push the commits from developers or contributors.
-For read-only access, please refer to the users section above.
-
-==== Daily use
-
-* Clone the repository:
-+
-[source,shell]
-....
-% git clone -o freebsd --config remote.freebsd.fetch='+refs/notes/*:refs/notes/*' https://git.freebsd.org/${repo}.git
-....
-+
-Then you should have the official mirrors as your remote:
-+
-[source,shell]
-....
-% git remote -v
-freebsd  https://git.freebsd.org/${repo}.git (fetch)
-freebsd  https://git.freebsd.org/${repo}.git (push)
-....
-
-* Configure the FreeBSD committer data:
-+
-The commit hook in repo.freebsd.org checks the "Commit" field matches the committer's information in FreeBSD.org.
-The easiest way to get the suggested config is by executing `/usr/local/bin/gen-gitconfig.sh` script on freefall:
-+
-[source,shell]
-....
-% gen-gitconfig.sh
-[...]
-% git config user.name (your name in gecos)
-% git config user.email (your login)@FreeBSD.org
-....
-
-* Set the push URL:
-+
-[source,shell]
-....
-% git remote set-url --push freebsd git@gitrepo.freebsd.org:${repo}.git
-....
-+
-Then you should have separated fetch and push URLs as the most efficient setup:
-+
-[source,shell]
-....
-% git remote -v
-freebsd  https://git.freebsd.org/${repo}.git (fetch)
-freebsd  git@gitrepo.freebsd.org:${repo}.git (push)
-....
-+
-Again, note that `gitrepo.freebsd.org` will be canonicalized to `repo.freebsd.org` in the future.
-
-* Install commit message template hook:
-+
-[source,shell]
-....
-% fetch https://cgit.freebsd.org/src/plain/tools/tools/git/hooks/prepare-commit-msg -o .git/hooks
-% chmod 755 .git/hooks/prepare-commit-msg
-....
-
-[[admin-branch]]
-==== "admin" branch
-
-The `access` and `mentors` files are stored in an orphan branch, `internal/admin`, in each repository.
-
-Following example is how to check out the `internal/admin` branch to a local branch named `admin`:
-
-[source,shell]
-....
-% git config --add remote.freebsd.fetch '+refs/internal/*:refs/internal/*'
-% git fetch
-% git checkout -b admin internal/admin
-....
-Alternatively, you can add a worktree for the `admin` branch:
-
-[source,shell]
-....
-git worktree add -b admin ../${repo}-admin internal/admin
-....
-
-For browsing `internal/admin` branch on web:
-https://cgit.freebsd.org/${repo}/log/?h=internal/admin
-
-For pushing, either specify the full refspec:
-
-[source,shell]
-....
-git push freebsd HEAD:refs/internal/admin
-....
-
-Or set `push.default` to `upstream` which will make `git push` to push the current branch back to its upstream by default, which is more suitable for our workflow:
-
-[source,shell]
-....
-git config push.default upstream
-....
-
-[WARNING]
-====
-These internal details may change often.
-====
+Please see the link:{committers-guide}#git-mini-primer[Committer's Guide].
 
 [[external-mirrors]]
 === External mirrors