[PATCH] help.c: add a compatibility comment to cmd_version()

[PATCH] help.c: add a compatibility comment to cmd_version()

[David Aguilar]

External projects have been known to parse the output of
"git version".  Help prevent future authors from changing
its format by adding a comment to its implementation.

Signed-off-by: David Aguilar <davvid@gmail.com>
---
 help.c | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/help.c b/help.c
index 1dfa0b0..02ba043 100644
--- a/help.c
+++ b/help.c
@@ -397,6 +397,10 @@ const char *help_unknown_cmd(const char *cmd)
 
 int cmd_version(int argc, const char **argv, const char *prefix)
 {
+	/*
+	 * The format of this string should be kept stable for compatibility
+	 * with external projects that rely on the output of "git version".
+	 */
 	printf("git version %s\n", git_version_string);
 	return 0;
 }
-- 
1.8.2.1.652.ge104b5e

Re: [PATCH] help.c: add a compatibility comment to cmd_version()

[Junio C Hamano]

David Aguilar <davvid@gmail.com> writes:

> External projects have been known to parse the output of
> "git version".  Help prevent future authors from changing
> its format by adding a comment to its implementation.
>
> Signed-off-by: David Aguilar <davvid@gmail.com>
> ---
>  help.c | 4 ++++
>  1 file changed, 4 insertions(+)
>
> diff --git a/help.c b/help.c
> index 1dfa0b0..02ba043 100644
> --- a/help.c
> +++ b/help.c
> @@ -397,6 +397,10 @@ const char *help_unknown_cmd(const char *cmd)
>  
>  int cmd_version(int argc, const char **argv, const char *prefix)
>  {
> +	/*
> +	 * The format of this string should be kept stable for compatibility
> +	 * with external projects that rely on the output of "git version".
> +	 */
>  	printf("git version %s\n", git_version_string);
>  	return 0;
>  }

Will queue; thanks.

Re: [PATCH] help.c: add a compatibility comment to cmd_version()

[Philip Oakley]

From: "David Aguilar" <davvid@gmail.com>
Sent: Tuesday, April 16, 2013 9:33 PM
> External projects have been known to parse the output of
> "git version".  Help prevent future authors from changing
> its format by adding a comment to its implementation.
>
> Signed-off-by: David Aguilar <davvid@gmail.com>
> ---
> help.c | 4 ++++
> 1 file changed, 4 insertions(+)
>
> diff --git a/help.c b/help.c
> index 1dfa0b0..02ba043 100644
> --- a/help.c
> +++ b/help.c
> @@ -397,6 +397,10 @@ const char *help_unknown_cmd(const char *cmd)
>
> int cmd_version(int argc, const char **argv, const char *prefix)
> {
> + /*
> + * The format of this string should be kept stable for compatibility
> + * with external projects that rely on the output of "git version".

Shouldn't the expected format of our known external project also be 
indicated?
Or mention "such as git gui"?

> + */
>  printf("git version %s\n", git_version_string);
>  return 0;
> }
> -- 
> 1.8.2.1.652.ge104b5e
>
> --
> To unsubscribe from this list: send the line "unsubscribe git" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html
>
>
> -----
> No virus found in this message.
> Checked by AVG - www.avg.com
> Version: 2013.0.3272 / Virus Database: 3162/6248 - Release Date: 
> 04/16/13
> 

Re: [PATCH] help.c: add a compatibility comment to cmd_version()

[Junio C Hamano]

"Philip Oakley" <philipoakley@iee.org> writes:

>> int cmd_version(int argc, const char **argv, const char *prefix)
>> {
>> + /*
>> + * The format of this string should be kept stable for compatibility
>> + * with external projects that rely on the output of "git version".
>
> Shouldn't the expected format of our known external project also be
> indicated?
> ...
>>  printf("git version %s\n", git_version_string);

It is fairly clear from the commented code that the only guarantee
they will be getting is that it begins with a string "git version ".
git_version_string[] has anything of the builder's choice.  I am not
sure if there anything more to "indicate".

Really, if you run

	$ git version

and you get "Git Source Code Management Version 3.56" from its
output, it is likely that the version is very different from what
you know, and you should not assume any your assumption would hold.

> Or mention "such as git gui"?

I do not see what it would buy us.  It is not like it is OK as long
as we upadte Git gui at the same time.

Re: [PATCH] help.c: add a compatibility comment to cmd_version()

[Philip Oakley]

From: "Junio C Hamano" <gitster@pobox.com>
Sent: Tuesday, April 16, 2013 11:35 PM
> "Philip Oakley" <philipoakley@iee.org> writes:
>
>>> int cmd_version(int argc, const char **argv, const char *prefix)
>>> {
>>> + /*
>>> + * The format of this string should be kept stable for 
>>> compatibility
>>> + * with external projects that rely on the output of "git version".

This 'tantalizes without telling', the same complaint that is given 
often for over-succinct commit messages.
How about
    * E.g. git gui uses the extended regular expression "^git version 
[1-9]+(\.[0-9]+)+.*"
    * to check for an acceptable version string.

The ERE is from git-gui.sh:L958.

>>
>> Shouldn't the expected format of our known external project also be
>> indicated?
>> ...
>>>  printf("git version %s\n", git_version_string);
>
> It is fairly clear from the commented code that the only guarantee
> they will be getting is that it begins with a string "git version ".

I read the code the opposite way. It says "This is the code to be 
changed" if you (anyone doing tweaks) want a special version string.

> git_version_string[] has anything of the builder's choice.  I am not
> sure if there anything more to "indicate".
>
> Really, if you run
>
> $ git version
>
> and you get "Git Source Code Management Version 3.56" from its
> output, it is likely that the version is very different from what
> you know, and you should not assume any your assumption would hold.

Again I am reading this from the opposite side. There would be no 
assumption of difference if it _passed_ the test scripts. Unfortunately 
it wouldn't be friendly to other tools (like git gui). Hence my 
suggestion of the basic test that a "passing" git would produce a 
consistent version string. It still allows the supplier's suffixes to be 
added, but not the prefixes. The test suite tests that git is 'good 
enough for most usages and picks up regressions. No?

Obvious inconsistent special versions would fail in many other places.
>
>> Or mention "such as git gui"?
>
> I do not see what it would buy us.  It is not like it is OK as long
> as we upadte Git gui at the same time.

Philip 

Re: [PATCH] help.c: add a compatibility comment to cmd_version()

[Junio C Hamano]

"Philip Oakley" <philipoakley@iee.org> writes:

> How about
>    * E.g. git gui uses the extended regular expression "^git version
> [1-9]+(\.[0-9]+)+.*"
>    * to check for an acceptable version string.
>
> The ERE is from git-gui.sh:L958.

That is exactly the kind of guarantee we do _not_ want to give.

> ... Hence my suggestion of the basic test that a "passing" git
> would produce a consistent version string.

I have been assuming that you are trying to avoid an exchange like
this one we had in the past:

  http://thread.gmane.org/gmane.comp.version-control.git/216923/focus=217007

I also have been assuming that you are pushing to limit the possible
versioning scheme, but I do not know what that extra limitation
would achieve in the real world.

By sticking to the pattern "git gui" happens to use, "git gui" may
be able to guess that the next version of Git says it is verison
"1.8.3".  That is the _only_ thing your "test" buys.

But having parsed the "1.8.3" substring out of it, "git gui" does
not know anything about what 1.8.3 gives it.  As far as it is
concerned, it is a version whose "git version" output it has never
seen (unless it has been kept up to date with the development of
Git).

By matching against "git version [1-9]+(\.[0-9]+)+", it is accepting
that future versions may break assumptions it makes for some known
versions (which is warranted) and all future versions (which is
unwarranted) of Git.  Maybe the version 2.0 of Git adds all changes
in the directory "d", including removals, when you say "git add d",
but it may have assumed that with Git version 1.5.0 or newer, saying
"git add d" would result in added and modified inside that directory
getting updated in the index, but paths removed from the working
tree will stay in the index.

The only thing the scripts that read from the output of "git
version" can reliably tell is if it is interacting with a version of
Git it knows about.  If it made any unwarranted assumption on the
versions it hasn't seen, it has to be fixed in "git gui" _anyway_.

Of course, we would not change the output of "git version"
willy-nilly without good reason, but that is a different topic.

So I do not know what you want to achieve in the real world with 
that extra limitation on the "git version" output format.

Maybe you are proposing something else.  I dunno.

Re: [PATCH] help.c: add a compatibility comment to cmd_version()

[Philip Oakley]

From: "Junio C Hamano" <gitster@pobox.com>
Sent: Thursday, April 18, 2013 1:13 AM
> "Philip Oakley" <philipoakley@iee.org> writes:
>
>> How about
>>    * E.g. git gui uses the extended regular expression "^git version
>> [1-9]+(\.[0-9]+)+.*"
>>    * to check for an acceptable version string.
>>
>> The ERE is from git-gui.sh:L958.
>
> That is exactly the kind of guarantee we do _not_ want to give.
>

So you are trying to avoid giving _any_ "guarantee" about what visible 
manifestation a user may obtain about a system that passes the test 
suite we have set out. I was hoping we could give a basic minimum 
indication of the expected style of the version string for a git which 
*passes* our tests. But like you say, it doesn't form a real guarantee - 
caveat emptor still applies.

>> ... Hence my suggestion of the basic test that a "passing" git
>> would produce a consistent version string.
>
> I have been assuming that you are trying to avoid an exchange like
> this one we had in the past:
>
> 
> http://thread.gmane.org/gmane.comp.version-control.git/216923/focus=217007
>
In a sense yes. As David noted, others do attempt to trust us via our 
current version string format. I thought it worthwhile (given my earlier 
'mistake' in 216923/focus=216925) to suggest such a basic indication of 
our current string style.

> I also have been assuming that you are pushing to limit the possible
> versioning scheme, but I do not know what that extra limitation
> would achieve in the real world.
>
> By sticking to the pattern "git gui" happens to use, "git gui" may
> be able to guess that the next version of Git says it is verison
> "1.8.3".  That is the _only_ thing your "test" buys.
>
> But having parsed the "1.8.3" substring out of it, "git gui" does
> not know anything about what 1.8.3 gives it.  As far as it is
> concerned, it is a version whose "git version" output it has never
> seen (unless it has been kept up to date with the development of
> Git).

You are focusssing on the wrong side of issue (from my viewpoint).
If my earlier patch had gone in, it would have passsed our tests but not 
played nicely with the community tools. That would have been IMHO a 
regression, so from my viewpoint I believed it was worth having a test 
to avoid such a 'regression'.

>
> By matching against "git version [1-9]+(\.[0-9]+)+", it is accepting
> that future versions may break assumptions it makes for some known
> versions (which is warranted) and all future versions (which is
> unwarranted) of Git.  Maybe the version 2.0 of Git adds all changes
> in the directory "d", including removals, when you say "git add d",
> but it may have assumed that with Git version 1.5.0 or newer, saying
> "git add d" would result in added and modified inside that directory
> getting updated in the index, but paths removed from the working
> tree will stay in the index.

If it was a gross incompatibility then (a) we are likley to be 
signalling it for a while, and (b) other tools would need updating as 
well, and they would hope that they could 'read' the version in a 
consistent style. We would also still have the choice of changing our 
existing string style, which would explicitly signal a change via the 
test fail.

>
> The only thing the scripts that read from the output of "git
> version" can reliably tell is if it is interacting with a version of
> Git it knows about.  If it made any unwarranted assumption on the
> versions it hasn't seen, it has to be fixed in "git gui" _anyway_.
>
> Of course, we would not change the output of "git version"
> willy-nilly without good reason, but that is a different topic.
Ah. I thought it was the [original] topic. I was calibrating the 
willy-nillyness ;-)

>
> So I do not know what you want to achieve in the real world with
> that extra limitation on the "git version" output format.
>
> Maybe you are proposing something else.  I dunno.
I was just using a slightly different philosophical approach.

> --
Philip