Re: [PATCH] messages: mark some strings with "up-to-date" not to touch

[Junio C Hamano <gitster@pobox.com>]

Eric Sunshine <ericsunshine@charter.net> writes:

> Let's do the second best thing, leave a short comment near them
> explaining why those strings should not be modified or localized.

I simply could not come up with a short and concise in-code comment
;-) What you picked looks good to me.

Thanks.  


>
> [es: make in-code comment more developer-friendly]
>
> Signed-off-by: Junio C Hamano <gitster@pobox.com>
> Signed-off-by: Eric Sunshine <sunshine@sunshineco.com>
> ---
>
> This is a reroll of Junio's[1] v1 which adds an in-code comment
> explaining that "up-to-date" messages in plumbing commands should not be
> changed, but doesn't explain _why_, which forces readers to dig through
> project history or the mailing list to understand the motivation. v2
> changes the comment to be more developer-friendly by adding the
> explanation directly to the comment.
>
> [1]: https://lore.kernel.org/git/xmqqjzofec0e.fsf@gitster.g/
>
> Range-diff:
> 1:  36596051c9 ! 1:  782169e0b1 messages: mark some strings with "up-to-date" not to touch
>     @@ Commit message
>          the commit is impossible to ask "git blame" to link back to the
>          commit that did not touch them.
>      
>     -    Let's do the second best thing, leave a short comment near them, to
>     -    make it possible for those who are motivated enough to find out why
>     -    we decided to tell them "do not modify".
>     +    Let's do the second best thing, leave a short comment near them
>     +    explaining why those strings should not be modified or localized.
>     +
>     +    [es: make in-code comment more developer-friendly]
>      
>          Signed-off-by: Junio C Hamano <gitster@pobox.com>
>     +    Signed-off-by: Eric Sunshine <sunshine@sunshineco.com>
>      
>       ## builtin/send-pack.c ##
>      @@ builtin/send-pack.c: int cmd_send_pack(int argc, const char **argv, const char *prefix)
>       	}
>       
>       	if (!ret && !transport_refs_pushed(remote_refs))
>     -+		/* do not modify this string */
>     ++		/* stable plumbing output; do not modify or localize */
>       		fprintf(stderr, "Everything up-to-date\n");
>       
>       	return ret;
>     @@ http-push.c: int cmd_main(int argc, const char **argv)
>       
>       		if (oideq(&ref->old_oid, &ref->peer_ref->new_oid)) {
>       			if (push_verbosely)
>     -+				/* do not modify this string */
>     ++				/* stable plumbing output; do not modify or localize */
>       				fprintf(stderr, "'%s': up-to-date\n", ref->name);
>       			if (helper_status)
>       				printf("ok %s up to date\n", ref->name);
>     @@ http-push.c: int cmd_main(int argc, const char **argv)
>       				 * commits at the remote end and likely
>       				 * we were not up to date to begin with.
>       				 */
>     -+				/* do not modify this string */
>     ++				/* stable plumbing output; do not modify or localize */
>       				error("remote '%s' is not an ancestor of\n"
>       				      "local '%s'.\n"
>       				      "Maybe you are not up-to-date and "
>     @@ transport.c: int transport_push(struct repository *r,
>       	if (porcelain && !push_ret)
>       		puts("Done");
>       	else if (!quiet && !ret && !transport_refs_pushed(remote_refs))
>     -+		/* do not modify this string */
>     ++		/* stable plumbing output; do not modify or localize */
>       		fprintf(stderr, "Everything up-to-date\n");
>       
>       done:
>
>  builtin/send-pack.c | 1 +
>  http-push.c         | 2 ++
>  transport.c         | 1 +
>  3 files changed, 4 insertions(+)
>
> diff --git a/builtin/send-pack.c b/builtin/send-pack.c
> index b7183be970..3df9eaad09 100644
> --- a/builtin/send-pack.c
> +++ b/builtin/send-pack.c
> @@ -333,6 +333,7 @@ int cmd_send_pack(int argc, const char **argv, const char *prefix)
>  	}
>  
>  	if (!ret && !transport_refs_pushed(remote_refs))
> +		/* stable plumbing output; do not modify or localize */
>  		fprintf(stderr, "Everything up-to-date\n");
>  
>  	return ret;
> diff --git a/http-push.c b/http-push.c
> index b4d0b2a6aa..12d1113741 100644
> --- a/http-push.c
> +++ b/http-push.c
> @@ -1851,6 +1851,7 @@ int cmd_main(int argc, const char **argv)
>  
>  		if (oideq(&ref->old_oid, &ref->peer_ref->new_oid)) {
>  			if (push_verbosely)
> +				/* stable plumbing output; do not modify or localize */
>  				fprintf(stderr, "'%s': up-to-date\n", ref->name);
>  			if (helper_status)
>  				printf("ok %s up to date\n", ref->name);
> @@ -1871,6 +1872,7 @@ int cmd_main(int argc, const char **argv)
>  				 * commits at the remote end and likely
>  				 * we were not up to date to begin with.
>  				 */
> +				/* stable plumbing output; do not modify or localize */
>  				error("remote '%s' is not an ancestor of\n"
>  				      "local '%s'.\n"
>  				      "Maybe you are not up-to-date and "
> diff --git a/transport.c b/transport.c
> index bd7899e9bf..df518ead70 100644
> --- a/transport.c
> +++ b/transport.c
> @@ -1467,6 +1467,7 @@ int transport_push(struct repository *r,
>  	if (porcelain && !push_ret)
>  		puts("Done");
>  	else if (!quiet && !ret && !transport_refs_pushed(remote_refs))
> +		/* stable plumbing output; do not modify or localize */
>  		fprintf(stderr, "Everything up-to-date\n");
>  
>  done: