Merge branch 'gitgitgadget:master' into mm/ci-diagnose-hangs

Author: mmontalbo

.b4-config

@@ -0,0 +1,6 @@
+# Note that these are default values that you can tweak via the typical
+# git-config(1) machinery. You thus shouldn't ever have to change this file.
+# See also https://b4.docs.kernel.org/en/latest/config.html.
+[b4]
+send-same-thread = shallow
+prep-cover-template = ./.b4-cover-template

.b4-cover-template

@@ -0,0 +1,11 @@
+${cover}
+
+---
+${shortlog}
+
+${diffstat}
+
+${range_diff}
+---
+base-commit: ${base_commit}
+${prerequisites}

Documentation/MyFirstContribution.adoc

@@ -790,7 +790,7 @@ We can note a few things:
   v3", etc. in place of "PATCH". For example, "[PATCH v2 1/3]" would be the first of
   three patches in the second iteration. Each iteration is sent with a new cover
   letter (like "[PATCH v2 0/3]" above), itself a reply to the cover letter of the
-  previous iteration (more on that below).
+  first iteration (more on that below).
 
 NOTE: A single-patch topic is sent with "[PATCH]", "[PATCH v2]", etc. without
 _i_/_n_ numbering (in the above thread overview, no single-patch topic appears,
@@ -833,7 +833,7 @@ This patchset is part of the MyFirstContribution tutorial and should not
 be merged.
 ----
 
-At this point the tutorial diverges, in order to demonstrate two
+At this point the tutorial diverges, in order to demonstrate three
 different methods of formatting your patchset and getting it reviewed.
 
 The first method to be covered is GitGitGadget, which is useful for those
@@ -845,9 +845,14 @@ more fine-grained control over the emails to be sent. This method requires some
 setup which can change depending on your system and will not be covered in this
 tutorial.
 
+The third method to be covered is `b4`, which builds on top of `git
+format-patch` and `git send-email`. This method is the recommended way to
+submit patches via mail as it automates a lot of the bookkeeping required by
+`git send-email`.
+
 Regardless of which method you choose, your engagement with reviewers will be
-the same; the review process will be covered after the sections on GitGitGadget
-and `git send-email`.
+the same; the review process will be covered after the sections on GitGitGadget,
+`git send-email` and `b4`.
 
 [[howto-ggg]]
 == Sending Patches via GitGitGadget
@@ -1214,7 +1219,7 @@ between your last version and now, if it's something significant. You do not
 need the exact same body in your second cover letter; focus on explaining to
 reviewers the changes you've made that may not be as visible.
 
-You will also need to go and find the Message-ID of your previous cover letter.
+You will also need to go and find the Message-ID of your first cover letter.
 You can either note it when you send the first series, from the output of `git
 send-email`, or you can look it up on the
 https://lore.kernel.org/git[mailing list]. Find your cover letter in the
@@ -1227,8 +1232,8 @@ Message-ID: <foo.12345.author@example.com>
 
 Your Message-ID is `<foo.12345.author@example.com>`. This example will be used
 below as well; make sure to replace it with the correct Message-ID for your
-**previous cover letter** - that is, if you're sending v2, use the Message-ID
-from v1; if you're sending v3, use the Message-ID from v2.
+**first cover letter** - that is, for any subsequent version that you send,
+always use the Message-ID from v1.
 
 While you're looking at the email, you should also note who is CC'd, as it's
 common practice in the mailing list to keep all CCs on a thread. You can add
@@ -1296,6 +1301,87 @@ index 88f126184c..38da593a60 100644
 2.21.0.392.gf8f6787159e-goog
 ----
 
+[[howto-b4]]
+== Sending Patches with `b4`
+
+`b4` is a tool that builds on top of `git format-patch` and `git send-email`.
+It automates much of the bookkeeping involved in sending a patch series to a
+mailing-list-based project.
+
+Refer to the https://b4.docs.kernel.org/[b4 documentation] for a full reference.
+
+[[prep-b4]]
+=== Preparing a Patch Series
+
+`b4` tracks your patch series as a branch. To start tracking the `psuh` branch
+you have been working on, run:
+
+----
+$ b4 prep --enroll master
+----
+
+This enrolls the current branch, using `master` as the base of the topic. `b4`
+manages the cover letter as part of the branch, so you can edit it at any time
+with:
+
+----
+$ b4 prep --edit-cover
+----
+
+The cover letter not only tracks the content of the top-level mail, but also
+the set of recipients. You can add recipients by adding `To:` and `Cc:`
+trailer lines.
+
+[[send-b4]]
+=== Sending the Patches
+
+Before sending the series out for real, you can inspect what `b4` would send by
+passing `--dry-run`:
+
+----
+$ b4 send --dry-run
+----
+
+Once you are happy with the result, send the series with:
+
+----
+$ b4 send
+----
+
+[[v2-b4]]
+=== Sending v2
+
+When you are ready to send a new iteration of your series, refine your
+patches as usual using linkgit:git-rebase[1]. Note that you typically want to
+rebase on top of the cover letter. You can configure an alias to enable easy
+rebases going forward:
+
+---
+$ git config set alias.b4-rebase 'rebase "HEAD^{/--- b4-submit-tracking ---}"'
+$ git b4-rebase -i
+---
+
+Before sending out the new version you should also update the cover letter with
+`b4 prep --edit-cover` to note the relevant changes compared to the previous
+version. You can inspect the changes between the two versions with `b4 prep
+--compare-to=v1`.
+
+Same as with the first version, you can use `b4 send` to send out the second
+version. `b4` automatically bumps the version to `v2`, generates the range-diff
+against the previous iteration, and threads the new series as a reply to the
+cover letter of the first version.
+
+[[configure-b4]]
+=== Configure b4
+
+`b4` can be configured via linkgit:git-config[1]. In addition to that, projects
+can have their own set of defaults in `.b4-config` in the root tree, which also
+uses Git's config format. The user's configuration always takes precedence over
+the per-project defaults.
+
+Refer to the https://b4.docs.kernel.org/en/latest/config.html[b4 config documentation]
+for more information on the available options.
+
 [[now-what]]
 == My Patch Got Emailed - Now What?
 
@@ -1330,18 +1416,42 @@ previous one" patches over 2 days), reviewers would strongly prefer if a
 single polished version came 2 days later instead, and that version with
 fewer mistakes were the only one they would need to review.
 
+This consideration applies not only when going from the initial patch to v2,
+but also to later iterations of the same series. There is no fixed rule for how
+long to wait before sending a new version. A useful default is to send at most
+one new version of the same patch series per day. This gives multiple reviewers
+time to comment, gives reviewers across time zones a fair chance to
+participate, lets you batch feedback together, and gives you time to think
+through the comments you received. Knowing that you should not immediately send
+another version also encourages you to review the patches more carefully before
+sending them, catch small mistakes such as typos and off-by-one errors
+yourself, and let reviewers spend more of their attention on design,
+algorithms, and other substantial issues.
+
+The right timing depends on the topic and the feedback. Larger series usually
+need more review time. If the only comments so far are minor, such as typo
+fixes, it often makes sense to wait a little longer in case deeper reviews are
+still coming. If the comments call for substantial rework, do not rush out an
+updated version before you have reviewed the larger changes carefully. Instead,
+reply to the review that prompted the rewrite, say that you are preparing a
+substantial rework, and mention which parts of the current series will become
+obsolete so reviewers can avoid spending time on them until the updated series
+is ready.
+
 
 [[reviewing]]
 === Responding to Reviews
 
 After a few days, you will hopefully receive a reply to your patchset with some
 comments. Woohoo! Now you can get back to work.
 
-It's good manners to reply to each comment, notifying the reviewer that you have
-made the change suggested, feel the original is better, or that the comment
-inspired you to do something a new way which is superior to both the original
-and the suggested change. This way reviewers don't need to inspect your v2 to
-figure out whether you implemented their comment or not.
+It's good manners to reply to each comment in the mailing list discussion
+instead of letting the next version of your patch be your only response. Tell
+the reviewer whether you plan to make the suggested change, keep the original,
+or pursue a different approach. This way reviewers can respond to your reasoning
+before you spend time preparing a version they may not agree with, and later do
+not need to inspect your v2 to figure out whether you implemented their comment
+or not.
 
 Reviewers may ask you about what you wrote in the patchset, either in
 the proposed commit log message or in the changes themselves.  You

Documentation/RelNotes/2.56.0.adoc

@@ -0,0 +1,113 @@
+Git v2.56 Release Notes
+=======================
+
+UI, Workflows & Features
+------------------------
+
+ * Advice shown by "git status" when the local branch is behind or has
+   diverged from its push branch has been updated to suggest "git pull
+   <remote> <branch>".
+
+ * The handling of promisor-remote protocol capability has been updated
+   to allow the other side to add to the list of promisor remotes via the
+   'promisor.acceptFromServerURL' configuration variable.
+
+ * The 'ort' merge backend has been hardened against corrupt trees by
+   ensuring it aborts under appropriate error conditions.
+
+ * The `fetch.followRemoteHEAD` configuration variable has been added to
+   provide a default for the per-remote `remote.<name>.followRemoteHEAD`
+   setting.
+
+ * "git log --follow" has been updated to better handle non-linear
+   history, in which the path being tracked gets renamed differently in
+   multiple history lines.
+
+ * The "git repo info" command has been taught new keys to output both
+   absolute and relative paths for "gitdir" and "commondir", supported by
+   a new path-formatting helper extracted from "git rev-parse".
+
+
+Performance, Internal Implementation, Development Support etc.
+--------------------------------------------------------------
+
+ * The refactoring of 'setup.c' has been continued to drop remaining
+   global state (`git_work_tree_cfg`, `is_bare_repository_cfg`), updating
+   `is_bare_repository()` to no longer implicitly rely on
+   `the_repository`.
+
+ * Project-specific configuration for b4 has been introduced, and the
+   documentation has been updated to recommend using it as a
+   streamlined method for submitting patches.
+
+ * The default format path of git cat-file --batch has been optimized
+   to use strbuf_add_oid_hex() and strbuf_add_uint() instead of
+   strbuf_addf(), yielding a noticeable speedup.
+
+ * Commands that list branches and tags (like git branch and git tag)
+   have been optimized to pass the namespace prefix when initializing
+   their ref iterator, avoiding a loose-ref scaling regression in
+   repositories with many unrelated loose references.
+
+ * The packed object source has been refactored into a proper struct
+   odb_source.
+
+ * The global configuration variables protect_hfs and protect_ntfs have
+   been migrated into struct repo_config_values to tie them to
+   per-repository configuration state.
+
+ * The trailer sections in SubmittingPatches have been updated to
+   encourage use of standard trailers.
+
+ * The documentation in SubmittingPatches has been updated to clarify how
+   patch contributors should respond to design and viability critiques,
+   and how the resolution of such critiques should be recorded in the
+   final commit messages.
+
+ * The pack-objects command has been updated to support reachability
+   bitmaps and delta-islands concurrently with the `--path-walk` option,
+   allowing faster packaging by falling back to path-walk when bitmaps
+   cannot fully satisfy the request.
+
+ * Documentation on community contribution guidelines has been updated to
+   encourage replying to review comments before rerolling, and to advise
+   a default limit of at most one reroll per day to give reviewers across
+   different time zones enough time to participate.
+
+
+Fixes since v2.55
+-----------------
+
+ * A regression in the error diagnosis code for invalid .git files has
+   been fixed, avoiding a potential NULL-pointer crash when reporting
+   that a .git file does not point to a valid repository.
+   (merge 54a441bcea jk/setup-gitfile-diag-fix later to maint).
+
+ * Support for hashing loose or packed objects larger than 4GB on Windows
+   and other LLP64 platforms has been improved by converting object header
+   buffers and data-handling functions from 'unsigned long' to 'size_t'.
+   (merge d99e13d0be po/hash-object-size-t later to maint).
+
+ * The display of the rebase todo list in "git status" has been
+   improved to correctly abbreviate object IDs for more commands and
+   avoid misinterpreting refs as object IDs.
+   (merge 6f34e5f9e3 pw/status-rebase-todo later to maint).
+
+ * Reference backend configuration has been updated to load lazily to
+   avoid recursive calls during repository initialization when 'onbranch'
+   configuration conditions are evaluated. This has also fixed a memory
+   leak and allowed the unused `chdir_notify_reparent()` machinery to be
+   dropped.
+   (merge d6522d01df ps/refs-onbranch-fixes later to maint).
+
+ * The connectivity check has been refactored to search for promisor
+   objects in a generic way using the object database interface,
+   rather than iterating packfiles directly. This allows connectivity
+   checks to work properly in repositories that do not use packfiles.
+   (merge 66ee9cb930 ps/connected-generic-promisor-checks later to maint).
+
+ * A test checking interactions between git rebase --quit and
+   autostash in t3420-rebase-autostash.sh has been corrected to use
+   test_path_is_missing instead of ! grep on a file that shouldn't
+   exist in the conflicted state.
+   (merge eaad121fef sg/t3420-do-not-grep-in-missing-file later to maint).