From: John Passaro <john.a.passaro@gmail.com>
To: Junio C Hamano <gitster@pobox.com>
Cc: John Passaro via GitGitGadget <gitgitgadget@gmail.com>,
git@vger.kernel.org, Patrick Steinhardt <ps@pks.im>
Subject: Re: [PATCH v3 2/3] builtin/tag.c: add --trailer arg
Date: Tue, 30 Apr 2024 17:48:14 -0400 [thread overview]
Message-ID: <CAJdN7Kggv-y8xRhdFanTyxa5wP-bG0omBPuETW6qijA67gn8oQ@mail.gmail.com> (raw)
In-Reply-To: <xmqqv83yrduw.fsf@gitster.g>
On Tue, Apr 30, 2024 at 12:53 PM Junio C Hamano <gitster@pobox.com> wrote:
>
Thanks for the feedback. Hoping for a couple points of clarification
then I'll put in one more version of this patch series.
> "John Passaro via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
> > From: John Passaro <john.a.passaro@gmail.com>
> >
> > git-tag currently supports interpreting trailers from an annotated tag
> > message, using --list --format="%(trailers)". There is no ergonomic way
> > to add trailers to an annotated tag message.
>
> Well said. Drop "currently", though. The usual way to compose a
> log message of this project is to
>
> - Give an observation on how the current system work in the present
> tense (so no need to say "Currently X is Y", just "X is Y"), and
> discuss what you perceive as a problem in it.
>
> - Propose a solution (optional---often, problem description
> trivially leads to an obvious solution in reader's minds).
>
> - Give commands to the codebase to "become like so".
>
> in this order.
Understood. In the most recent version of this patch, I updated the
message. However on second thought I think I'm gonna keep this on
the next submission of this patch (without "currently" of course).
>
> > In a previous patch, we refactored git-commit's implementation of its
> > --trailer arg to the trailer.h API. Let's use that new function to teach
> > git-tag the same --trailer argument, emulating as much of git-commit's
> > behavior as much as possible.
>
> Nicely described.
>
> > @@ -178,6 +179,19 @@ This option is only applicable when listing tags without annotation lines.
> > Implies `-a` if none of `-a`, `-s`, or `-u <key-id>`
> > is given.
> >
> > +--trailer <token>[(=|:)<value>]::
> > + Specify a (<token>, <value>) pair that should be applied as a
> > + trailer. (e.g. `git tag --trailer "Signed-off-by:T A Ger \
> > + <tagger@example.com>" --trailer "Helped-by:C O Mitter \
> > + <committer@example.com>"` will add the "Signed-off-by" trailer
> > + and the "Helped-by" trailer to the tag message.)
> > + The `trailer.*` configuration variables
> > + (linkgit:git-interpret-trailers[1]) can be used to define if
> > + a duplicated trailer is omitted, where in the run of trailers
> > + each trailer would appear, and other details.
> > + The trailers can be seen in `git tag --list` using
> > + `--format="%(trailers)"` placeholder.
>
> I can see this was copied-and-pasted from git-commit, but I am not
> sure if the ones used in the example are good fit for tag objects.
> What does Helped-by even mean in the context of an annotated tag?
I can see that the git project itself doesn't typically add trailers to tags.
If y'all were in that habit I imagine this feature would already be
implemented :-)
Nonetheless Signed-off-by or Approved-by is easy to imagine, for example
in an environment where multiple sign-offs are required (i.e. not just
the implicit
sign-off of the tagger). So we could just leave that in and be done with it.
I have a couple more hypothetical trailers that are both plausible and somewhat
generic; do any of them seem expressive enough to include in the docs?
* Tested-by: T E Ster <tester@example.com>
* Testing-assigned-to: T E Ster <tester@example.com>
* Scheduled-Deployment-Date: 2024-05-15 (or 1714500385 -05:00)
* Deployment-assigned-to: Oscar P Staff <ops@example.com>
* (for RC/alpha tags) Full-release-scheduled-for: 2024-06-05
There's also project-specific trailers. For example, on my team,
we use "Deploy-Strategy: ..." to tell CICD what deployment routines to run. This
is pretty specific to us but worth calling out. Maybe could translate to a
documentation example with something like "<Project-specific-trailer>: foo"
> > @@ -338,10 +344,22 @@ static void create_tag(const struct object_id *object, const char *object_ref,
> > }
> > close(fd);
> >
> > - if (launch_editor(path, buf, NULL)) {
> > - fprintf(stderr,
> > - _("Please supply the message using either -m or -F option.\n"));
> > - exit(1);
> > + if (trailer_args->nr && amend_file_with_trailers(path, trailer_args))
> > + die(_("unable to pass trailers to --trailers"));
> > +
> > + if (should_edit) {
> > + if (launch_editor(path, buf, NULL)) {
> > + fprintf(stderr,
> > + _("Please supply the message using either -m or -F option.\n"));
> > + exit(1);
> > + }
> > + } else if (trailer_args->nr) {
>
> When both should_edit and trailer_args->nr are true, this block will
> not be entered. We first do the "amend_file" thing, and then run an
> editor on it, and that is the end of the story in that case.
>
> When we do not have should_edit (e.g., -m "tag message" is given),
> we would have run "amend_file" thing on it to tweak the message,
> and we come in here.
>
> > + strbuf_reset(buf);
> > + if (strbuf_read_file(buf, path, 0) < 0) {
> > + fprintf(stderr,
> > + _("Please supply the message using either -m or -F option.\n"));
> > + exit(1);
>
> Does this error message make sense here in this context? The
> earlier one was introduced by 7198203a (editor.c: Libify
> launch_editor(), 2008-07-25)---after we fail to run the editor, as
> we somehow seem to be unable to run an editor, we suggest the user
> to give us a message in other ways. But this one is different. The
> user gave us in one of these other ways already instead of using an
> editor, but mucking with that with the "amend_file" thing somehow
> made it unreadable. Shouldn't it be more like
>
> die_errno(_("failed to read '%s'"), path);
>
> or something along that line?
I didn't realize that the first message is intended to augment more
expressive failure messages previously printed in launch_editor().
Knowing that, your suggested message will point users in the right
direction much more effectively. Also i guess die() probably preferable
since unlike launch_editor(), which may signal non-exceptional failure,
this error is more likely to be a bug.
However, in service of helping users find workarounds, shouldn't we tell them
--trailer may be the culprit?
> Failed to read '%s'. Try again without --trailer (use -e or -F to add trailers manually).
next prev parent reply other threads:[~2024-04-30 21:49 UTC|newest]
Thread overview: 37+ messages / expand[flat|nested] mbox.gz Atom feed top
2024-04-29 4:31 [PATCH] builtin/tag.c: add --trailer arg John Passaro via GitGitGadget
2024-04-29 6:50 ` Patrick Steinhardt
2024-04-29 14:50 ` John Passaro
2024-04-29 15:05 ` John Passaro
2024-04-29 17:07 ` Junio C Hamano
2024-04-29 15:29 ` Junio C Hamano
2024-04-29 16:38 ` John Passaro
2024-04-29 17:04 ` Junio C Hamano
2024-04-29 16:53 ` [PATCH v2] " John Passaro via GitGitGadget
2024-04-29 18:54 ` [PATCH v3 0/3] builtin/tag.c: add --trailer option John Passaro via GitGitGadget
2024-04-29 18:54 ` [PATCH v3 1/3] builtin/commit.c: refactor --trailer logic John Passaro via GitGitGadget
2024-04-30 5:54 ` Patrick Steinhardt
2024-04-30 16:38 ` Junio C Hamano
2024-04-29 18:54 ` [PATCH v3 2/3] builtin/tag.c: add --trailer arg John Passaro via GitGitGadget
2024-04-30 5:54 ` Patrick Steinhardt
2024-04-30 16:53 ` Junio C Hamano
2024-04-30 21:48 ` John Passaro [this message]
2024-04-30 22:23 ` Junio C Hamano
2024-05-05 18:59 ` John Passaro
2024-04-29 18:54 ` [PATCH v3 3/3] po: update git-tag translations John Passaro via GitGitGadget
2024-04-29 19:22 ` Junio C Hamano
2024-04-29 19:28 ` John Passaro
2024-04-30 14:41 ` [PATCH v4 0/3] builtin/tag.c: add --trailer option John Passaro via GitGitGadget
2024-04-30 14:41 ` [PATCH v4 1/3] builtin/commit.c: remove bespoke option callback John Passaro via GitGitGadget
2024-05-02 6:27 ` Patrick Steinhardt
2024-04-30 14:41 ` [PATCH v4 2/3] builtin/commit.c: refactor --trailer logic John Passaro via GitGitGadget
2024-05-02 6:27 ` Patrick Steinhardt
2024-04-30 14:41 ` [PATCH v4 3/3] builtin/tag.c: add --trailer option John Passaro via GitGitGadget
2024-05-02 6:27 ` [PATCH v4 0/3] " Patrick Steinhardt
2024-05-05 18:49 ` [PATCH v5 " John Passaro via GitGitGadget
2024-05-05 18:49 ` [PATCH v5 1/3] builtin/commit: use ARGV macro to collect trailers John Passaro via GitGitGadget
2024-05-07 15:38 ` John Passaro
2024-05-07 17:06 ` Junio C Hamano
2024-05-05 18:49 ` [PATCH v5 2/3] builtin/commit: refactor --trailer logic John Passaro via GitGitGadget
2024-05-05 18:49 ` [PATCH v5 3/3] builtin/tag: add --trailer option John Passaro via GitGitGadget
2024-05-06 5:40 ` [PATCH v5 0/3] builtin/tag.c: " Patrick Steinhardt
2024-05-06 17:52 ` Junio C Hamano
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: http://vger.kernel.org/majordomo-info.html
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=CAJdN7Kggv-y8xRhdFanTyxa5wP-bG0omBPuETW6qijA67gn8oQ@mail.gmail.com \
--to=john.a.passaro@gmail.com \
--cc=git@vger.kernel.org \
--cc=gitgitgadget@gmail.com \
--cc=gitster@pobox.com \
--cc=ps@pks.im \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://80x24.org/mirrors/git.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).