| Message ID | cover.1729017728.git.code@khaugsbakk.name (mailing list archive) |
|---|---|
| Headers | show |
| Series | doc: update-ref: amend old material and discuss symrefs | expand |
On Tue Oct 15, 2024 at 21:03, <kristofferhaugsbakk@fastmail.com> wrote: > From: Kristoffer Haugsbakk <code@khaugsbakk.name> > > (See the previous email for the context) > > This series removes or moves some old material in the update-ref doc and > improves the discussion of symrefs, opting for a high-level description > with some redundancy (see patch 5/6) in order to avoid a reported > mistake/confusion. > > The end goal (after all patches are applied): > > • First paragraph (in Description) describes the first form > • Second paragraph the second form > • Third paragraph mentions symrefs and explains why `--stdin` supports > them > • A new section whither the symlink (FS) vs. symrefs (`ref: ` files… or > strings nowadays with the different formats that refs can have?) > discussion is moved > • Link update-ref to symbolic-ref and vice versa Thanks, it seems much more clear to me this way! Reviewed-by: Bence Ferdinandy <bence@ferdinandy.com>
On Tue, Oct 15, 2024 at 09:03:09PM +0200, kristofferhaugsbakk@fastmail.com wrote: > Kristoffer Haugsbakk (6): > doc: update-ref: drop “flag” > doc: update-ref: remove safety paragraphs > doc: update-ref: demote symlink to last section > doc: update-ref: remove confusing paragraph > doc: update-ref: discuss symbolic links > doc: mutually link update-ref and symbolic-ref > > Documentation/git-symbolic-ref.txt | 4 +++ > Documentation/git-update-ref.txt | 48 +++++++++++++----------------- > 2 files changed, 25 insertions(+), 27 deletions(-) Thanks for working on this. These changes generally looked good to me (although seeing smart-quotes in the commit messages was a little surprising ;-)). I'm making a note for the next WC report to expect a new round that corrects the subject line of the penultimate patch "doc: update-ref: discuss symbolic links". As a general note, prefixing commits with "doc: update-ref: " is a little strange to me. I think I might have instead written: Documentation/git-update-ref.txt: remove safety paragraphs , and so on. I left a couple of other small notes, but I don't think any of them are urgent to address, though it would be nice. Thanks for working on this and improving Git's documentation. Thanks, Taylor
On Wed, Oct 16, 2024, at 22:54, Taylor Blau wrote: > Thanks for working on this. These changes generally looked good to me > (although seeing smart-quotes in the commit messages was a little > surprising ;-)). > > I'm making a note for the next WC report to expect a new round that > corrects the subject line of the penultimate patch "doc: update-ref: > discuss symbolic links". > > As a general note, prefixing commits with "doc: update-ref: " is a > little strange to me. I think I might have instead written: > > Documentation/git-update-ref.txt: remove safety paragraphs > > , and so on. I left a couple of other small notes, but I don't think any > of them are urgent to address, though it would be nice. > > Thanks for working on this and improving Git's documentation. > > Thanks, > Taylor Thanks for the review overview. I’ll change the subjects/area parts in the next round. I looked through the commit subjects for `Documentation` in the past and, seeing several different styles, landed on one of the shorter ones. According to my recollection.
From: Kristoffer Haugsbakk <code@khaugsbakk.name> (See the previous email for the context) This series removes or moves some old material in the update-ref doc and improves the discussion of symrefs, opting for a high-level description with some redundancy (see patch 5/6) in order to avoid a reported mistake/confusion. The end goal (after all patches are applied): • First paragraph (in Description) describes the first form • Second paragraph the second form • Third paragraph mentions symrefs and explains why `--stdin` supports them • A new section whither the symlink (FS) vs. symrefs (`ref: ` files… or strings nowadays with the different formats that refs can have?) discussion is moved • Link update-ref to symbolic-ref and vice versa Kristoffer Haugsbakk (6): doc: update-ref: drop “flag” doc: update-ref: remove safety paragraphs doc: update-ref: demote symlink to last section doc: update-ref: remove confusing paragraph doc: update-ref: discuss symbolic links doc: mutually link update-ref and symbolic-ref Documentation/git-symbolic-ref.txt | 4 +++ Documentation/git-update-ref.txt | 48 +++++++++++++----------------- 2 files changed, 25 insertions(+), 27 deletions(-) base-commit: ef8ce8f3d4344fd3af049c17eeba5cd20d98b69f