Re: SHA256 support not experimental, or?

From: Junio C Hamano <gitster@pobox.com>
Date: Jul 20, 2023, 18:18 UTC
Message-ID: <xmqqr0p230rj.fsf@gitster.g>
In-Reply-To: <ZLlNtbAbVcYH7eFb@adams>

Adam Majer <adamm@zombino.com> writes:

Show 7 quoted lines

> I'll try again with inline patch. I think it wasn't picked up since it
> was mime encoded by the mail client..
>
> - Adam
>
>
> From 90be51143e741053390810720ba4a639c3b0b74c Mon Sep 17 00:00:00 2001

Remove all the above lines (including the "From <commit object name>"). If you want to add a note that should not be recorded in the message of the resulting commit, write it _after_ the three-dash line after your sign-off.

> From: Adam Majer <adamm@zombino.com>
> Date: Wed, 28 Jun 2023 14:46:02 +0200
> Subject: [PATCH] doc: sha256 is no longer experimental

It is not technically incorrect to have these three lines here, but when you are presenting your own work, it is preferrable to do without them. The "From:" address line and "Subject:" text line do not have to be here---most people should be able to make the corresponding e-mail headers to have the value they want to use, and while the above "Date:" might be the time you wrote the commit, it is way earlier than the time the contents of the commit was presented for consideration to the general public, which is recorded in the e-mail header of the message you are sending.

So, the body of the message usually should start from here (below).

In general, please follow [[describe-changes]] part of the Documentation/SubmittingPatches document, and also "git log --no-merges" of recent contributions by others. "The purpose of this patch is" is not how we usually talk about our work.

Show 26 quoted lines

> The purpose of this patch is to remove scary wording that basically
> stops people using sha256 repositories not because of interoperability
> issues with sha1 repositories, but from fear that their work will
> suddenly become incompatible in some future version of git.
>
> We should be clear that currently sha256 repositories will not work with
> sha1 repositories but stop the scary words.
>
> Signed-off-by: Adam Majer <adamm@zombino.com>
> ---
>  Documentation/git.txt                      | 4 ++--
>  Documentation/object-format-disclaimer.txt | 8 ++------
>  2 files changed, 4 insertions(+), 8 deletions(-)
>
> diff --git a/Documentation/git.txt b/Documentation/git.txt
> index f0cafa2290..666dbdb55c 100644
> --- a/Documentation/git.txt
> +++ b/Documentation/git.txt
> @@ -553,8 +553,8 @@ double-quotes and respecting backslash escapes. E.g., the value
>  	If this variable is set, the default hash algorithm for new
>  	repositories will be set to this value. This value is
>  	ignored when cloning and the setting of the remote repository
> -	is always used. The default is "sha1". THIS VARIABLE IS
> -	EXPERIMENTAL! See `--object-format` in linkgit:git-init[1].
> +	is always used. The default is "sha1". See `--object-format`
> +	in linkgit:git-init[1].

This side looks OK (just removing the single sentence).

Show 15 quoted lines

>  Git Commits
>  ~~~~~~~~~~~
> diff --git a/Documentation/object-format-disclaimer.txt b/Documentation/object-format-disclaimer.txt
> index 4cb106f0d1..1e976688be 100644
> --- a/Documentation/object-format-disclaimer.txt
> +++ b/Documentation/object-format-disclaimer.txt
> @@ -1,6 +1,2 @@
> -THIS OPTION IS EXPERIMENTAL! SHA-256 support is experimental and still
> -in an early stage.  A SHA-256 repository will in general not be able to
> -share work with "regular" SHA-1 repositories.  It should be assumed
> -that, e.g., Git internal file formats in relation to SHA-256
> -repositories may change in backwards-incompatible ways.  Only use
> -`--object-format=sha256` for testing purposes.
> +Note: SHA-256 repositories currently will not be able to share work
> +with "regular" SHA-1 repositories.

The original did not have this problem because it had enough surrounding context, but the updated text now risks getting misread as if there are "regular" and "special" SHA-1 repositories, the latter of which might work better with SHA-256.

And the message about SHA-256's non-experimental status can probably be a lot stronger, after the discussion we had recently. How about saying something like:

    Note: there is no interoperability between SHA-256 repositories
    and SHA-1 repositories right now.  We historically warned that
    SHA-256 repositories may need backward incompatible changes
    later when we introduce such interoperability features, but at
    this point we do not expect that we need to make such a change
    when we do so, and the users can expect that their SHA-256
    repositories they create with today's Git will be usable by
    future versions of Git without losing information.

which would probably be much closer to what you wanted to hear?

Thanks.