git: bcbdcf52ce - main - Move the developer-centric bits from handbook/mirrors to committers-guide
Warner Losh <[email protected]>
| Newsgroups | gmane.os.freebsd.devel.cvs.doc |
|---|---|
| Message-ID | <[email protected]> |
The branch main has been updated by imp: URL: https://cgit.FreeBSD.org/doc/commit/?id=bcbdcf52ce6535afa5da0cb48b1575ab8d071990 commit bcbdcf52ce6535afa5da0cb48b1575ab8d071990 Author: Warner Losh <[email protected]> AuthorDate: 2021-06-11 18:10:07 +0000 Commit: Warner Losh <[email protected]> CommitDate: 2021-06-11 22:13:39 +0000 Move the developer-centric bits from handbook/mirrors to committers-guide 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 --- .../en/articles/committers-guide/_index.adoc | 101 +++++++++++++++++++- .../content/en/books/handbook/mirrors/_index.adoc | 102 +-------------------- 2 files changed, 101 insertions(+), 102 deletions(-) diff --git a/documentation/content/en/articles/committers-guide/_index.adoc b/documentation/content/en/articles/committers-guide/_index.adoc index 835f28cf99..63f2db466e 100644 --- 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 [email protected]:${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 [email protected]:${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 index b709efaadf..501a30f77a 100644 --- 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 [email protected]:${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 [email protected]:${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 _______________________________________________ [email protected] mailing list https://lists.freebsd.org/mailman/listinfo/dev-commits-doc-all To unsubscribe, send any mail to "[email protected]"