Re: [PATCH v3] doc: describe the project's decision-making process

[Patrick Steinhardt <ps@pks.im>]

[-- Attachment #1: Type: text/plain, Size: 3037 bytes --]

On Fri, May 17, 2024 at 09:40:02AM -0700, Junio C Hamano wrote:
> Patrick Steinhardt <ps@pks.im> writes:
> >> +When consensus is reached that it is a good idea, the original
> >> +proposer is expected to coordinate the effort to make it happen,
> >> +with help from others who were involved in the discussion, as
> >> +needed.
> >
> > One thing I want to eventually propose is to go further here:
> > documenting the outcome of the discussion, regardless of whether we
> > decided for or against it, in a low-overhead format. This could for
> > example be a small paragraph in a "Documentation/Projects" file that
> > points to the on-list discussion together with a small summary of why
> > the decision was reached.
> 
> Having such a list certainly is handy; the problem is how to keep
> them current, though.

I try to somewhat tackle the issue by explicitly saying that the format
should be low-overhead. But that of course won't fully make the problem
go away, we still need to make sure that it's getting updated somewhat
regularly.

That being said, I don't think it'll be all that often that we need to
add new items to the list. We don't have a ton of large ongoing projects
in our codebase. I'd claim that we can rather measure the cadence of
such projects in years rather than months. So we might get away with a
"best effort" approach to keep it up-to-date.

> > I don't think that this change needs to be part of your patch though, as
> > your intent is only to document processes as they work right now. But I
> > wanted to bring this up regardless as a foreshadowing.
> 
> Yup, I agree that it is probably better left out of the scope for
> now.
> 
> If we are in the "expressing wish" mode, another thing we might find
> it useful, if such a thing existed, is a list of principles for
> designing new things.  E.g., not changing an established behaviour
> to prioritize protecting existing users' muscle memory over whims of
> the day by folks who haven't had enough time to familialize with it.
> E.g., the plumbing output is sacred but the Porcelain output is
> subject to change to improve human-user experience with coloring
> and pagination, etc.

Yes, I very much agree. One of these principles that I want to discuss
soonish is the design of our CLI. I think we would benefit if we had a
set of guidelines that show what our ideal UI should look like. Many of
our older commands may not fit into such a UI design, as I think that it
has evolved since the inception of Git, and that's fine. But starting to
think about the bigger picture here and where we want to go may be quite
helpful overall. It would make it a ton easier for folks to argue based
on established and documented principles instead of requiring handwavy
gut feeling.

That's only one part though where we may want to lay out our principles,
I'm sure there are others. But I'm throttling my push for more structure
a bit, and rather want to lead one discussion after the other.

Patrick

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]