Re: [PATCH] git-submodule.sh: Support 'checkout' as a valid update command

Francesco Pretto [off-list ref] writes:

Like you said, "it already refers to checkout and handles it
correctly". I think the use of the simple present tense here is
correct: it's a fact. Feel free to advice another wording if you
prefer.

It is not about preference but what we want to convey to the
readers.  When you start the sentence with "Oh, it already works
correctly", the readers need to see this sentence finished: "It
already works, it is handled correctly, but we change the code
nevertheless because ...?".

Here is my attempt to fill that "because ..." part:

	Subject: git-submodule.sh: 'checkout' is a valid update mode

	'checkout' is documented as one of the valid values for
	'submodule.<name>.update' variable, and in a repository with
	the variable set to 'checkout', "git submodule update"
	command do update using the 'checkout' mode.

	However, it has been an accident that the implementation
	works this way; any unknown value would trigger the same
	codepath and update using the 'checkout' mode.

        Tighten the codepath and explicitly list 'checkout' as one
	of the known update modes, and error out when an unknown
	update mode is used.

	Also, teach the codepath that initializes the configuration
	variable from in-tree .gitmodules that 'checkout' is one of
	the valid values---the code since ac1fbbda (submodule: do
	not copy unknown update mode from .gitmodules, 2013-12-02)
	used to treat the value 'checkout' as unknown and mapped it
	to 'none', which made little sense.

2014/1/7 Junio C Hamano [off-list ref]:

It is not about preference but what we want to convey to the
readers.  When you start the sentence with "Oh, it already works
correctly", the readers need to see this sentence finished: "It
already works, it is handled correctly, but we change the code
nevertheless because ...?".

Here is my attempt to fill that "because ..." part:

        Subject: git-submodule.sh: 'checkout' is a valid update mode

        'checkout' is documented as one of the valid values for
        'submodule.<name>.update' variable, and in a repository with
        the variable set to 'checkout', "git submodule update"
        command do update using the 'checkout' mode.

        However, it has been an accident that the implementation
        works this way; any unknown value would trigger the same
        codepath and update using the 'checkout' mode.

        Tighten the codepath and explicitly list 'checkout' as one
        of the known update modes, and error out when an unknown
        update mode is used.

        Also, teach the codepath that initializes the configuration
        variable from in-tree .gitmodules that 'checkout' is one of
        the valid values---the code since ac1fbbda (submodule: do
        not copy unknown update mode from .gitmodules, 2013-12-02)
        used to treat the value 'checkout' as unknown and mapped it
        to 'none', which made little sense.

I wouldn't be able to explain the change better than your description.
Also, I was under the improper assumption that the change was obvious.
Thank you very much for the amended patch description.

Cheers,
Francesco