Re: [PATCH v2] http: document sslcert and sslkey types and extend to proxy

From: Junio C Hamano <gitster@pobox.com>
Date: Apr 20, 2023, 19:43 UTC
Message-ID: <xmqq7cu6z6et.fsf@gitster.g>
In-Reply-To: <pull.1520.v2.git.1682014322604.gitgitgadget@gmail.com>

"Ricky Davidson via GitGitGadget" <gitgitgadget@gmail.com> writes:

> From: Ricky Davidson <Ricky.Davidson@hii-tsd.com>

I think it is the first time we see your patches around here. Welcome to Git developer community.

> 0a01d41 added http.sslCertType and http.sslKeyType, but:
>
> 1. does not document the feature.
> 2. does not apply to SSL proxy equivalents.

The above description would read better to have "it" to serve as the subject for the two sentences that point out rooms for improvement of what the earlier commit did somewhere. Perhaps between "but" and the colon after it, e.g. "X did Y, but it: (1) did not do W, and (2) did not do Z." Alternatively, "X did Y, but: (1) it did not do W. (2) it did not do Z." would also work.

The way we refer to an existing commit is:

	0a01d41e (http: add support for different sslcert and sslkey
	types., 2023-03-20) added ...

Running "git show --pretty=reference -s $commit" would give you a properly formatted reference.

> Documents http.sslCertType and http.sslKeyType. Implements
> http.proxySSLCertType. Same for http.sslKeyType and
> http.proxySSLKeyType equivalents and related environment
> variables.

After explaining the status quo and talking about what we want to improve, we write what we wanted the code to become with this patch in imperative mood, as if we are giving an order to "become like so", instead of third-person present tense.

I.e. something like "Document X and Y, and implement W and Z for completeness. Do the same for A and B."

Other than that, well-written in an understandable way.  Very nice.

>  Documentation/config/http.txt | 24 ++++++++++++++++++++++++
>  http.c                        | 12 ++++++++++++
>  2 files changed, 36 insertions(+)

I wonder if we can add some tests for the feature, though.

Thanks.