[PATCH] Documentation/howto: tracking git.git

[Bagas Sanjaya <bagasdotme@gmail.com>]

Document how to track git.git repository for Git development.

Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
 Documentation/Makefile                  |  1 +
 Documentation/howto/tracking-gitgit.txt | 79 +++++++++++++++++++++++++
 2 files changed, 80 insertions(+)
 create mode 100644 Documentation/howto/tracking-gitgit.txt

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 2aae4c9cbb..2b5b8b28b0 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -84,6 +84,7 @@ SP_ARTICLES += howto/rebase-from-internal-branch
 SP_ARTICLES += howto/keep-canonical-history-correct
 SP_ARTICLES += howto/maintain-git
 SP_ARTICLES += howto/coordinate-embargoed-releases
+SP_ARTICLES += howto/tracking-gitgit
 API_DOCS = $(patsubst %.txt,%,$(filter-out technical/api-index-skel.txt technical/api-index.txt, $(wildcard technical/api-*.txt)))
 SP_ARTICLES += $(API_DOCS)
 
diff --git a/Documentation/howto/tracking-gitgit.txt b/Documentation/howto/tracking-gitgit.txt
new file mode 100644
index 0000000000..61dbd2540b
--- /dev/null
+++ b/Documentation/howto/tracking-gitgit.txt
@@ -0,0 +1,79 @@
+From: Bagas Sanjaya <bagasdotme@gmail.com>
+Date: Fri, 14 May 2021 13:26:33 +0700
+Subject: Tracking git.git
+Abstract: How to track git.git repository for Git development
+Content-type: text/asciidoc
+
+Tracking git.git
+================
+
+This short document shows how to track git.git (source code repository
+for Git) for purposes of Git development.
+
+Available Branches
+------------------
+
+There are several branches on git.git with different purposes:
+
+master::
+This is the most stable branch. Changes (topics) that are merged
+to master should have been stabilized in next and suitable for
+production use. Feature releases (vX.Y.0) are cut from this
+branch.
+
+next::
+This is where topics that haven't been yet merged to master are
+stabilized and tested for breakage and regressions. It gives
+a summary forecast of what next batch of topics that will be
+merged to master looks like.
+
+seen::
+This is the most bleeding edge branch where all excited
+developments happened. All proposed topics are queued in seen
+by the maintainer. However, these may be buggy (have breakage or
+regressions). When topics queued are deemed good and ready for
+inclusion, they are graduated to next for stabilization.
+
+maint::
+This branch is used for preparing maintenance releases. Bugfixes
+for feature release (vX.Y.0) are accumulated in maint. Then at
+some point, the tip of the branch is tagged with vX.Y.Z.
+
+todo::
+This contains helper tools written by the maintainer to ease
+maintaining Git. Also, "What's cooking in Git" messages are
+prepared in todo before being sent to the mailing list.
+
+Tracking
+--------
+
+If you don't have git.git clone handy, you can obtain one by:
+
+----
+$ git clone https://github.com/git/git.git git
+----
+
+Now you can start hacking your topics. Don't forget to read
+`Documentation/SubmittingPatches` for instructions on patch
+submission.
+
+After some time, there will be updates to git.git. First, fetch them:
+
+----
+$ git fetch origin
+----
+
+Then pull the updates.
+
+ - For `master`, `next`, `maint`, and `todo`, you can do fast-forward
+   pull:
+
+ $ git pull --ff-only
+
+ - For `seen`, DO NOT pull with `git pull`. This is because seen is
+   in constant flux, and most often your local seen is divergent from
+   the origin, caused by force-push from the maintainer. Attempting
+   to pull either via merge or rebase will most likely end in
+   conflict. Instead, pull by resetting the local seen to the origin:
+
+ $ git reset --hard origin/seen

base-commit: df6c4f722c94641d5a9ea5496511f7043433abc2
-- 
2.25.1