Re: [PATCH v2 10/16] tag: change misleading --list <pattern> documentation

From: Junio C Hamano <gitster@pobox.com>
To: "Ævar Arnfjörð Bjarmason" <avarab@gmail.com>
Cc: Git Mailing List <git@vger.kernel.org>,
	Lars Hjemli <hjemli@gmail.com>, Jeff King <peff@peff.net>,
	Christian Couder <christian.couder@gmail.com>,
	Carlos Rica <jasampler@gmail.com>,
	Samuel Tardieu <sam@rfc1149.net>,
	Tom Grennan <tmgrennan@gmail.com>,
	Karthik Nayak <karthik.188@gmail.com>
Subject: Re: [PATCH v2 10/16] tag: change misleading --list <pattern> documentation
Date: Wed, 22 Mar 2017 15:26:21 -0700	[thread overview]
Message-ID: <xmqqtw6lgd82.fsf@gitster.mtv.corp.google.com> (raw)
In-Reply-To: <CACBZZX4rofOquS4q0NDCb8cHOF=E7iPzFMxj3bre6CTB7=b_MA@mail.gmail.com> (=?utf-8?B?IsOGdmFyIEFybmZqw7Zyw7A=?= Bjarmason"'s message of "Wed, 22 Mar 2017 23:08:28 +0100")

Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:

> of things you think we should be putting in the test suite. I.e.
> should the tests be:
>
> a) Only be a collection of invocations of git we'd be comfortable
> showing to someone as "this works, and this is how you should do it",
> or things that explicitly fail marked with test_must_fail.
>
> b) or a) && also various surprising combinations of things we don't
> necessarily want to encourage or even support in the future, but which
> are in there so if we change them, we at least know our change changed
> something that worked before.

I am strongly inclined to (a).  If we cannot decide when we designed
the feature, and we anticipate that we may want to change it later,
then documenting the choice in a test or two may be a way to remind
the choice we happened to have made, but in general I do not think
we want to promise (to ourselves) more than what we are willing to
commit to.