Re: How can we decrease the cognitive overhead for contributors?

[Liliana Marie Prikler <liliana.prikler@gmail.com>]

Hi,

Am Sonntag, dem 27.08.2023 um 16:57 +0300 schrieb Saku Laesvuori:
> > > 
> > not sure how most people consume their emails nowadays, but for me
> > it's one flat list per thread, in a browser (i.e. it's not a tree).
> 
> The point is that the emails contain the information on how to
> construct a tree out of them. It's just that most web clients (which
> most people are unfortunately using nowadays) are so bad that they
> render the tree as a flat list.
Not sure about "most", but Guix folk are definitely biased towards
dedicated mail clients (terminal, graphical, Emacs…), so perhaps my own
perception was a little off in that people will always benefit from
having the tree.  Then again, you can share your email between multiple
clients, which isn't that easy to do with code repositories sadly.  

Of course, you can mirror the repo, but your bug trackers aren't that
easily mirrored.

> 
> > and all i'm trying to achieve here is to move the discussion away
> > from email-is-superior-period, to look at what requiremenets we
> > have and what tools satisfy them, if any.
> 
> I think that is a good discussion to have, but I think it would be
> better to describe some of the requirements you think we should
> consider instead of just saying email isn't superior. It might not
> be, but it might also be. We should consider what we need and
> evaluate the available tools based on that, and if the result is that
> email is the best then it is.
Not needing to register yet another account for one-off contributions
is an argument that kills all the forges, sadly :)

> > > at the ChatGPT-related stuff that has been submitted). There
> > > sadly is no pleasing everyone here and unless these tools are
> > > incredibly simple to maintain, the utilitarian approach of least
> > > misery leads you to plain email.
> > 
> > but is a least-misery model appropriate here? how do you even
> > account for the contributions that could have happened in a
> > different environment, but did not happen?
> > 
> > similarly, e.g. demanding a dated ChangeLog format for commit
> > messages has a filtering effect on who will contribute, and then
> > who will stick around. most engineers have a hard time jumping
> > through hoops that they find pointless (git automatically encodes
> > that information), and i'd suggest considering what the effect are
> > of such rules on Guix asan emergent order.
> 
> I agree on the ChangeLogs being a weird thing to require in commit
> messages. I think of commit messages as the place where you record
> the reasons behind the change in the commit. The ChangeLog seems to
> just record the changes which the diff of the commit already
> automatically records more accurately.
First things first, I disagree with the framing here.  Engineers do
pointless things all the time and both code style and commit message
style have near endless potential for bikeshedding (which we are
currently engaged in btw).  There are like thirteen competing standards
on how to format C code and similar debates in other languages.  In
fact, I'd go so far as to argue that a language ecosystem that has no
such debate is potentially lacking in diversity.

A proper ChangeLog doesn't simply "record the changes the diff already
records more accurately".  It adds semantics.  For instance, when
bumping a package, we write the same line twice; once for the header,
once for the ChangeLog.  What we don't write is that we also adjusted
the hash along with the version.  Doing so would give us no new
information, but the diff includes it anyway, because diffs are stupid.
Humans writing (and reading) ChangeLogs aren't stupid and can rely on
contextual meta-information – however, the ChangeLog should still be
self-contained in the sense that it doesn't rely on other parts of the
message to infer the actual changes made.

> If someone has use cases for the ChangeLog commits, I'd like to hear
> them. Maybe there is something that can't be achieved with git
> history without ChangeLogs, but I can't think of anything. Someone
> mentioned grepping the git log with them, but I think the same thing
> can be done with git log and git blame regardless of the commit
> message format.
In my humble opinion, you underestimate the benefits of not having to
invoke another command on a commit.  For a great number of changes, the
ChangeLog style allows me to imagine the code that was written without
having to see it in a way that a simple diffstat just can't.  Of
course, whether you use ChangeLog style commit messages, Emoji commits
or any other formatting guide is a political question between everyone
involved in a project, but there are benefits to having guidelines and
following them.  

It's similar to following generally accepted etiquette in any circle. 
People will generally be happy as long as you follow them and can often
tolerate small deviations, but at a certain point it just becomes
uncomfortable, so we kindly ask you to follow the established
practices.

Cheers