[PATCH v2 0/2] doc: refs: put ref migration warning under the command

[kristofferhaugsbakk@fastmail.com]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

Topic name (applied): doc-refs-migrate-limitations

Topic summary: Put ref migration warning as an admonition under the command
so that it is visible.

That’s the first patch. The second patch adds a missing `linkgit` since it
touches that same warning text.

I have two other patches that are not included here. They are unrelated
cleanups that I will post later. Here are the commit subjects and the first
paragraph so that you can see what they are about:

• doc: refs: wrap standalone placeholders in underscores

  This is a synopsis manpage which means that standalone placeholders[1]
  are supposed to use underscores (_), not backticks (`).[2]
• doc: refs: use inline-verbatim throughout

  Use inline-verbatim backticks (`) for literal commands, options, and
  subcommands listed under the “Commands” section.

§ Cc list

The two people that I have the impression that have worked most on
this command.

§ Changes in v2

• Patch 1/2: Use Warning admonition instead of Caution
• Patch 2/2: Add Ack

§ Link to v1

https://lore.kernel.org/git/CV_git_ref_migration_warning.b09@msgid.xyz/

[1/2] doc: refs: put ref migration warning under the command
[2/2] doc: refs: linkgit to git-maintenance(1)

 Documentation/git-refs.adoc | 30 +++++++++++++++---------------
 1 file changed, 15 insertions(+), 15 deletions(-)

Interdiff against v1:
diff --git a/Documentation/git-refs.adoc b/Documentation/git-refs.adoc
index 1ec26be0b4f..9063892651e 100644
--- a/Documentation/git-refs.adoc
+++ b/Documentation/git-refs.adoc
@@ -36,7 +36,7 @@ COMMANDS
 `migrate`::
 	Migrate ref store between different formats.
 +
-[CAUTION]
+[WARNING]
 --
 The ref format migration has several known limitations in its current form:
 
Range-diff against v1:
1:  cc4d9ca5006 ! 1:  8a6415e2d9b doc: refs: put ref migration warning under the command
    @@ Commit message
         `migrate` description in order to see the “known limitations” for
         it. This is important information since the text says that concurrent
         writes can lead to an inconsistent migrated state. Let’s move that text
    -    up to the command description and put it inside a Caution admonition.
    +    up to the command description and put it inside a Warning admonition.
     
         This section made sense when it was added in 25a0023f (builtin/refs:
         new command to migrate ref storage formats, 2024-06-06); `migrate` was
    @@ Documentation/git-refs.adoc: COMMANDS
      `migrate`::
      	Migrate ref store between different formats.
     ++
    -+[CAUTION]
    ++[WARNING]
     +--
     +The ref format migration has several known limitations in its current form:
     +
2:  7265de45c9d ! 2:  801a3d7f539 doc: refs: linkgit to git-maintenance(1)
    @@ Metadata
      ## Commit message ##
         doc: refs: linkgit to git-maintenance(1)
     
    +    Acked-by: Patrick Steinhardt <ps@pks.im>
         Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
     
      ## Documentation/git-refs.adoc ##

base-commit: 13c7afec212fc97ce257d15601659314c6673d6c
-- 
2.54.0.22.g9e26862b904