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

[Ekaitz Zarraga]

 
> I think a lot of this discussion is stuck on what is better web or
> email. Where it doesn't have to be.
> 
> What we instead need to do is acknowledge that some people like the web
> approach.
> 
> And accommodate them so we can have guix used by more people. Simple as that 
> :D


Exactly.
An option is to make some kind of user-story based documentation might help?

For example:

--
- If you are used to a web-based git forge such as gitlab or github, Guix's 
approach
to collaboration might seem a little bit hard at the beginning.
Guix uses an email based approach, like many other GNU projects do. Email based
approach relies on sending commits as patches that can be later applied by 
commiters
and maintainers. Thee patches are sent via email, in plain text, instead of 
using a
website for a Pull- or Merge- Request.

You don't have to worry about the format of the emails, as git is able to 
generate
them for you:

   $ git commit ...
   $ git format-patch ...

If you configure git properly (link to how to do it), git can send those emails 
to
guix automatically (see Using Git Send Mail). If you prefer, you can copy the 
content
of the file `format-patch` generates in a plain text email, or attach it and 
send it to
`guix-patches`.

When that email is received a bug report will be opened in guix's issue system, 
where
you can further discuss, as you would do in any other issue board or merge- or 
pull-
-request discussion. The discussion is available at `URL` and looks like 
`screenshot`.

If you want to share a series of patches...
--

Something like that (done with more care and attention than what I just did), 
might
help newcomers. It's mostly the same our documentation says, but our 
documentation
currently (I think) relies too much on the people knowing what everything means.

Maybe a deeper contribution guide might be an interesting thing to write down...
Also including some introduction to the internals and how to write a 
build-system...
Stuff like that is always useful.
It has to be properly maintained though, but even if it is out of date, it's 
still
a valuable resource to have some info about the *concepts*. (we can always put 
the
date of the latest change and a note: this documentation is designed to explain 
the
concepts, the specific details might be out of date, but the concepts remain).

Or something, I don't know. But I'm open to try it :)


The case of the Changelog commits has been discussed and its important too.
We need to be able to make contributors learn how much they need to write down 
in
the commit messages. I tend to write too much, and I don't think any of my 
patches
have been applied without changes in the commit message.

For example, in guix we often do (I just invented the name): 

gnu: Add lolo

* gnu/packages/engineering.scm(lolo): New variable.

Is that enough to describe the addition of a new package? If you know what you 
are
looking for it might be, but it looks like an automatism commiters have that is 
not
communicated properly. What if there's something in a `let` i changed? I have 
to list
that too? What if...?

Some help on that might be useful. And also, explaining how important it is to 
follow
the jargon we use in the commit messages. Or how long should our explanations 
be...
Just to help people don't feel overwhelmed about it, nothing more than that 
(and 
nothing less!).

I don't know if this adds anything new to the conversation.

Cheers!

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

[MSavoritias]

On 9/22/23 18:14, Imran Iqbal wrote:

On Sun, Sep 03, 2023 at 05:45:41PM +, Ekaitz Zarraga wrote:

I use protonmail and they don't provide smtp access so I can't do git
send-mail as easy as other people do.

A mail provider not allowing SMTP is a git forge that does not allow git
push.

This is not Guix's fault, but it's a problem Guix doesn't help fix either.

This is not on guix to fix, this in you with your choice of mail
provider.


This doesn't mean I'm against the email based approach, in fact, I really
like it. The main problem I see is many people inside guix are not
sensible to people's problems and tastes.

The problem is people's tastes are "we need to use the web browser for
everything" which is what computers have become in a advertising and VC
funded world. We should not be forcing that on people.


Some people are forced to use tools for several reasons, too.

But text editing and email the two things which there are a plethora of
tools, and it's very hard to imagine a scenario where someone is forced
into using one.


This is what I mean when I say many times emacs is kind of mandatory, and
this thread is kind of a demonstration of what I meant because the main
discussion evolved to: you can use this or that in emacs to ease the dev
experience.

This is because emacs is a lisp machine that just happens to let you
edit text. If you are working in a lisp-y language, emacs provides the
best development experience. Emacs also lets you hand mail inside of
emacs (among many many other things). This does not mean you are forced
to use emacs. I use neovim and neomutt for my needs.


I don't think software we use is the main problem, but the fact that we
are not always sensible with other people's experience.

Imagine a different scenario, where instead of this being about email it
was around guile. Would it be fair to say that a Guix makes it hard
to contribute by choosing to be implemented in guile? And that Guix
should move towards using another language that more people are familiar
with like python or javascript?

Personally I don't think its fair to ask Guix to move away from emails
because folks are more familiar with using web browsers for everything.



I think a lot of this discussion is stuck on what is better web or 
email. Where it doesn't have to be.


What we instead need to do is acknowledge that some people like the web 
approach.


And accommodate them so we can have guix used by more people. Simple as 
that :D



Its free software and power to the person that using the software after all.


MSavoritias

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

[Ekaitz Zarraga]

Hi,


> On Sun, Sep 03, 2023 at 05:45:41PM +, Ekaitz Zarraga wrote:
> 
> > I use protonmail and they don't provide smtp access so I can't do git
> > send-mail as easy as other people do.
> 
> 
> A mail provider not allowing SMTP is a git forge that does not allow git
> push.


This is a feeling, not a fact.

> > This is not Guix's fault, but it's a problem Guix doesn't help fix either.
> 
> This is not on guix to fix, this in you with your choice of mail
> provider.

I didn't say it's a problem Guix needs to fix.
Also, what I'm trying to say here is maybe I didn't have the chance to choose
my email provider.
This is the exact behavior that I was saying it's not helpful.

The email based approach is fantastic, and as good as it is, is flexible enough
to let me use it even if I don't have SMTP access.
What I think Guix docs lack is an explanation for those users like me, that
don't have the privilege or the mental clarity to choose an email provider that
matches your standards.

> > This doesn't mean I'm against the email based approach, in fact, I really
> > like it. The main problem I see is many people inside guix are not
> > sensible to people's problems and tastes.
> 
> The problem is people's tastes are "we need to use the web browser for
> everything" which is what computers have become in a advertising and VC
> funded world. We should not be forcing that on people.


This is a projection, not what I meant.

And even with that, if everyone wants to use the browser for everything
maybe, if what we want is to *actually* reduce the cognitive overhead of
people we *should* consider giving them a chance.
Or should we *correct* people's tastes because they are wrong, as you
suggest here?

I'm not asking Guix to change the tools but the information about them.
Make them more approachable doesn't necessarily mean to use a flashy web
application imho. It means to give tools and knowledge, or at least to
give enough pointers to that knowledge to let people jump in and feel
comfortable in an easy way.

So, in any case I meant what you are implying here, and I even find slightly
offensive that kind of comment. It feels pretty insensible and purposely 
misleading. 

(Also: VCs and advertising have nothing to do with this, people who proposed
forges proposed quite reasonable alternatives)

> > Some people are forced to use tools for several reasons, too.
> 
> But text editing and email the two things which there are a plethora of
> tools, and it's very hard to imagine a scenario where someone is forced
> into using one.

Some people can't install things in their devices, or they can't access
the network using certain protocols. Giving alternatives helps that group
of people.
 
> > This is what I mean when I say many times emacs is kind of mandatory, and
> > this thread is kind of a demonstration of what I meant because the main
> > discussion evolved to: you can use this or that in emacs to ease the dev
> > experience.
> 
> This is because emacs is a lisp machine that just happens to let you
> edit text. If you are working in a lisp-y language, emacs provides the
> best development experience. Emacs also lets you hand mail inside of
> emacs (among many many other things). This does not mean you are forced
> to use emacs. I use neovim and neomutt for my needs.

Again, this comment assumes I don't understand the reasons behind it.
The problem I'm trying to point is not that emacs is not great, but the fact
that new people to the project has tons of info about emacs and around zero
about any other editor or configuration, giving them the false (as you point)
image that emacs is mandatory to work in guix.

It's a matter of sensibility, exactly the thing you are not having here.

> > I don't think software we use is the main problem, but the fact that we
> > are not always sensible with other people's experience.
> 
> Imagine a different scenario, where instead of this being about email it
> was around guile. Would it be fair to say that a Guix makes it hard
> to contribute by choosing to be implemented in guile? And that Guix
> should move towards using another language that more people are familiar
> with like python or javascript?

That argument is not a fair argument either.
Guile is structural in Guix, but emails are not and (you said it) emacs is
not either.

Also, what we are trying to do here is to reduce the cognitive overhead of
*contributors*, not from every possible individual in the world.

This is not only misleading, but unfair with my comment.
You nitpicked every part of my message you could use for your final argument.
Which is the following:
 
> Personally I don't think its fair to ask Guix to move away from emails
> because folks are more familiar with using web browsers for everything.

First, I didn't, and most of the people didn't, ask Guix to move away from
emails.

Second, folks that are more familiar with web browsers are not inferior to
the users that like using the email. If the majority 

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

[Katherine Cox-Buday]

Imran Iqbal  writes:

> Personally I don't think its fair to ask Guix to move away from emails
> because folks are more familiar with using web browsers for everything.

Imran, you bring up good points. I wanted to state that I share this opinion: 
Guix should not move away from emails.

I view this conversation as discussing root-causes and ways to address those 
root causes through addition, not subtraction.

I hope that helps to assuage your concerns.

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

[Imran Iqbal]

On Sun, Sep 03, 2023 at 05:45:41PM +, Ekaitz Zarraga wrote:
> I use protonmail and they don't provide smtp access so I can't do git
> send-mail as easy as other people do.

A mail provider not allowing SMTP is a git forge that does not allow git
push.
> This is not Guix's fault, but it's a problem Guix doesn't help fix either.

This is not on guix to fix, this in you with your choice of mail
provider.

> This doesn't mean I'm against the email based approach, in fact, I really
> like it. The main problem I see is many people inside guix are not
> sensible to people's problems and tastes.

The problem is people's tastes are "we need to use the web browser for
everything" which is what computers have become in a advertising and VC
funded world. We should not be forcing that on people.

> Some people are forced to use tools for several reasons, too.

But text editing and email the two things which there are a plethora of
tools, and it's very hard to imagine a scenario where someone is forced
into using one.

> This is what I mean when I say many times emacs is kind of mandatory, and
> this thread is kind of a demonstration of what I meant because the main
> discussion evolved to: you can use this or that in emacs to ease the dev
> experience.

This is because emacs is a lisp machine that just happens to let you
edit text. If you are working in a lisp-y language, emacs provides the
best development experience. Emacs also lets you hand mail inside of
emacs (among many many other things). This does not mean you are forced
to use emacs. I use neovim and neomutt for my needs.

> I don't think software we use is the main problem, but the fact that we
> are not always sensible with other people's experience.

Imagine a different scenario, where instead of this being about email it
was around guile. Would it be fair to say that a Guix makes it hard
to contribute by choosing to be implemented in guile? And that Guix
should move towards using another language that more people are familiar
with like python or javascript?

Personally I don't think its fair to ask Guix to move away from emails
because folks are more familiar with using web browsers for everything.

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

[Development of GNU Guix and the GNU System distribution.]

Hi Simon,

On Mon, Sep 18 2023, Simon Tournier wrote:
>
> To be clear, I dismiss only these two sentences:

Having read your message from earlier today [1] in which I think you
questioned the continued utility of this thread ("could we stop this
useless and unproductive flamewar?") it seems fair to say that this
communication has now reached a logical end.

Participants are arguing over what they are arguing about.

Let's build something cool today. Thanks for everyone's work on Guix!

Kind regards
Felix

[1] https://lists.gnu.org/archive/html/guix-devel/2023-09/msg00430.html

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

[Liliana Marie Prikler]

Am Montag, dem 18.09.2023 um 20:39 +0300 schrieb MSavoritias:
> 
> On 9/18/23 20:13, Simon Tournier wrote:
> > On Mon, 18 Sept 2023 at 18:35, MSavoritias 
> > wrote:
> > 
> > > I was talking from my experience. If you don't share it that is
> > > fine.
> > Share what?  Your experience?  How can I?  Instead, I share facts
> > backed by numbers.
> > 
> > It is fine to share how you perceive, encouraged even!  It is not
> > fine to make bold claim based on nothing more than a very
> > subjective view point.
> 
> Please take a step back. You cannot dismiss my experience.
> 
> As I have said and other people in this thread, and as I said i also 
> engage with people in social networks, and I am talking from that
> experience.
I think it is fair to say that experiences are subjective and
potentially misleading (and in the case of social media typically
subject to the bias induced by filter bubbles).  Now, the same
similarly applies to facts and statistics when given the wrong
interpretation, but first things first, we have to be aware of those
sources of bias and then work with them.  In this case it means not
making hasty claims on contributor count based on what you've heard in
social media.


Am Montag, dem 18.09.2023 um 11:37 +0200 schrieb Simon Tournier:
> Please point one project where:
> 
>   + more than 900 people have contributed to the project,
>   + more than 100 people had or have write access in the repository.
Some more data points captured by the same means you used, make of them
what you will:

Emacs: 1440/470
GCC: 2468/908
Nixpkgs: 7283/6339
Rust: 5657/5460
NPM (just the cli): 896/53
guixrus: 31/4

(As we can see, the pull request model hides how many people actually
have write access in some instances.)

What's not shown in these data points obviously are recent
contributions and active committers – we've had them posted at some
point, but that's old data by now.

Quite interestingly, Emacs and GCC both appear to have a 3:1 ratio of
contributors to committers despite using the same email-based workflow.
Perhaps that's due to age, or maybe it's a sign that we are too slow to
accept help? 

> The thing is nobody talked about email vs web forge to my knowledge
> though.
The thing is every discussion à la "maybe we should improve our
workflow somehow" eventually devolves into exactly this.  I have seen
my fair share of such discussions already in the short time I've spent
contributing to Guix.  The best that has so far come from it was people
spinning of their own channels (and even then, the use of another forge
appears almost incidental at times; our vetting process has similarly
been criticized for its perceived inefficiencies).

Now, I'd like to call back to a point I made earlier:

Am Dienstag, dem 05.09.2023 um 22:43 +0200 schrieb Liliana Marie
Prikler:
> Maybe it's time to take a step back and instead of asking “How can we
> decrease the cognitive overhead for contributors?”, we should perhaps
> ask “For which contributors do we want to/can we decrease the
> cognitive overhead?”
You can quite easily work around this issue by maintaining a
comparatively small channel for some thirty people.  However, you do
now have the cognitive overhead of being one of its four maintainers
while also trying to feed back whatever code has actually matured well
upstream to ease your own maintenance burden.  If that's the tradeoff
you want to make, then by all means, go for it.

> One of the solution offered was to have *also* a web interface. It
> was never suggested any comparison.
> 
> The comparison seemed to have stemmed from some people feeling they 
> would be left behind (?) and wanting to prove that email is better or
> something. Personally i don't care what is better.
I think you are underestimating the community splitting effects that
offering different *blessed* frontends has.  We are not talking about
your personal choice of a mail user agent here, because there's nothing
to bless; you simply take whatever is comfortable to you.  For blessed
web frontends OTOH, just offering two different representations of the
same data can already lead to problems, e.g. different bugs being
reported by the mumi vs. old school debbugs crowd.  This is also part
of the reason why large organizations tend to centralize their stuff in
one platform, which most forges make stupidly simple.  Even if they
could cater to different groups simultaneously, *they just don't care*.

Now Guix is already a little special in that it offers like three views
into this big pile of bug reports and patches (plus a fourth one if you
count yhetil).  If you're going to add yet another interface, you have
to consider maintenance (as Andreas pointed out early on) and possibly
different styles of etiquette encouraged by such interfaces (as I
pointed out soon after) or possibly other road bumps.  

Cheers

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

[Simon Tournier]

Hi,

On Mon, 18 Sept 2023 at 19:40, MSavoritias  wrote:

> As i said its okay if you don't understand it, or share it. What you can
> not do is dismiss my experience.

I do not dismiss your experience.  To the contrary.  It is because I
do not share other experiences that I am interested by learning them.
I think some of the points your are raising here or there are very
valuable, and whatever if I fully share them or not.  They are
valuable and it is important that you express them.  Period. :-)

To be clear, I dismiss only these two sentences [1]:

And the fact that guix doesn't get have many
committers and contributors are scarce, speaks for itself. If you don't
see it I suggest asking people in social networks/forums why they
*don't* get involved in guix.

Because here you do not speak about your personal experience; you are
reporting two statements which are IMHO not backed and thus they drag
down.  You draw a general conclusion extrapolated from your subjective
viewpoint.

Do not take me wrong, your viewpoint is valuable.  As important as any
other subjective viewpoint.  And for what it is worth, I read (almost)
all viewpoints with interest.  It is important that we all share them.

I do not feel personally attacked.  You, do you feel personally
attacked?   If yes, I am sorry for my tone because it was not my
intent.  I think it is important 1. to focus on positive actionable
items and 2. avoid slippery slope leading to negativity.

Well, instead of these two claims, it appears to me more engaging to ask:

 + considering Guix is 10 years old, how many new contributors does
the project get per month?  On average.
 + how many contributors contribute more than X times?
 + how many people roam on other media than Guix mailing list?
 + etc.

IMHO, by these questions, you are sharing your experience, your
perspective and your viewpoint without jumping to some partial
conclusion; even we could maybe reach together or infer some
interesting conclusions.  Somehow, these questions would drag up and
engage potentially fruitful discussions.  Maybe, that's what you
wanted to express?

Anyway.  That's how I view the things from my perspective.

It is my last email in this thread too.

Cheers,
simon


1: Re: How can we decrease the cognitive overhead for contributors?
MSavoritias 
Sun, 17 Sep 2023 19:20:48 +0300
id:f199249e-b30a-adf5-224f-1aed74a56...@fannys.me
https://lists.gnu.org/archive/html/guix-devel/2023-09
https://yhetil.org/guix/f199249e-b30a-adf5-224f-1aed74a56...@fannys.me

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

[MSavoritias]

On 9/18/23 20:13, Simon Tournier wrote:

On Mon, 18 Sept 2023 at 18:35, MSavoritias  wrote:


I was talking from my experience. If you don't share it that is fine.

Share what?  Your experience?  How can I?  Instead, I share facts
backed by numbers.

It is fine to share how you perceive, encouraged even!  It is not fine
to make bold claim based on nothing more than a very subjective view
point.


Please take a step back. You cannot dismiss my experience.

As I have said and other people in this thread, and as I said i also 
engage with people in social networks,


and I am talking from that experience.


As i said its okay if you don't understand it, or share it. What you can 
not do is dismiss my experience.


It is not attack on you personally what i have said it is meant as how I 
view things from my perspective that is all.



Consider this my last email in this thread.


MSavoritias.

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

[Simon Tournier]

On Mon, 18 Sept 2023 at 18:35, MSavoritias  wrote:

> I was talking from my experience. If you don't share it that is fine.

Share what?  Your experience?  How can I?  Instead, I share facts
backed by numbers.

It is fine to share how you perceive, encouraged even!  It is not fine
to make bold claim based on nothing more than a very subjective view
point.

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

[MSavoritias]

On 9/14/23 11:24, Ricardo Wurmus wrote:

Fannys  writes:


But again, even if this is a great option for you, it might be a really bad
option for some other people. Everybody does not have the time to spend
learning emacs, or other specific tool. It's ok if the workflow suggests that
but it's not great if we have no other alternative.

It's not accessible and imposes a barrier in some people.

Yeah agreed. And we should be consious of that.
Ironically by mandating Emacs and Email we force people to use specific
tools while at the same time even though the same people will complain(!) 
against vendor lock-in
like github.

We don’t *mandate* the use of Emacs.  It’s just a common recommendation
because it works so well with text and is trivially extensible, so it’s
a common target for helper tools.  Surely we also wouldn’t call a
recommendation to use a shell script “vendor lock-in” just because it
needs Bash.

Emacs works well with text, and text is all that’s needed in a
patch-based workflow, which is in fact vendor agnostic.

Of course this doesn’t mean that it is as accessible as we’d want.

Well as it was pointed out when it is the only thing that is mentioned 
in the manual and all the tooling is based around it, it might as well 
be mandated.


If it works only in Bash it pretty much is "vendor lock-in" yes.

I have mentioned in other email so I won't repeat myself here, plain 
Emacs is not really accessible for a person that wants to start messing 
around with guix or guile.



MSavoritias

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

[MSavoritias]

On 9/18/23 12:37, Simon Tournier wrote:

Hi,

On Sun, 17 Sep 2023 at 19:20, MSavoritias  wrote:


Including an committer. And the fact that guix doesn't get have many
committers and contributors are scarce, speaks for itself. If you don't
see it I suggest asking people in social networks/forums why they
*don't* get involved in guix.

--8<---cut here---start->8---
$ git shortlog -sn --all | wc -l
952

$ git log --format="%ce" | sort | uniq -c | wc -l
104
--8<---cut here---end--->8---

Please point one project where:

   + more than 900 people have contributed to the project,
   + more than 100 people had or have write access in the repository.

It is fine to discuss how to improve and what we could do better.  It is
incorrect to say “guix doesn't get have many committers and
contributors” and it is not fine to frame it negatively.

I was talking from my experience. If you don't share it that is fine.

For example Debian moved to Gitlab. Same for gnome and kde.

As I pointed in my very first reply [1] in this thread:

 For instance, Debian is based on Gitlab since their switch from Alioth
 to Salsa.  It would be interesting to know if this “new” web-based
 workflow using Merge Request is increasing the number of submissions
 and/or increasing the number of occasional contributors.

As far as I have read all this thread, no one provides numbers.  The
answer by Vagrant (Debian Developer and Guix contributor) appears to me
interesting [2].  Therefore, could we stop this useless and unproductive
flamewar?  Many Guix channels are hosted on Gitlab, Github or Sourcehut
and they are not receiving so much more contributions.  As Katherine
pointed [3],


Regarding the many contributions it has to do also with a lot of other 
stuff. Obviously a web interface wouldn't


solve everything. And i hope it never seemed I said otherwise.



 I know everyone is focusing on email vs. web-forge, but I am trying to
 draw attention to the root causes of the complexity, and enumerating
 possible solutions to these.

and I think that kind of mindset is very helpful; it is engaging.  Well,
to my approximate recollection, there is a talk at each DebConf about
reflecting on newcomers backed by some stats; e.g., [4].  In summary,
“email vs. web-forge” is a fake-problem, IMHO.  Last, the talk [5] by
Enrico Zini appears to me much more fruitful.  The question is about
sustain the community.  And this sustainability does not clearly depend
on any tool.


The thing is nobody talked about email vs web forge to my knowledge though.

What was pointed out was specifically cognitive overhead and how we can 
reduce that.


One of the solution offered was to have *also* a web interface. It was 
never suggested any comparison.


The comparison seemed to have stemmed from some people feeling they 
would be left behind (?) and wanting to


prove that email is better or something. Personally i don't care what is 
better.


What i care is that some people prefer web-based so we should 
accommodate them :) plain and simple.



MSavoritias


Cheers,
simon


1: Re: How can we decrease the cognitive overhead for contributors?
Simon Tournier 
Thu, 24 Aug 2023 20:53:14 +0200
id:871qfsuvad@gmail.com
https://lists.gnu.org/archive/html/guix-devel/2023-08
https://yhetil.org/guix/871qfsuvad....@gmail.com

2: Re: How can we decrease the cognitive overhead for contributors?
Vagrant Cascadian 
Sat, 02 Sep 2023 18:05:40 -0700
id:87wmx8m5gb.fsf@wireframe
https://lists.gnu.org/archive/html/guix-devel/2023-09
https://yhetil.org/guix/87wmx8m5gb.fsf@wireframe

3: Re: How can we decrease the cognitive overhead for contributors?
Katherine Cox-Buday 
Tue, 05 Sep 2023 13:15:48 -0600
id:13416fee-8c7d-b145-48b9-0fbec2251...@gmail.com
https://lists.gnu.org/archive/html/guix-devel/2023-09
https://yhetil.org/guix/13416fee-8c7d-b145-48b9-0fbec2251...@gmail.com

4: https://debconf23.debconf.org/talks/32-teams-newcomers-and-numbers/
5: https://debconf23.debconf.org/talks/2-adulting/

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

[Simon Tournier]

Hi,

On Sun, 17 Sep 2023 at 14:29, MSavoritias  wrote:

> The reason I have come to guix is because it strives to actually make it 
> easier for people to change things. with guix shell and such. So making 
> it easier for people to contribute is absolutely a part of it. Im not 
> saying we should force every volunteer of course to do "work". What I am 
> saying is:

Sorry if I misread you.  From my understanding you are mixing unrelated
things.  As I have tried to explain elsewhere in this thread, there is a
range of contributions.  Somehow, we can divide them in 4 categories:

0. Use Guix (and potentially report bugs :-))
1. Extend Guix for your own needs
2. Submit your modifications
3. Merge some modifications

Here, you start to speak about #0 and #1 and then you splice to #2.

I agree, it is a whole as the “free software” definition:

0. The freedom to run the program as you wish, for any purpose.
1. The freedom to change it so it does your computing as you wish.
2. The freedom to redistribute copies so you can help others.
3. The freedom to distribute copies of your modified versions to others.

However, to stay actionable, we need to keep in mind the 4 levels.  And
we need to recognize and identify for each level what is good, smooth,
easy and what is harder, unexpected or worse blocker.

Else, we are in some vacuum of abstract and we are locked in rants
without some engaging path forward.

That’s said, let me point that people are already engaging for improving
the accessibility of editors other than Emacs.  For instance, Vim [1] or
VSCode [2].  The frame is not “what we should do” but “let me show you
what I have”, IMHO.  Well, you are free to join the fun! :-)

1: https://10years.guix.gnu.org/video/using-vim-for-guix-development/
2: 
https://videos.univ-grenoble-alpes.fr/video/26660-cafe_guix_vscode_comme_outil_deditionmp4/

Cheers,
simon

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

[Simon Tournier]

Hi,

On Sun, 17 Sep 2023 at 19:20, MSavoritias  wrote:

> Including an committer. And the fact that guix doesn't get have many 
> committers and contributors are scarce, speaks for itself. If you don't 
> see it I suggest asking people in social networks/forums why they 
> *don't* get involved in guix.

--8<---cut here---start->8---
$ git shortlog -sn --all | wc -l
952

$ git log --format="%ce" | sort | uniq -c | wc -l
104
--8<---cut here---end--->8---

Please point one project where:

  + more than 900 people have contributed to the project,
  + more than 100 people had or have write access in the repository.

It is fine to discuss how to improve and what we could do better.  It is
incorrect to say “guix doesn't get have many committers and
contributors” and it is not fine to frame it negatively.

> For example Debian moved to Gitlab. Same for gnome and kde.

As I pointed in my very first reply [1] in this thread:

For instance, Debian is based on Gitlab since their switch from Alioth
to Salsa.  It would be interesting to know if this “new” web-based
workflow using Merge Request is increasing the number of submissions
and/or increasing the number of occasional contributors.

As far as I have read all this thread, no one provides numbers.  The
answer by Vagrant (Debian Developer and Guix contributor) appears to me
interesting [2].  Therefore, could we stop this useless and unproductive
flamewar?  Many Guix channels are hosted on Gitlab, Github or Sourcehut
and they are not receiving so much more contributions.  As Katherine
pointed [3],

I know everyone is focusing on email vs. web-forge, but I am trying to 
draw attention to the root causes of the complexity, and enumerating 
possible solutions to these.

and I think that kind of mindset is very helpful; it is engaging.  Well,
to my approximate recollection, there is a talk at each DebConf about
reflecting on newcomers backed by some stats; e.g., [4].  In summary,
“email vs. web-forge” is a fake-problem, IMHO.  Last, the talk [5] by
Enrico Zini appears to me much more fruitful.  The question is about
sustain the community.  And this sustainability does not clearly depend
on any tool.


Cheers,
simon


1: Re: How can we decrease the cognitive overhead for contributors?
Simon Tournier 
Thu, 24 Aug 2023 20:53:14 +0200
id:871qfsuvad@gmail.com
https://lists.gnu.org/archive/html/guix-devel/2023-08
https://yhetil.org/guix/871qfsuvad@gmail.com

2: Re: How can we decrease the cognitive overhead for contributors?
Vagrant Cascadian 
Sat, 02 Sep 2023 18:05:40 -0700
id:87wmx8m5gb.fsf@wireframe
https://lists.gnu.org/archive/html/guix-devel/2023-09
https://yhetil.org/guix/87wmx8m5gb.fsf@wireframe

3: Re: How can we decrease the cognitive overhead for contributors?
Katherine Cox-Buday 
Tue, 05 Sep 2023 13:15:48 -0600
id:13416fee-8c7d-b145-48b9-0fbec2251...@gmail.com
https://lists.gnu.org/archive/html/guix-devel/2023-09
https://yhetil.org/guix/13416fee-8c7d-b145-48b9-0fbec2251...@gmail.com

4: https://debconf23.debconf.org/talks/32-teams-newcomers-and-numbers/
5: https://debconf23.debconf.org/talks/2-adulting/

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

[Liliana Marie Prikler]

Am Sonntag, dem 17.09.2023 um 19:20 +0300 schrieb MSavoritias:
> Personally free software means that there shouldn't even be a
> separation of Dev and user. But that's another topic.
I mean, the pull request model has this separation baked into it.  To
create a pull request, you must have an account on the platform that
the project chooses to host its source on, fork it, and push your own
fork with whatever changes you have for the world to see, thereby
marking you a "developer", whatever that means.  To write an email, you
simply overcome your crippling social anxiety and write an email. 
Indeed, that's still a hard thing to do on its own, but the separation
of developers and users is not a thing you have to think about here.

Cheers

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

[MSavoritias]

On 9/10/23 01:20, Liliana Marie Prikler wrote:

Am Samstag, dem 09.09.2023 um 21:40 +0200 schrieb Ricardo Wurmus:

Liliana Marie Prikler  writes:


Must we force a single workflow on everyone, even if our track
record in reviewing and merging doesn’t clearly show that our way
is superior?

Again, define superior.

No, I won’t.  I think it’s obvious that our review process isn’t
working *well*.  So the argument that our current workflow allows for
effective review is dubious.  Not saying that you made that claim,
just that it’s hard to convince others of adopting our ways when the
results just aren’t great.

What do you consider "the results" here?  The rate at which patches are
merged?  This is hardly an issue our project alone is fighting and I'm
not convinced that technology, more or less, will shift it in either
direction.


That's one thing yeah.

There are multiple people in the thread pointing out issues with 
contributing that create friction.


Including an committer. And the fact that guix doesn't get have many 
committers and contributors are scarce, speaks for itself. If you don't 
see it I suggest asking people in social networks/forums why they 
*don't* get involved in guix.



Let's take our importers as an example.  Bugs aside, they allow us to
bump any package to the newest released version.  Naturally, similar
tools have evolved over in the forge world as well.  The end result?
Bots are now writing merge request that end up ignored much like there
are bugs in Guix that receive little attention due to what might as
well be unfortunate timing.

I'm also not sure how we can tie back contribution throughput to
cognitive overhead.  In fact, there might well be a Jevons paradox
hiding somewhere in that less overhead per patch means that more
patches can be written, which results in the same overall cognitive
overhead in the long run.

Now, you are probably right in that our review process probably isn't
working well for some value of well that yet needs to be defined.
However, without any frame of reference it is also a statement that can
neither be verified nor falsified.  I could be sitting in a burning
house claiming "this is fine" or sitting in the finest restaurant
claiming "this place sucks" and since you can't see me, there's no way
for you to infer that I'm a cat.

Cheers

Frame of reference should be what other projects have done. Its not like 
this hasn't come up before in other projects.


For example Debian moved to Gitlab. Same for gnome and kde.

I'm not saying we should copy them but we should at least ask "Why?" and 
how did they come to those conclusions.


Then we should also do a survey of people outside of guix that may be 
interested in it. What stops you from doing so? (spoiler: its the email 
among other problems :) )



Personally free software means that there shouldn't even be a separation 
of Dev and user. But that's another topic.

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

[MSavoritias]

On 9/8/23 21:50, Liliana Marie Prikler wrote:

Hi,

Am Freitag, dem 08.09.2023 um 16:44 +0200 schrieb Ricardo Wurmus:

I often have to review Github Pull Requests, and I don’t go commit by
commit by go through the diff and annotate the changes.  I *read* the
commits to get a sense for how the feature evolved and why changes
were made, but the fact that new commits are pushed on top of the
branch is not an obstacle in practice, because the commits don’t
matter.

(I know, it hurts me too, but I don’t make the rules, okay?)

Well, thanks to Guix inventing the time machine, individual commits do
matter to us.


And in these review interfaces we can mark individual comments as
resolved.  So the flat list of changes with annotations *does* in
fact provide a clearer organization than a tree of emails.

Note also that we don’t usually review commits by starting one new
thread for each issue we address, so we don’t benefit from automatic
branching of sub-discussions.

To be fair, the summarizing of changes followed by comments to
individual bits are a point that the forges at least get right.
However, unless you rework a single line multiple times – which
admittedly happens more often in the "push the change on top" model of
the forges than in the "condense your changes to logical units" model
we use – a branching discussion per commit still comes quite close in
practice.  Also, when there are multiple reviewers notice different
things, you also get the branching tree.


On Github, Pull Request branches are like our WIP branches.  They are
how we arrive at acceptable changes.  Picky people like me would then
go back and write new atomic commits for the effective diff, but in
my role as a reviewer I usually rebase, squash, and merge.

This workflow is more familiar to some and alienating to others, but
both of these workflows would work fine for Guix.  But today our
tools can only accommodate *one* workflow.

I'd imagine that rebase, squash and merge would exacerbate the workload
on the committer side and I think that most popular projects on those
forges already experience similar effects to us despite folks just
merging the requests as-is and in part even getting paid by big tech
for doing so.  (Perhaps I exaggerate at getting paid for processing
merge requests, I haven't worked for any of these companies, but
especially at the ones more oriented towards doing business, I'd
imagine that you can at least buy yourself a sandwich from the work you
do from time to time.)


It happens to be the one I’m used to, but let’s please not pretend
that it’s inherently *better* than the other.

I mean, when we say better, we would have to refer to some metric of
goodness.  And the metric I personally choose is somewhere in the
intersection of accessibility and interoperability, because that is
what matters to me.  With Github, Gitlab and whatever other forges you
have, you are more or less bound to their web interface.  If that works
for you, it works.  If it doesn't, it doesn't.  With the email-based
workflow, I can use whichever tools I am comfortable with, as long as
they work for sending mail (as a contributor) or eventually invoke `git
push' on a bunch of signed-off commits (as a committer).  This both
increases the chances of things working and gives me the tools to build
things that work for myself (and potentially others as well).

Cheers


That's the thing though, its not more accessible.

For multiple reasons including:

- knowledge accessibility

- accessibility for people with disabilities

- accessibility for people that don't have the time

and so on.


So the argument for accessibility is very much wrong. Now if you want to 
argue that its better for


some people because they can tweak their Emacs, sure I agree. I am one 
of those people.



But the web and html has orders of magnitude better accessibility than 
anything email. as a medium.


I mean we don't even have much accessibility to speak of in guix but 
that's another topic.



MSavoritias

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

[MSavoritias]

On 9/12/23 17:51, Maxim Cournoyer wrote:

Hi,

Csepp  writes:


Giovanni Biscuolo  writes:


[[PGP Signed Part:Undecided]]
Hello Csepp,

Csepp  writes:

[...]


I don't think repeating that no forge sucks less advances the
conversation towards any solution other than keeping the status quo,
which can't really be called a solution.

Are we really talking about changing the official Guix forge:
https://savannah.gnu.org/projects/guix?

I definitely am.

The real place to put efforts toward that goal should be in the GNU
project; this way we can continue to maintain shared resource, knowledge
and tooling as a project.  I think packaging either sourcehut or gitea
and writing a Guix System service for it would provide opportunities to
experiment and perhaps one day move in that direction, so that's
something concrete that you can direct your efforts too.

Agreed. and speaking of that it seems its already something in the works 
as it was pointed elsewhere:


(as trial at least.)

sourcehut.gnu.org

sourcehut.gnu.org hub <#>

 https://sourcehut.gnu.org/ 

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

[MSavoritias]

On 9/13/23 18:42, Maxim Cournoyer wrote:

Hi Fannys,

Fannys  writes:


Ekaitz Zarraga  writes:


This is what I mean when I say many times emacs is kind of mandatory,
and
this thread is kind of a demonstration of what I meant because the main
discussion evolved to: you can use this or that in emacs to ease the
dev
experience.


One of the benefits of my being able to attend Guix Days was seeing
peoples' workflows and stacks in person.

As such, one of my conclusions having (already) committed to Guix was
that I needed to master Emacs prior to Guile
(Im highly flow orientated).

But again, even if this is a great option for you, it might be a really bad
option for some other people. Everybody does not have the time to spend
learning emacs, or other specific tool. It's ok if the workflow suggests that
but it's not great if we have no other alternative.

It's not accessible and imposes a barrier in some people.

Yeah agreed. And we should be consious of that.
Ironically by mandating Emacs and Email we force people to use specific
tools while at the same time even though the same people will complain(!) 
against vendor lock-in
like github.

There's no lock-in.  You can use any tool you want.  Most people hacking
on Guix do so with Emacs and Geiser because these are currently the best
tools (that I know of) to do the job; these are the tools many of us
know and can easily recommend.  If Visual Code (or editor X) was
packaged in Guix and had great support for working with Guile, we could
also mention it in our manual or in the cookbook.

Notice I use recommend rather than mandate; these are just
recommendations that try to be helpful.  If it's not helpful to you, you
are free to select your own tool box and share how it works (via patches
to the contributing section or a blog post for example).


There are two problems here though. Let me elaborate:

1. The "recommendations": (This is just an example)

I am a new person wanting to get involved or just tweak my config in 
guix/guile.


I go to the manual to learn package management, 
https://guix.gnu.org/en/manual/devel/en/guix.html#Package-Management


Apparently i have to either use the terminal or something called emacs. 
If I follow the guide located here: 
https://emacs-guix.gitlab.io/website/manual/latest/emacs-guix.html#Installation


It says to install emacs-guix. Okay. So apparently it is an Emacs thing, 
whatever that means. And when you start Emacs after installing the 
package, you are going to end up with Emacs in its plain form. 
Unfamiliar keybindings, no autocomplete, etc. Well thats no to Emacs 
then. The other thing is the terminal apparently. Horrible, but at least 
it works.


So what if I want to mess around with guile and the guix config directly?

If we check here it says to use something called Emacs again. So Im 
guessing its the same Emacs that was also apparent in the previous step 
with the config. but not there are more tools.


2. The contribute yourself your tools.

My point with all this is not to say its your fault or really anybody 
specific. Its more to say that:


Recommendations in an abstract sense work fine. But not in the real 
world. You proposed:


> If it's not helpful to you, you are free to select your own tool box 
and share how it works (via patches to the contributing section or a 
blog post for example). are free to select your own tool box and share 
how it works (via patches to the contributing section or a blog post for 
example).


How many people actually have the time and energy and know-how to do 
this? In the original email it was about a mother who on her spare time 
contributes to guix. Or as another example it could be about a person 
that just starts programming. Or it could be about a person that works 
and has few spare time.


Of course I saw in an email earlier in the thread that: "If you don't 
have time (as I do) then don't contribute." Which at the very least i 
find gross and not at all what guix is about.


Guix is supposed to be about equity. We are not all privileged (not 
saying you are or anybody else in this thread is.) enough to have the 
time and knowledge to learn Emacs, git-mail, find an email client that 
works (still havent found one. previous email was with the wrong email 
and threads are a nightmare.), and set up geiser and such.


The reason I have come to guix is because it strives to actually make it 
easier for people to change things. with guix shell and such. So making 
it easier for people to contribute is absolutely a part of it. Im not 
saying we should force every volunteer of course to do "work". What I am 
saying is:


- Guix recommendations in the manual, in the cookbook and other places, 
carry weight. In the sense that if to use something else than Emacs i 
have to write my own scripts or go to some random tutorial in a search 
engine then we have effectively pushed Emacs as the main guix platform. 
For better or worse. And we have excluded a portion of 

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

[MSavoritias]

On 9/7/23 23:38, Katherine Cox-Buday wrote:

On 9/5/23 2:43 PM, Liliana Marie Prikler wrote:

Am Dienstag, dem 05.09.2023 um 19:40 +0100 schrieb (:

Liliana Marie Prikler  writes:

Uhm, we have snippets?


Well, those are exclusive to Emacs :)  And without regard to /that/
issue, I do think that there's a problem if the commit format is so
complex that it's not trivial for anyone new to the project to write
them out manually.

By definition, no amount of typing is non-trivial, safe for the empty
amount, which good luck trying to commit your changes by pure mouse
movements, I guess?

Now, if you excuse my French, I think the problem isn't really as much
that people struggle to type out the perfect ChangeLog on the first
try, which also makes it odd to request a linter.  Bear in mind that
committers will sign off anything that appears convincing enough, even
if there are smaller mistakes in the message.  Trust me, I've been
there and seen that; and also done it myself.

Instead, we have seen in this thread appeals to age, appeals to
perceived lack of personal benefit, and now appeals to typing effort,
none of which really make that great of an argument against the
ChangeLog style, especially when they come in combination with a
refusal to make use of already provided tools.  I think we're starting
to see the moving of the goal post as the actual game here.

Maybe it's time to take a step back and instead of asking “How can we
decrease the cognitive overhead for contributors?”, we should perhaps
ask “For which contributors do we want to/can we decrease the cognitive
overhead?”  We have drifted much from the original post that discussed
moms with full-time jobs, who struggle to do “difficult” tasks
(simplified wording; may change the meaning of the OP a little).  Now,
I personally struggle to see how your personal preference for
communication media, commit message style, and other things that were
discussed in any of the preceding threads actually correlate with being
a parent.  However, I do know that with its 150 million users, most
people of the world don't have a Github account.  Being one of the 4
billion email users out there is a comparably low barrier of entry
imho.  So, whose cognitive overhead do you want to reduce (besides the
obvious "my own", which everyone always tries)?


Liliana, many of your responses in this thread are not OK. They have 
been dismissive and have strayed into personal attacks. At times I'm 
not sure if you're intentionally misinterpreting the conversation to 
try and make a point.


If you disagree with something, or have a point to make, please do so 
directly, and without attacking anyone's character or making veiled 
innuendos about their motives or capabilities.


Speaking for myself, I think if you asked me questions instead of 
inferring narratives, you'd find that our values and preferences are 
probably more closely aligned than you realize.


We're all here to try and make Guix better, but we can't do that in a 
hostile environment.



Completely agree with this too. I wanted to say that Katherine is not 
alone in feeling that some comments


in the thread have been dismissive or even elitist in a lot of cases. 
and one of the main people posting these


have been Liliana.

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

[MSavoritias]

On 9/6/23 23:10, Wojtek Kosior via Development of GNU Guix and the GNU 
System distribution. wrote:

Hello,

I wanted to add to this thread my 2 cents. As a person who has recently
(last months) made the first attempts at contributing.

To me, registrations and reliance on JS had always been an obstacle to
using web-based forges. This is one of the reasons I haven't been
contributing to existing projects in the past.

With Guix this issue is gone but there's also another thing that
incentivized me — that, since joining the Guix mailing lists, I am
seeing activity all the time, right at my fingertips (because I have my
email client opened most of the time).

So far I have sent patches 4 times. Once it was a simple update that got
accepted quickly, once I was addressing a problem that turned out to be
better solvable another way and 2 submissions are still waiting for
someone to review them.

Although I had to learn to use `git format-patch` and related tools, I
don't consider it a problem. Actually, I wanted to learn email-based
workflow anyway because it seems to be a more KISS way of software
development.

The amount of new stuff to learn can, however, be a bit overwhelming. I
did learn to use git to send emails but haven't yet started using any of
the templating packages for Emacs that were recommended in Guix
documentation. It would be just too much to process at once.

Do I think Guix has a problem with cognitive overhead? Not at all.
Rather, it seems to be addressing the problems really well.
1. It makes it easy to hack on itself without the need to clone the
repo first. That's what helped me get familiar with it before I
could even try to contribute anything.
2. It, by default, updates to the most up-to-date version.
3. It has some detailed documentation.
4. It eases the setting up of one's development environment.

I fact, I suspect the email-based workflow might be automatically
filtering out some bad submissions that would have been made otherwise.
The geeky nature of the project does put it in a kind of a niche where
only geeks dwell. But this is somewhat benefitial because geeks are
those who can build it.


Arguments that its a good thing its hard for people to contribute to the 
project don't really help.


Because among others it promotes gate-keeping and elitism. Im not saying 
you specifically are that person,


but that is how a person that wants to contribute will get the argument.


The part about email working for you, I am glad it does :)

We need to care for the people that may like a different style of 
contributing too though.


Because the more people guix can attract the better for the project.


MSavoritias



Lastly, sorry if something I wrote is a duplicate of other's opinions —
the thread got s long it'd be hard to read through 100% of it

Best,
Wojtek

-- (sig_start)
website: https://koszko.org/koszko.html
fingerprint: E972 7060 E3C5 637C 8A4F  4B42 4BC5 221C 5A79 FD1A
follow me on Fediverse: https://friendica.me/profile/koszko/profile

♥ R29kIGlzIHRoZXJlIGFuZCBsb3ZlcyBtZQ== | ÷ c2luIHNlcGFyYXRlZCBtZSBmcm9tIEhpbQ==
✝ YnV0IEplc3VzIGRpZWQgdG8gc2F2ZSBtZQ== | ? U2hhbGwgSSBiZWNvbWUgSGlzIGZyaWVuZD8=
-- (sig_end)


On Tue, 05 Sep 2023 22:43:04 +0200 Liliana Marie Prikler 
 wrote:


Am Dienstag, dem 05.09.2023 um 19:40 +0100 schrieb (:

Liliana Marie Prikler  writes:

Uhm, we have snippets?

Well, those are exclusive to Emacs :)  And without regard to /that/
issue, I do think that there's a problem if the commit format is so
complex that it's not trivial for anyone new to the project to write
them out manually.

By definition, no amount of typing is non-trivial, safe for the empty
amount, which good luck trying to commit your changes by pure mouse
movements, I guess?

Now, if you excuse my French, I think the problem isn't really as much
that people struggle to type out the perfect ChangeLog on the first
try, which also makes it odd to request a linter.  Bear in mind that
committers will sign off anything that appears convincing enough, even
if there are smaller mistakes in the message.  Trust me, I've been
there and seen that; and also done it myself.

Instead, we have seen in this thread appeals to age, appeals to
perceived lack of personal benefit, and now appeals to typing effort,
none of which really make that great of an argument against the
ChangeLog style, especially when they come in combination with a
refusal to make use of already provided tools.  I think we're starting
to see the moving of the goal post as the actual game here.

Maybe it's time to take a step back and instead of asking “How can we
decrease the cognitive overhead for contributors?”, we should perhaps
ask “For which contributors do we want to/can we decrease the cognitive
overhead?”  We have drifted much from the original post that discussed
moms with full-time jobs, who struggle to do “difficult” tasks
(simplified wording; may change the meaning of the OP a little).  Now,
I personally 

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

[Simon Tournier]

Hi,

On Thu, 14 Sep 2023 at 23:19, Sarthak Shah  wrote:

> I believe that it should not be very hard to create a user interface (web,
> ncurses or GUI) that searches for a package's location (the package record
> has a field that accommodates this) and then displays it, which the user
> can then edit.

A part already exists:

https://toys.whereis.みんな/
https://toys.whereis.みんな/?search=hello

Then click to location leads to:

https://git.savannah.gnu.org/cgit/guix.git/tree/gnu/packages/base.scm?id=master#n90

and note it also works for packages in some channels:

https://gitlab.inria.fr/guix-hpc/guix-hpc/-/blob/master/inria/mpi.scm#L26

However, that’s not possible to edit.  It would appears to me hard to
implement.  Because I do not see how it would be possible to implement
some edition features without a login – some login management is always
painful from my tiny experience.  Therefore, if you think “it should not
be very hard to create a user interface” that fulfills your description,
then I am sure many of us will appreciate to run your
implementation. :-p

Cheers,
simon

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

[Sarthak Shah]

I think that quite a few Guix users end up not committing to Guix because
of how daunting and strange the process seems.
In particular, having an alternate, easy-to-use interface for updating
package definitions specifically could be very useful.

The greatest strength of Guix is that it can be very easily integrated into
Guile programs.
I believe that it should not be very hard to create a user interface (web,
ncurses or GUI) that searches for a package's location (the package record
has a field that accommodates this) and then displays it, which the user
can then edit. We can then have the program build the package based on this
new definition, and if the user is satisfied with it it can format a patch
based on the edit and all the contributor will have to do is e-mail it.

This could greatly reduce the barrier to entry for contributing newer
package versions, but it could also open up the door to spam/misuse if we
host it on the web.

Regards,
Sarthak.

On Wed, 13 Sep, 2023, 17:54 Fannys,  wrote:

>
> Ekaitz Zarraga  writes:
>
> >> > This is what I mean when I say many times emacs is kind of mandatory,
> >> > and
> >> > this thread is kind of a demonstration of what I meant because the
> main
> >> > discussion evolved to: you can use this or that in emacs to ease the
> >> > dev
> >> > experience.
> >>
> >>
> >> One of the benefits of my being able to attend Guix Days was seeing
> >> peoples' workflows and stacks in person.
> >>
> >> As such, one of my conclusions having (already) committed to Guix was
> >> that I needed to master Emacs prior to Guile
> >> (Im highly flow orientated).
> >
> > But again, even if this is a great option for you, it might be a really
> bad
> > option for some other people. Everybody does not have the time to spend
> > learning emacs, or other specific tool. It's ok if the workflow suggests
> that
> > but it's not great if we have no other alternative.
> >
> > It's not accessible and imposes a barrier in some people.
>
> Yeah agreed. And we should be consious of that.
> Ironically by mandating Emacs and Email we force people to use specific
> tools while at the same time even though the same people will complain(!)
> against vendor lock-in
> like github.
>
>

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

[Ricardo Wurmus]

Fannys  writes:

>> But again, even if this is a great option for you, it might be a really bad
>> option for some other people. Everybody does not have the time to spend
>> learning emacs, or other specific tool. It's ok if the workflow suggests that
>> but it's not great if we have no other alternative.
>>
>> It's not accessible and imposes a barrier in some people.
>
> Yeah agreed. And we should be consious of that.
> Ironically by mandating Emacs and Email we force people to use specific
> tools while at the same time even though the same people will complain(!) 
> against vendor lock-in
> like github.

We don’t *mandate* the use of Emacs.  It’s just a common recommendation
because it works so well with text and is trivially extensible, so it’s
a common target for helper tools.  Surely we also wouldn’t call a
recommendation to use a shell script “vendor lock-in” just because it
needs Bash.

Emacs works well with text, and text is all that’s needed in a
patch-based workflow, which is in fact vendor agnostic.

Of course this doesn’t mean that it is as accessible as we’d want.

-- 
Ricardo

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

[Ricardo Wurmus]

MSavoritias  writes:

> Simon Tournier  writes:
>
>> Hi,
>>
>> On Tue, 29 Aug 2023 at 12:53, MSavoritias  wrote:
>>
>>> Do you know if there are any plans to write a scheme bug/patching
>>> system? Because looking a bit into it, it doesn't seem like its that
>>> actively developed so maybe we would be better served by one in scheme.
>>> Or Sourcehut of course as somebody wrote in another email.
>>> Since not much would change with sr.ht anyways.
>>
>> The only work I know is named tissue by Arun Isaac.  Arun also
>> contributes to Mumi (one web front-end of the venerable Debbugs instance
>> of the GNU project).
>>
>> https://tissue.systemreboot.net/
>> https://archive.fosdem.org/2023/schedule/event/tissue/
>>
>> Well, I am not convinced by the argument « we would be better served by
>> one in scheme ».  For instance, Cuirass or Build Coordinator or even
>> Mumi, all are implemented in Scheme and they are receiving very few
>> contributions.
>>
>> https://git.savannah.gnu.org/cgit/guix/guix-cuirass.git
>> https://git.savannah.gnu.org/cgit/guix/build-coordinator.git/
>> https://git.savannah.gnu.org/cgit/guix/mumi.git/
>>
>>
>> Cheers,
>> simon
>
> Its more about:
> If debbugs has issues and we dont fully control it and can make those
> improvements, why not something in scheme instead of sr.ht?

It’s an independent axis.  Limitations in Debbugs cannot be fixed
centrally because we don’t control the server.  If we did decide to
operate a bug tracker by ourselves it would suit us to pick one that
didn’t also require a lot of effort to work around annoyances.

The fact that we’ve used Scheme for a number of tools that don’t see
many contributions aside from those who initially wrote them is a good
reminder to adjust our expectations.


-- 
Ricardo

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

[Ekaitz Zarraga]

Hi,

On Wednesday, September 13th, 2023 at 3:42 PM, Maxim Cournoyer 
 wrote:

> 
> There's no lock-in. You can use any tool you want. Most people hacking
> on Guix do so with Emacs and Geiser because these are currently the best
> tools (that I know of) to do the job; these are the tools many of us
> know and can easily recommend. If Visual Code (or editor X) was
> packaged in Guix and had great support for working with Guile, we could
> also mention it in our manual or in the cookbook.
> 
> Notice I use recommend rather than mandate; these are just
> recommendations that try to be helpful. If it's not helpful to you, you
> are free to select your own tool box and share how it works (via patches
> to the contributing section or a blog post for example).

Of course, but it's limiting because there's no other recommendation than that.
Everything is built around it with no sensibility to any other approach.

Many times I've been answered how to solve my problems using emacs and a big
part of this conversation evolved in that direction, proposing technological
solutions to human problems in emacs, and only for emacs, ignoring the fact
that many guix users are not emacs users and also that technology is not the
root issue of this.

If you have a hammer everything look like nails I guess, and we are
programmers, there's nothing shameful about that, but if we really want to be
welcoming we have to be more than just programmers. Maybe that's something not
all of us should do, but some. I don't know.

Further than that. I'll try to summarize my views on this because I think we
diverged a lot in that direction and it would be a shame to miss this
opportunity to be more welcoming.


## Boring stuff coming, you have been warned

The technology itself is not a real deal most of the times. Sometimes it can
be: should I recompile the project? How do I configure the development
environment? Why my setup has to be a little bit worse if I'm not working with
emacs? How do I contribute my patch with the email provider of my choice? Can I
just paste the patch in the body of the email? Maybe attach it? Which one is
better? One patch per email? Maybe I'm bothering people asking the same thing
over and over again?

Most of those are a matter of getting used to some things that might be hard at
the beginning. I'm sure Katherine, who started this thread is not really
limited in a technical level, as I am not. We might be limited in the amount of
time needed to get used to these things and we don't want to bother
maintainers and commiters with stupid errors we feel like we are committing
over and over again because we don't have a solid reference for some of these
things. Examples of missing pieces of information:

> If you can't use `git send-mail` for a reason you can do this and that and
> that instead.

> If you are not an emacs user you can try this and that. (*probably this is
> something we, non-emacs users, should write*)

Example of a good way to do it, (maybe it's missing a reference in the docs):

https://guix.gnu.org/en/blog/2021/the-big-change/

Political/management decisions often more complex to deal with. Changelog style
is, in my opinion, useless, but it's not hard to follow if there are good
guides on how to do it well. There are other changes in the way packages are
described that are hard to follow too. Just copying what other people did is
not enough, probably because we don't feel like we can control what we are
doing. It's some kind of a trial and error process that always ends up in the
hands of the commiter or maintainer that receives our patches.

My take is: *check what other packages/commits do* is not a real answer. The
same way reading some English is not enough to write English yourself
comfortably. We need guidance or clearly written stuff that is *easy* to find.
Most of these questions are answered in the mailing list, the same way I think
Liliana very well explained how Changelog commits have to be done, but it's not
written in Guix itself (there's a link in the manual) by Guix and *for* Guix.

I would prefer to use other kind of tooling. Sourcehut is interesting as it
provides a way to keep the same email based approach we use, but with some
extra goodies, but I'm also OK with what we currently have. So that's not a big
deal for me at this point. I can say I'm starting to get used.

If we had a *very clear* guide, that would be way better for contributors. Not
just about Guix, but about all those other things that happen around. And I
don't mean a copy/paste tuto, but something were decisions are explained with
the goals they have.

(As a note, the GNU Standard for Changelog commit messages has some examples
that are way more verbose than the ones we have in Guix. IMHO those have a lot
of sense, the commit messages we do in Guix most of the times don't.)


The final point I would like to insist on is the contribution experience. I
don't really know how the issue system works as a whole. We have 

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

[Maxim Cournoyer]

Hi Fannys,

Fannys  writes:

> Ekaitz Zarraga  writes:
>
>>> > This is what I mean when I say many times emacs is kind of mandatory,
>>> > and
>>> > this thread is kind of a demonstration of what I meant because the main
>>> > discussion evolved to: you can use this or that in emacs to ease the
>>> > dev
>>> > experience.
>>> 
>>> 
>>> One of the benefits of my being able to attend Guix Days was seeing
>>> peoples' workflows and stacks in person.
>>> 
>>> As such, one of my conclusions having (already) committed to Guix was
>>> that I needed to master Emacs prior to Guile
>>> (Im highly flow orientated).
>>
>> But again, even if this is a great option for you, it might be a really bad
>> option for some other people. Everybody does not have the time to spend
>> learning emacs, or other specific tool. It's ok if the workflow suggests that
>> but it's not great if we have no other alternative.
>>
>> It's not accessible and imposes a barrier in some people.
>
> Yeah agreed. And we should be consious of that.
> Ironically by mandating Emacs and Email we force people to use specific
> tools while at the same time even though the same people will complain(!) 
> against vendor lock-in
> like github.

There's no lock-in.  You can use any tool you want.  Most people hacking
on Guix do so with Emacs and Geiser because these are currently the best
tools (that I know of) to do the job; these are the tools many of us
know and can easily recommend.  If Visual Code (or editor X) was
packaged in Guix and had great support for working with Guile, we could
also mention it in our manual or in the cookbook.

Notice I use recommend rather than mandate; these are just
recommendations that try to be helpful.  If it's not helpful to you, you
are free to select your own tool box and share how it works (via patches
to the contributing section or a blog post for example).

-- 
Thanks,
Maxim

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

[MSavoritias]

> Wed, 02 Aug 2023 12:37:57 +0200
> id:cover.1690972374.git.l...@6xq.net
> https://issues.guix.gnu.org//65010
> https://issues.guix.gnu.org/msgid/cover.1690972374.git.l...@6xq.net
> https://yhetil.org/guix/cover.1690972374.git.l...@6xq.net
>
> then, one will do reply and probably comment one or more patches over
> the 8.  Then, it is harder for another person to follow.  For example, I
> would have to open the message in order to know that this series adds,
>
> guix: toml: Add TOML parser.
>
> which could be interesting for Julia.  And I would probably skip all the
> series because the subject is about Python build system improvements
> that I am necessary following.  However, if I see the subject,
>
> guix: toml: Add TOML parser.
>
> then I open the message and read it.
>
> Therefore, I do not see any “good” solution for this point #22.  One
> idea would be to have a kind of proxy.  We would send the whole series
> to an hypothetical guix-contributi...@gnu.org and then a bot would send
> to guix-patches for getting an ID and that bot would send the series to
> that ID, probably adding some X-Debbugs-CC for the submitter (and for
> teams).  Bah, too much “would”. :-)
>
>
> 1: https://yhetil.org/guix/87wmx8m5gb.fsf@wireframe
> Re: How can we decrease the cognitive overhead for contributors?
> Vagrant Cascadian 
> Sat, 02 Sep 2023 18:05:40 -0700
> id:87wmx8m5gb.fsf@wireframe
> https://lists.gnu.org/archive/html/guix-devel/2023-09
>
>
>> If I compare this workflow to the workflow of other contributions I make:
>>
>>    1-10 as usual
>>    11. Write a more commonly accepted commit message with no special 
>> formatting.
>
> This depends on the project and I am not convinced we can rule for #11.
>
> BTW, one strong advantage for this commit message format is that grep
> can be exploited.  For some reasons, I am often looking for some past
> versions, for example,
>
> $ git log --pretty="%h %s" | grep Update | grep vlc
> 8d342711dd gnu: vlc: Update to 3.0.17.4.
> 5a29cc9ade gnu: vlc: Update to 3.0.17.3.
> fb0e5874ec gnu: vlc: Update to 3.0.16.
> e2ad110f4c gnu: vlc: Update to 3.0.14.
> def314d810 gnu: vlc: Update to 3.0.12.
> 6ec120b1c7 gnu: vlc: Update to 3.0.11.1.
> 0bed485a39 gnu: vlc: Update to 3.0.11.
> 178f1d1f75 gnu: vlc: Update to 3.0.8.
> cf40f8e4d7 gnu: vlc: Update to 3.0.7.1.
> 94f7f9503a gnu: vlc: Update to 3.0.7.
> dba326def1 gnu: vlc: Update to 3.0.6.
> ea593fe298 gnu: vlc: Update to 3.0.5.
> d0e23e3940 gnu: vlc: Update to 3.0.3, and add more inputs.
> 7627705293 gnu: vlc: Update to 3.0.3, and add more inputs.
> f137f84923 gnu: vlc: Update to 2.2.8 [fixes CVE-2017-9300, CVE-2017-10699].
> dd13aa90d6 gnu: vlc: Update to 2.2.6.
> 3bc45ad460 gnu: vlc: Update to 2.2.5.1.
> a134cc8e93 gnu: vlc: Update to 2.2.4 [fixes CVE-2016-5108].
> c6c86cd7a5 gnu: vlc: Update input Qt to version 5.
> 9c55bae607 gnu: vlc: Update to 2.2.1.
> 1a189da0e7 gnu: vlc: Update to 2.2.0.
> b9156ccc08 Revert "gnu: vlc: Update to 2.2.0"
> ad036bda89 gnu: vlc: Update to 2.2.0
> 23466647a8 gnu: vlc: Update to 2.1.5.
>
>
> And because there is some variation with the commit message format,
> these are not all the updates of VLC,
>
> $ git log --pretty="%h %s" | grep Update | grep VLC
> af74211d98 gnu: VLC: Update to 3.0.18.
> 5af110868c gnu: VLC: Update to 3.0.10.
> 091ef8c97e gnu: VLC: Update to 3.0.4.
> 324c049ff6 gnu: VLC: Update to 3.0.3-1 [fixes CVE-2018-11529].
>
> Then “guix time-machine --commit=fb0e5874ec -- shell vlc” and hop I get
> 3.0.16.  If the commit message format would not be so strict, this would
> be impossible and we would need another external tool.
>
>
>>    12. Run `git push` (subsequent changes are still just `git push`).
>>    13. Go to forge website, click button to open a pull-request.
>>    14. Wait for CI to tell you if anything is wrong.
>
> To be fair, here you forget one important blocker: having an account to
> the forge website.
>
> I do not speak about freedom issues.  Just about the fact to open an
> account to the forge website.  For example, let consider this project:
>
> https://framagit.org/upt/upt
>
> And if I want to contribute with a Merge-Request, I need to open an
> account to the Gitlab instance of FramaGit and push my code to this
> instance, even if I already have my fork living on my own Git
> repository and I have no plan to use this FramaGit forge.
>

Bear in mind that Sourcehut accepts patches without an account and there
is forgefed https://forgefed.org/ for forges federation. which forgejo
has support https://forgejo.org/

MSavoritias

>> If you're so inclined, for a bit of fun, and as a crude way of simulating
>> compromised executive functioning, imagine that between each of the 
>> steps above,
>> a year passes. And reflect on what it would be like to gather the energy to
>> start the process of starting a contribution of some kind, let alone 
>> follow it
>> through to completion.
>
> I like this way of thinking because it helps to spot some blockers.
>
> Please note that it is not truly about the complexity of the steps but
> about how many steps one is able to complete between two interruptions.
> Well, it is a well-known issue about task switching [1]. :-)
>
> 1: https://en.wikipedia.org/wiki/Task_switching_(psychology)
>
> Cheers,
> simon

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

[MSavoritias]

I dont think we need to compare things here. Of course we should be able
to make lives easier for reviewers and contributors. There is no need
here to compare them. Remember that making lives easier for contributors
will make lives easier for reviewers too after all :) Because more
correct pathces and more people wanting to be involved.
Hence me saying its not a comparison or focusing on one or the
other. But more of the same thing.

As I mentioned in another point in the thread we already have
"non-standard" stuff so that argument doesn't really hold water
here. Non standard stuff being emacs, mumi and a bunch of other stuff
that make submissions tolerable. Or emacs-debbugs.

Also yes "visual" flow helps some people. Nothing wrong with that and we
should encourage that. (Encrourage that by fully supporting it). I mean i am 
trying to use the cli as less as
possible since its a horrible interface.

And yes the gnu commit messages could be improved. Its not like they are
set in stone anyway.

MSavoritias

Giovanni Biscuolo  writes:

> [[PGP Signed Part:Undecided]]
> Hello Katherine,
>
> thank you for having summarized (part of) this thread in a list of
> actionable tasks
>
> now Someone™ have the chance to decrease the cognitive overhead for
> contributors by _increasing_ her cognitive overhead to sort out and
> complete each task
>
> as a general comment, it seems to me that you put very much attention to
> the process of contributing v1 of a patch but you underestimate the
> cognitive overhead of the collective patch reviewing process and
> committing to Guix proper process
>
> AFAIU, observing what is happening in Guix since 2019, what is actually
> critical for Guix is _not_ the cognitive overhead needed to send a patch
> to guix-devel, but what comes after and _around_.
>
> last but not least, to be fair we should see at what other distribution
> (not single software projects) are doing for their contributing process:
> I know a little about Debian and in my experience it's far easier to
> contribute to Guix than to Debian (but I know little, I emphasize)
>
> Katherine Cox-Buday  writes:
>
>> Summary of my conclusions:
>>
>> 1. We should use sourcehut or continue to improve mumi
>
> Please forgive me if I insist, but the one and _only_ benefit of using
> SourceHut is the web-UI /helper/ to prepare an email message to send,
> it's "just" a web-UI version of the "git format-patch" CLI; the rest of
> the "patch management workflow" is email **and** CLI (git am) based;
> it's documented.
>
> Furthermore, users that are comfortable with the SourceHut web UI are
> free to use that as their personal working repo, there is no need for
> Guix to use a SourceHut remote as the official one.
>
>>     - QA status should be visable from a patch's page
>
> On mumi web interface, in each issue page related to a patch, there is a
> "badge" linking to the QA status for that patch, right below the issue
> title; i.e.:
>
> https://issues.guix.gnu.org/65694
>
> have a link to https://qa.guix.gnu.org/issue/65694
>
> QA (and relates services, like data.qa) is a great project that could
> greatly improve current situation when completed!
>
>>     - It should be possible to interact with the issue through the
>>  page
>
> I don't exactly understand: what do you mean with "interact"?
>
> ...and what page?  https://issues.guix.gnu.org/ or
> https://qa.guix.gnu.org/issue/65694 (or any other issue)
>
>> 2. We should create scripts/sub-commands to lift contribution activities 
>> into
>>     higher-order concepts:
>>     - Prepare a new submission
>>     - Run pre-checks on a submission
>>     - Submit a patch
>>     - Status of patch
>
> AFAIU you already use some of this "lifting" scripts od commands: can
> you please send patches so thay could possibly be included in Guix
> proper or in some section of the Cookbook?
>
> [...]
>
>> On 8/28/23 4:17 AM, Simon Tournier wrote:
>
> [...]
>
>>  > In order to be pragmatical and list actionable items, could you
>>  > specifically list what you consider as a toil or cognitive overhead?
>>  > Maybe you could share your script helping you.
>>
>> Yes, great point! Let's try to distill all this conversation down into the
>> salient points and see if we can't agree on some actionable items.
>>
>> Here's my understanding of the process to contribute a patch:
>>
>>    1. Check out main, and run `./bootstrap`, then `./configure 
>> --localstatedir=/var --sysconfdir=/etc`
>>    2. Run `make`
>>    3. You need to determine whether the change can be targeted against 
>> main or
>>   needs to target a feature branch, so you go read about that.
>
> [...]
>
>> In other projects I've worked with, steps 12-19 are commonly done in a CI
>> pipeline, and courteous people will try to save CI resources by running 
>> these
>> steps locally first using some kind of environment identical to what CI runs
>> (sometimes a container is used for this. I think Guix has better options!).
>> Sometimes this is 

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

[MSavoritias]

Simon Tournier  writes:

> Hi,
>
> On Tue, 29 Aug 2023 at 12:53, MSavoritias  wrote:
>
>> Do you know if there are any plans to write a scheme bug/patching
>> system? Because looking a bit into it, it doesn't seem like its that
>> actively developed so maybe we would be better served by one in scheme.
>> Or Sourcehut of course as somebody wrote in another email.
>> Since not much would change with sr.ht anyways.
>
> The only work I know is named tissue by Arun Isaac.  Arun also
> contributes to Mumi (one web front-end of the venerable Debbugs instance
> of the GNU project).
>
> https://tissue.systemreboot.net/
> https://archive.fosdem.org/2023/schedule/event/tissue/
>
> Well, I am not convinced by the argument « we would be better served by
> one in scheme ».  For instance, Cuirass or Build Coordinator or even
> Mumi, all are implemented in Scheme and they are receiving very few
> contributions.
>
> https://git.savannah.gnu.org/cgit/guix/guix-cuirass.git
> https://git.savannah.gnu.org/cgit/guix/build-coordinator.git/
> https://git.savannah.gnu.org/cgit/guix/mumi.git/
>
>
> Cheers,
> simon

Its more about:
If debbugs has issues and we dont fully control it and can make those
improvements, why not something in scheme instead of sr.ht?
But i could go either way.

MSavoritias

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

[MSavoritias]

Ekaitz Zarraga  writes:

>> > This is what I mean when I say many times emacs is kind of mandatory,
>> > and
>> > this thread is kind of a demonstration of what I meant because the main
>> > discussion evolved to: you can use this or that in emacs to ease the
>> > dev
>> > experience.
>> 
>> 
>> One of the benefits of my being able to attend Guix Days was seeing
>> peoples' workflows and stacks in person.
>> 
>> As such, one of my conclusions having (already) committed to Guix was
>> that I needed to master Emacs prior to Guile
>> (Im highly flow orientated).
>
> But again, even if this is a great option for you, it might be a really bad
> option for some other people. Everybody does not have the time to spend
> learning emacs, or other specific tool. It's ok if the workflow suggests that
> but it's not great if we have no other alternative.
>
> It's not accessible and imposes a barrier in some people.

Yeah agreed. And we should be consious of that.
Ironically by mandating Emacs and Email we force people to use specific
tools while at the same time even though the same people will complain(!) 
against vendor lock-in
like github.

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

[Fannys]

Ekaitz Zarraga  writes:

>> > This is what I mean when I say many times emacs is kind of mandatory,
>> > and
>> > this thread is kind of a demonstration of what I meant because the main
>> > discussion evolved to: you can use this or that in emacs to ease the
>> > dev
>> > experience.
>> 
>> 
>> One of the benefits of my being able to attend Guix Days was seeing
>> peoples' workflows and stacks in person.
>> 
>> As such, one of my conclusions having (already) committed to Guix was
>> that I needed to master Emacs prior to Guile
>> (Im highly flow orientated).
>
> But again, even if this is a great option for you, it might be a really bad
> option for some other people. Everybody does not have the time to spend
> learning emacs, or other specific tool. It's ok if the workflow suggests that
> but it's not great if we have no other alternative.
>
> It's not accessible and imposes a barrier in some people.

Yeah agreed. And we should be consious of that.
Ironically by mandating Emacs and Email we force people to use specific
tools while at the same time even though the same people will complain(!) 
against vendor lock-in
like github.

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

[Simon Tournier]

Re,

On Wed, 13 Sep 2023 at 09:57, Simon Tournier  wrote:

> Somehow, the line is drawn using a two-axis plot of “easy vs boring”
> when instead we should draw a two-axis plot of “complexity vs capture
> the values”.

I meant, the thread is considering a one-axis plot using a subjective
parameter from “easy“ to “boring” and splits this line into two
subparts.  Instead, we should consider a two-axis plot using the
parameters “complexity” and “capture the value”.  Somehow. :-)

Cheers,
simon

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

[Simon Tournier]

Hi Katherine,

On Tue, 12 Sep 2023 at 10:05, Katherine Cox-Buday  
wrote:

> And these are subjective statements, which are bad to rest decisions on. 
> I have the opinion that this style of commit message is difficult and 
> doesn't have a lot of value; others think it's easy and find a lot of 
> value in it.

About commit message format, I think this is the knot.  Because the
discussion is focused on “easy vs difficult“ and there is no “real”
answer on this frame.

Instead, the question appears to me about “complexity vs value”.

The questions are not about pros and cons for some non well-defined
ChangeLog-like commit format message, but what are the values of the
commit messages for the project?

Could you explain what are the values, from your perspective, about the
commit message for the Guix project?  Whatever the message format.

The next question is then: does the current ChangeLog-like format
capture these values?  Or is another format that captures these values?

The ChangeLog-like format is a mean for an end.  As it is noticed
elsewhere in the thread, this ChangeLog-like format fills an historical
end.  Here you say the ChangeLog-like «doesn't have a lot of value» but,
if I have read correctly this thread, no one has explicitly said what is
this end that the project wants?  It is only with this angle of a more
or less defined end that the mean can be scrutinized, IMHO.

WDYT?


> I don't place much emphasis on my opinion or others' on this, but I 
> place an enormous emphasis on the existence of the two groups. We should 
> be curious why the two groups hold their opinions, and curious about a 
> mutual path forward.

I agree that the thread draws a line with two groups.  However, this
line is set using some personal preferences comparing apple to orange.

For example, I also find “boring” the kind of strictness of the
ChangeLog-like format so my personal preference would be tempted to
belong to group A.  In the same time, I recognize that this
ChangeLog-like format provides helpful structure so my personal
preference would be tempted to belong to group B.

However, if I first list what I consider as the values for the commit
messages at the project level, then the ChangeLog-like format appears to
me filling the needs.

Somehow, the line is drawn using a two-axis plot of “easy vs boring”
when instead we should draw a two-axis plot of “complexity vs capture
the values”.

Bah, I do not know.  Maybe, what I am saying makes no sense. :-)

Cheers,
simon

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

[Simon Tournier]

Hi Maxim,

On Tue, 12 Sep 2023 at 10:42, Maxim Cournoyer  wrote:

>> Even before looking at it, I have to spend some time to find a way to
>> manually apply the patches.  Then, rebasing on the top of master could
>> lead to conflict but that another story and the same appears whatever
>> the workflow.
>
> I think this kind of problem has improved though, since we deploy by
> default our etc/git/config snippet, which sets 'useAutoBase = true'.
>
> At least I don't have a problem when applying patches with 'git am -3s'.

We are drifting. :-)

This branch of the looooong thread starts with:

    Re: How can we decrease the cognitive overhead for contributors?
Attila Lendvai 
Fri, 25 Aug 2023 08:07:53 +

id:JRUs8LVm3AtAh0MnHjE5rnhB4sNET0vWTOO2N3w2KfvKoM3CALRNwHTmwJ0Y9Bg3ZDWCs8j-1bMCo9aRiaoac8TAkuXAvrWgSwt_8RcwhQA=@lendvai.name

https://yhetil.org/guix/JRUs8LVm3AtAh0MnHjE5rnhB4sNET0vWTOO2N3w2KfvKoM3CALRNwHTmwJ0Y9Bg3ZDWCs8j-1bMCo9aRiaoac8TAkuXAvrWgSwt_8RcwhQA=@lendvai.name
https://lists.gnu.org/archive/html/guix-devel/2023-08

Attila speaks about the PR model.  Then many comments later about the
pros and cons, the discussion is split intro the contributor side and
the reviewer side of the PR model.  Ricardo reports then their
experience reviewing Pull Request:

    Re: How can we decrease the cognitive overhead for contributors?
Ricardo Wurmus 
Fri, 08 Sep 2023 16:44:41 +0200
id:87sf7o67ia@elephly.net
https://yhetil.org/guix/87sf7o67ia@elephly.net
https://lists.gnu.org/archive/html/guix-devel/2023-09

And I provide one typical example where “our“ model leads to some
friction for the reviewer: the first step, apply the patches.

And this exact same friction does not exist in the PR model by design of
this very PR model.  I am not saying the PR model is perfect and I am
not saying “our” workflow is crappy.  I just agree with Ricardo
messages.

Now, yes this kind of problem is improving.  Please note that the
problem is not new and I am aware of it. :-) I submitted on October 2020
the first mention of ‘git format-patch --base’ in the “Submitting
Patches” section and d18b787d8a5cada8d239f1335257d0c1bca7f825 had been
pushed only on September 2021.

For whatever reason, sometimes patches fall into some cracks or are
badly formatted or something else.  Then, applying them becomes boring.
I am not saying that’s impossible, I am just saying that sometimes we
have a friction (something that has no value for the project) because of
our workflow.

I am not speaking on the vacuum of an hypothetical problem but I am
using a concrete example patch#62202 from my own pile.

Using the usual “git am -3s” from Emacs Debbugs, then I get:

--8<---cut here---start->8---
Applying: import: juliahub: first script draft.
error: sha1 information is lacking or useless (guix/import/go.scm).
error: could not build fake ancestor
hint: Use 'git am --show-current-patch=diff' to see the failed patch
Patch failed at 0001 import: juliahub: first script draft.
When you have resolved this problem, run "git am --continue".
If you prefer to skip this patch, run "git am --skip" instead.
To restore the original branch and stop patching, run "git am --abort".
--8<---cut here---end--->8---

Ok, maybe that’s because some empty commit message (I did not know that
and I had to search using search engine, well I do not know), let’s try
with “git apply”, then I get:

--8<---cut here---start->8---
error: patch failed: guix/import/go.scm:503
error: guix/import/go.scm: patch does not apply
--8<---cut here---end--->8---

Ok, that’s maybe this file had been modified.  So I do,

--8<---cut here---start->8---
$ git log --format="%h %cd %s" -- guix/import/go.scm
ae587c2ef041 Mon Mar 13 15:08:33 2023 +0100 guix: Strip #:use-module lists.
3c24da4260f2 Sat Dec 31 14:48:46 2022 +0100 import/utils: Pass all arguments 
through to package builder.
c1db66fa0a17 Sun Jan 9 23:17:17 2022 +0100 import: go: Correctly report 
diagnostics upon version mismatch.
--8<---cut here---end--->8---

And I checkout ae587c2ef041.  Same error.  The parent of ae587c2ef041.
Same error.  And I checkout 3c24da4260f2.  Same error.  Ok, do I try
with b4?

Well, at this point, do we agree there is useless friction? :-)

Maybe I am missing the obvious.  Maybe that’s a rare case.  That’s just
one from my pile.  And I see that time to time.

After 15 minutes today (and 10-15 minutes on April, 7th = 24 days after
the submission), I just give up.  And it ends on some eternal postponing
on my side; until I will just copy manually the 21 patches and manually
recreate the 21 

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

[Katherine Cox-Buday]

On 9/8/23 2:37 PM, Ricardo Wurmus wrote:


Liliana Marie Prikler  writes:


Am Freitag, dem 08.09.2023 um 17:27 +0200 schrieb Ricardo Wurmus:

I have the same positive view on our faux ChangeLogs commit messages,
though I also would like to have them generated.  The benefit is
still there: I still get to *review* an effective summary of the
changes before pushing or sending them off for review.  But at least
I don’t have to write them myself.

Now, this is no longer a problem for me because I’ve been writing so
many commit messages over the years (and because I no longer try to
adhere to some poorly specified format), but it *is* a problem for
people that I’ve mentored.

etc/committer.scm and the yasnippets are supposed to alleviate some
of the pain, but I don’t need to think for a long time to come up
with a number of improvements in this area.

Can I assume this to mean it'd take you some short time to think of
snippets that we're currently lacking?  If so, please do contribute
them.  If not, what do you mean then?


I mean that they have plenty of defects.

When I wrote the first few iterations of etc/committer.scm it was only
really meant and good for bulk package updates (= lots of changes across
files, all upgrades).  It couldn’t (and maybe still can’t) reliably
detect added or removed package definitions.  It doesn’t handle changes
to the arguments field.  It’s also terribly slow because it naively
recomputes information for every hunk in the diff, reading package
definitions from the old vs the changed file after every commit.

The update yasnippet repeatedly gets the order of lines wrong when
adding a patch to dist_patch_DATA in gnu/local.mk; it also doesn’t do
what etc/committer.scm is already able to do: detecting changes to
inputs.  Configuring yasnippet is also not trivial for people who don’t
regularly use Emacs (the snippets are tied to modes set by magit).

I think in light of these defects “Uhm, we have snippets?” isn’t a
satisfying response.


Also, from my original message:

   I use the templates provided, but those don't cover all cases, 
and I've

   even gotten feedback in a review to change a message it created.

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

[Katherine Cox-Buday]

On 9/8/23 5:28 AM, Ricardo Wurmus wrote:


Katherine, I’m very happy you brought this up and continue to respond in
this thread to clarify and steer the discussion into a fruitful
direction.  I know I couldn’t do it.  I thank you for this work, and I
hope that the project can come up with ways to lower the barriers to
entry.


Thanks for saying so, Ricardo, and thank you for all of your 
contributions to Guix. When I think fondly of the project, yours is one 
of the names that springs to mind.

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

[Katherine Cox-Buday]

On 9/8/23 6:40 AM, Giovanni Biscuolo wrote:

Ricardo,

Ricardo Wurmus  writes:


Giovanni,


You are obviously free not to contribute your patches upstream but the
fact that you decided not to because it's "too hard" (my executive
summary about your complaints about Change Log content rules) to write
commit messages suitable for contribution it _not_ a Guix maintainers
fault, not at all.


As a former Guix co-maintainer I disagree with this take.  (Nobody even
brought up the word “fault”, which is a particularly unhelpful lens for
understanding social issues, in my opinion.)


sorry for using "fault", I can't find a better term


“too hard” sounds (perhaps unintentionally) derisive.


the complete sentence is: «"too hard" (my executive summary about your
complaints about Change Log content rules)»

what can I add about my intentions?

[...]


It’s not that writing commit messages is hard.  It’s one of many
obstacles,


IMO one of the very little ones


Taking a single step is trivial. Walking a thousand miles is difficult. 
The aggregate is the thing that matters most!


And these are subjective statements, which are bad to rest decisions on. 
I have the opinion that this style of commit message is difficult and 
doesn't have a lot of value; others think it's easy and find a lot of 
value in it.


I don't place much emphasis on my opinion or others' on this, but I 
place an enormous emphasis on the existence of the two groups. We should 
be curious why the two groups hold their opinions, and curious about a 
mutual path forward.


Instead of setting up camp and throwing rocks, let's share a meal and 
create a better way for everyone.



We can’t blame anyone for seeing these two piles and come to the
conclusion that it’s not worth the hassle — especially when operating
your own channel is so easy in comparison.


I'm not blaming Katherine, I respect her decision; I just wanted to say:
please don't blame the guidelines about ChangeLog for the two (or more)
piles.


No hard feeling, Gio. I want to echo what Ricardo is saying: viewing 
these conversations through the lens of blame and fault is not the 
intent, and is not helpful. In my original message I intentionally said 
that this was not a list of grievances, but an attempt to describe the 
"shape" of the problem.


While I do search for root-causes to issues, it's not done with the 
intent to cast blame on something. It's done with curiosity, and the 
desire to make the situation better for everyone.

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

[Katherine Cox-Buday]

On 9/11/23 6:19 AM, Giovanni Biscuolo wrote:


If you want I can add a little bit of Italian attitide at discussing in
detail tiny variations of the same thing :-O... just joking, eh! ;-)


One of the reasons I love working with people from around the world is 
the delight in discovering that despite real cultural differences, we 
are all human.


I think discussing minute details in a search to be perfectly understood 
is a very human thing that transcends cultures :)

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

[Maxim Cournoyer]

Hi,

Csepp  writes:

> Giovanni Biscuolo  writes:
>
>> [[PGP Signed Part:Undecided]]
>> Hello Csepp, 
>>
>> Csepp  writes:
>>
>> [...]
>>
>>> I don't think repeating that no forge sucks less advances the
>>> conversation towards any solution other than keeping the status quo,
>>> which can't really be called a solution.
>>
>> Are we really talking about changing the official Guix forge:
>> https://savannah.gnu.org/projects/guix?
>
> I definitely am.

The real place to put efforts toward that goal should be in the GNU
project; this way we can continue to maintain shared resource, knowledge
and tooling as a project.  I think packaging either sourcehut or gitea
and writing a Guix System service for it would provide opportunities to
experiment and perhaps one day move in that direction, so that's
something concrete that you can direct your efforts too.

-- 
Thanks,
Maxim

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

[Maxim Cournoyer]

Hi Simon,

Simon Tournier  writes:

> Hi Liliana,
>
> On Mon, 11 Sep 2023 at 19:53, Liliana Marie Prikler 
>  wrote:
>
>> For "patch does not apply", the forge solution is typically to send a
>> notification to the issuer.
>
> No, that does not match my small experience.  Because often the issuer
> is gone or not responding.  As a reviewer using the forge solution, I am
> still able to pull the issuer branch and then resolve the conflicts if
> any.
>
> Using “our” workflow, I fail earlier in the process.  I am not able to
> apply the patches against any branches (pull the PR somehow).  An
> example:
>
> [bug#62202] [PATCH 0/21] Juliahub import script.
> https://issues.guix.gnu.org/msgid/871qlq89kz@ngraves.fr
>
> Even before looking at it, I have to spend some time to find a way to
> manually apply the patches.  Then, rebasing on the top of master could
> lead to conflict but that another story and the same appears whatever
> the workflow.

I think this kind of problem has improved though, since we deploy by
default our etc/git/config snippet, which sets 'useAutoBase = true'.

At least I don't have a problem when applying patches with 'git am -3s'.
I don't see what is specially difficult here (perhaps there are too many
options available to do the task?), but we could document some ways,
perhaps adding a new 'Reviewing others work' section to the Contributing
node?  It could show how to do it from either an Gnus perspective
(Emacs) or via 'wget -O- $mumi_url | git am -3s' etc.  and provide some
guidance, perhaps with a link to

until this is automated in a 'guix review' command or similar.

-- 
Thanks,
Maxim

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

[Csepp]

Giovanni Biscuolo  writes:

> [[PGP Signed Part:Undecided]]
> Hello Csepp, 
>
> Csepp  writes:
>
> [...]
>
>> I don't think repeating that no forge sucks less advances the
>> conversation towards any solution other than keeping the status quo,
>> which can't really be called a solution.
>
> Are we really talking about changing the official Guix forge:
> https://savannah.gnu.org/projects/guix?

I definitely am.

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

[Giovanni Biscuolo]

Hello Csepp, 

Csepp  writes:

[...]

> I don't think repeating that no forge sucks less advances the
> conversation towards any solution other than keeping the status quo,
> which can't really be called a solution.

Are we really talking about changing the official Guix forge:
https://savannah.gnu.org/projects/guix?

When talking about "what forge to use" I feel that keeping the status
quo is a very good solution, overall.

Thanks, Gio'

-- 
Giovanni Biscuolo

Xelera IT Infrastructures


signature.asc
Description: PGP signature

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

[Csepp]

Giovanni Biscuolo  writes:

> [[PGP Signed Part:Undecided]]
> Hi Liliana,
>
> Liliana Marie Prikler  writes:
>
> [...]
>
>> For example, whenever people say that "forges would improve stuff", my
>> reply is (modulo phrasing) "yes, for the people who are already used to
>> forges".
>
> I just want to point out that actually Guix _do_have_ a forge. the
> software is Savane and it's hosted on savannah.gnu.org:
> https://savannah.gnu.org/projects/guix
>
> This is just to remind everyone that there are very different forges out
> there, and:
>
>   All forges suck, _no one_ sucks less

To quote the elementary HIG:
"Design is not just, like, your opinion, man"
https://docs.elementary.io/hig/design-philosophy#design-is-not-just-like-your-opinion-man

Just because two alternatives are both imperfect does not mean they are
equally bad.  Statistically speaking, 10 forges having the same
"suckiness" score has an infinitesimal chance.

A more meaningful argument would be that the alternatives have different
goals, but even that's shaky, since most of their goals are shared.
If it takes me 30 minutes to find a commit in a repo on one forge and 5
minutes on another, then one forge is *objectively* worse in *that
aspect*.

I don't think repeating that no forge sucks less advances the
conversation towards any solution other than keeping the status quo,
which can't really be called a solution.

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

[Simon Tournier]

Hi Liliana,

On Mon, 11 Sep 2023 at 19:53, Liliana Marie Prikler  
wrote:

> For "patch does not apply", the forge solution is typically to send a
> notification to the issuer.

No, that does not match my small experience.  Because often the issuer
is gone or not responding.  As a reviewer using the forge solution, I am
still able to pull the issuer branch and then resolve the conflicts if
any.

Using “our” workflow, I fail earlier in the process.  I am not able to
apply the patches against any branches (pull the PR somehow).  An
example:

[bug#62202] [PATCH 0/21] Juliahub import script.
https://issues.guix.gnu.org/msgid/871qlq89kz@ngraves.fr

Even before looking at it, I have to spend some time to find a way to
manually apply the patches.  Then, rebasing on the top of master could
lead to conflict but that another story and the same appears whatever
the workflow.

Nicolas did a cool job with this Julia importer, and because of this
first boring task, I am procrastinating and delaying to the eternal
tomorrow the review of the work.

Whatever the complexity of this task, there is no value for the project.

I read Ricardo’s message [1] as: our workflow is far to help us for
having smooth reviews so it’s hard to convince folks already familiar
with other workflows to adopt our.  Not saying that these other
workflows are better either.

Cheers,
simon


1: Re: How can we decrease the cognitive overhead for contributors?
Ricardo Wurmus 
Fri, 08 Sep 2023 22:24:06 +0200
id:87tts44d2y@elephly.net
https://yhetil.org/guix/87tts44d2y@elephly.net
https://lists.gnu.org/archive/html/guix-devel/2023-09

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

[Liliana Marie Prikler]

Hi Simon,

Am Montag, dem 11.09.2023 um 12:36 +0200 schrieb Simon Tournier:
> Today, the review and commit process have many steps, more or less
> simple, not all sure!, well at the end, we have something complex.
> 
> One trivial step is to apply the patch (or series) to your local
> checkout and so many things can lead to some useless frictions.  For
> example, the patch does not apply because the base commit is not
> provided, or because it is badly formatted, or because….  And one
> ends to fix themself, e.g., probably using some manual trick just for
> applying the patch.  No value for the project.
> 
> Yes, QA is currently helping for that specific example about applying
> patches but the solution depends on why the patch does not apply.
As a committer, I've already shared my tool for applying patches from
mumi.  It is currently broken due to yet another bug in mumi that I
can't figure out the cause of, but assuming that gets fixed, it is
indeed a trivial step with the added value that I can sign off the
commit as I do (and signed commits gives the benefit of a trusted
upgrade chain, as detailed in the introductory blog).

Now granted, there is no benefit if you do this "checking out for
review work" as a non-committer, because your signature, whether you
apply it or not, holds no value for the project.  However, there are
issues one can spot simply "by looking" as well as others that do
require actual research beyond building the package (such as "is this
software actually GPL'd" for example).  As for actually checking
whether the package builds, we could move more of that to QA, but I'm
not sure whether that'd be a benefit.

For "patch does not apply", the forge solution is typically to send a
notification to the issuer.  Sure, we could do that, we could even do
so automatically, but fixing one's own patch over and over against a
running target when there's no hope it'll get merged (for other issues
that are never pointed out, because you're coding for a bot) induces
even more cognitive overhead.

> Well, I am not saying that we should switch to PR model using
> GitHub. :-) Let just recognize that our current workflow has many
> drawbacks that make some frictions (steps with no value) for
> reviewing.  And PR model à la GitHub has many other drawbacks but at
> least it reduces some frictions (technical steps with no value);
> mainly because some people are paid for removing (or hide) these
> useless friction.
> 
> Don’t you agree that the review process implies many manual steps
> that have no value for the project?
I might actually disagree on the "many", but let's agree on "some" and
move on from there.

> Last, I agree that the main issue when speaking about the reviewing
> process is not about tooling.  The lack of a smooth technical
> solution is just acting as a chemical developing solution in
> photography, it increases the contrast and makes the poor image
> apparent.
Yeah, I don't get that metaphor.

Cheers

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

[Giovanni Biscuolo]

Hi Liliana,

Liliana Marie Prikler  writes:

[...]

> For example, whenever people say that "forges would improve stuff", my
> reply is (modulo phrasing) "yes, for the people who are already used to
> forges".

I just want to point out that actually Guix _do_have_ a forge. the
software is Savane and it's hosted on savannah.gnu.org:
https://savannah.gnu.org/projects/guix

This is just to remind everyone that there are very different forges out
there, and:

  All forges suck, _no one_ sucks less

> Now, forges might indeed be familiar to many,

What kind of forge?  Savannah, GitHub, GitLab, SourceHut, Codeberg (you
name it)

Just to bring a simple, when talking about the "Pull Request" workflow
to manage merges, they are not even interoperable (while git
request-pull /is/)

...not to talk about issue management features, when present.

[...]

> Bear in mind, that contributing already has at least one degree of
> complexity baked right into itself on the basis of being a feedback
> loop.

Wow. food for thought!

Thanks! Gio'

-- 
Giovanni Biscuolo

Xelera IT Infrastructures


signature.asc
Description: PGP signature

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

[Giovanni Biscuolo]

Hello,

(I find it difficult to efficiently follow this thread and to keep up to
date with reading it, so please forgive me if someone else already
addressed my considerations)

Simon Tournier  writes:

[...]

> « For which contributors do we want to/can we decrease the cognitive
> overhead? », so I read it as: do we discuss about someone who is already
> playing guitar or someone who is knowing nothing about music.
>
> We already have the answer: we are speaking about someone who already
> plays guitar (a skilled programmer).

There are many ways to contribute to Guix:

--8<---cut here---start->8---

- Project Management
- Art
- Documentation
- Packages
- Programming
- System Administration
- Test and Bug Reports
- Translation

--8<---cut here---end--->8---
(https://guix.gnu.org/en/contribute/)

and just a few of them requires to be a skilled programmer :-)

But you are absolutely right, we are talking about someone who already
have:

--8<---cut here---start->8---

(skill
 (or project-management
 user-interface-design
 graphical-design
 multimedia-design
 technical-documentation-writing
 guix-programming
 guile-programming
 program-debugging
 system-administration
 translation-of-tachnical-documents))
 
--8<---cut here---end--->8---

I'd also say that other "low level" skills are dependencies for some or
all of the above mentioned skills, like: git-dvcs-usage, text-mua-usage

As already mentioned, a conditio sine qua non (hard dependency) to
contribute to Guix (as to as many many other international distributed
projects) is to have "high level" skill named
manage-communications-in-EN.

Last but not least, a "meta skill" is that you accept to do all of this
as a volunteer in a large group of volunteers, with very few /direct/
rewards - the most important one being to improve the best ever free
software distro [1] - and many many issues to address...

Quite a lot of skills to be able to contribute, I'd say.

Furthermore, not a skill but another requirement not to be
underestimated is you need a certain amount of time and unfortunately
many people can only subtract that from their (often already scarce)
free time.

Probably we should find a way to /introduce/ old and new contributors to
this concepts since I feel someway sometimes they are forgotten or
underestimated.

[...]

> Somehow, now we have to discuss about specific task, task by task, and
> propose how to improve.  Survey is one next action for collecting
> data.

My 2 cents: surveys should be _carefully_ designed or the resulting data
would be useless at best, misleading at worst

[...]

> The improvement had been the removal of the friction by switching to
> some web interface.  Now, the process is probably not easy for people
> like me that are not used to web interface, although interacting with
> web interface is a simpler task than configuring some tools for
> editing translation files.

There is a weblate CLI we should probably package in Guix:
https://docs.weblate.org/en/latest/wlc.html

I just hope that changing from a git-commit-based approach to a
weblate-tool approach have helped find many more active translators:
https://translate.fedoraproject.org/projects/guix/#information

> we are far from the initial discussion. ;-)

Sorry: OT... OT?!? :-O

> I do not see “the practice of controlling access to information,
> advanced levels of study, elite sections of society, etc“.  Well, are
> you French? ;-) Because I feel we are discussing unrelated points
> emerging although we are agree on the core and we just detail tiny
> variations of the same thing. :-)

If you want I can add a little bit of Italian attitide at discussing in
detail tiny variations of the same thing :-O... just joking, eh! ;-)

[...]

Ciao! Gio'


[1] well, I'm biased :-D

-- 
Giovanni Biscuolo

Xelera IT Infrastructures


signature.asc
Description: PGP signature

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

[Simon Tournier]

Hi Liliana,

On Sun, 10 Sep 2023 at 00:20, Liliana Marie Prikler  
wrote:

>> > > Must we force a single workflow on everyone, even if our track
>> > > record in reviewing and merging doesn’t clearly show that our way
>> > > is superior
>> >
>> > Again, define superior.
>> 
>> No, I won’t.  I think it’s obvious that our review process isn’t
>> working *well*.  So the argument that our current workflow allows for
>> effective review is dubious.  Not saying that you made that claim,
>> just that it’s hard to convince others of adopting our ways when the
>> results just aren’t great.
>
> What do you consider "the results" here?  The rate at which patches are
> merged?  This is hardly an issue our project alone is fighting and I'm
> not convinced that technology, more or less, will shift it in either
> direction.  

That’s not about “result” here.  That’s about “simple vs easy” or
“complex can be easy” or etc.

Similarly as submitting patches means that many steps are more or less
simple, then the complete process can be considered as relatively
complex.  To be explicit, I do not speak about being “easy” which is
subjective and instead I am speaking about some objective criteria
(e.g., the number of steps even if they are trivial).

Some part of that complexity has some value for the project and some
other part has no value.  The question is thus to identify and then
remove (or hide) the complexity that has no value for the project.

Today, the review and commit process have many steps, more or less
simple, not all sure!, well at the end, we have something complex.

One trivial step is to apply the patch (or series) to your local
checkout and so many things can lead to some useless frictions.  For
example, the patch does not apply because the base commit is not
provided, or because it is badly formatted, or because….  And one ends
to fix themself, e.g., probably using some manual trick just for
applying the patch.  No value for the project.

Yes, QA is currently helping for that specific example about applying
patches but the solution depends on why the patch does not apply.

Well, I am not saying that we should switch to PR model using
GitHub. :-) Let just recognize that our current workflow has many
drawbacks that make some frictions (steps with no value) for reviewing.
And PR model à la GitHub has many other drawbacks but at least it
reduces some frictions (technical steps with no value); mainly because
some people are paid for removing (or hide) these useless friction.

Don’t you agree that the review process implies many manual steps that
have no value for the project?

Last, I agree that the main issue when speaking about the reviewing
process is not about tooling.  The lack of a smooth technical solution
is just acting as a chemical developing solution in photography, it
increases the contrast and makes the poor image apparent.

Cheers,
simon

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

[Giovanni Biscuolo]

Hi Efraim,

Efraim Flashner  writes:

[...]

> On the other hand, if we do manage to automate writing of commit
> messages, it makes one less thing for committers to manually fix before
> pushing the commit.

It would be lovely!  It could also be done by a client-side git hook,
provided in the Guix repo and automatically installed when following the
instructions on the Guix manual (sorry I miss the pointer now) so that
not only committers can benefit using that script but also contributors.

As usual: patches wellcome! :-)

Sorry I can't contribute with this task, I really don't know ho to
program such a script.

All I can do is suggesting to add a git commit message template (see
message id:87y1hhdnzj@xelera.eu point 4. for details)

Anyway, automation does't mean that the contributor/committer can ignore
the commit message content conforms to the Guix guidelines: IMO a human
supervising activity is always needed, be it done by contributors before
submiting a patch or by a reviewer before committing.

> The last couple of contributions I pushed had green checks on
> qa.guix.gnu.org and I felt at a bit of a loss what to do while
> checking it over.

Sorry feel I don't fully understand what do you mean.

I'm guessing here...

AFAIU having a green light on QA means one of the build farms
succesfully built the package, I guess this is a "gree check" on a
"Committer check list" before committing: actually I can't find such
check list but probably it can be "extrapolated" from the checklist
documented for patch submissions:
https://guix.gnu.org/en/manual/devel/en/html_node/Submitting-Patches.html

So, if all the items in the check list are OK, the package sould be
committed to the appropriate branch.

Lastly, IMO if you are committer you can go on, if you are not committer
you should notify a suitable committer that all is ready for commitment.

Maybe if QA would send an email notification to the bug owner (every bug
related to a patch set should have an owner) about thay "green light" it
could be of some help with keeping track of what can be actually merged.

> After checking that it was in fact green I double-checked the
> commit message and then also some of the layout of the commit and the
> package itself, and made sure it passed `guix lint`. More resources for
> qa.guix.gnu.org would let us build more patches more quickly.

I agree, QA is a critical resource in this phase of Guix evolution.

More resources IMO also means documentation... and maybe more features?

I feel like we should find a way to sponsor the work on QA.

Happy hacking! Gio'

-- 
Giovanni Biscuolo

Xelera IT Infrastructures


signature.asc
Description: PGP signature

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

[Efraim Flashner]

On Fri, Sep 08, 2023 at 04:20:30PM +0200, Ricardo Wurmus wrote:
> 
> Josselin Poiret  writes:
> 
> > Regarding the “mom argument”, I would disagree and say that this is
> > completely related: interruptions are more costly, you're more likely to
> > have less attention span, and overall you probably don't want to commit
> > to 20 steps just to send a contribution.
> 
> That’s exactly it.
> 
> I’m a parent working a full-time job and I’m easily overwhelmed by what
> I would have considered to be simple processes 20 years ago.  All these
> simple and totally “easy” processes add up and – oops it’s 11:30pm
> already and I had been feeling exhausted since 10am…
> 
> There’s an hour before I pass out — what will I do with it?  This thread
> is about how we can reduce overhead; for me that would mean to have
> certain checks automated, or to have commit messages be generated so I
> only need to read them to sign off on them, etc.
> 
> We all may gain from streamlining our processes.  Personally, I see the
> biggest problem in a lack of effective tools for reviewers, which
> results in stretching out contribution interactions over weeks, months,
> or years.  This, to me, would be a way to increase the weight of the
> rewards on the unbalanced scales that are overwhelmed by chores on the
> other side.

On the other hand, if we do manage to automate writing of commit
messages, it makes one less thing for committers to manually fix before
pushing the commit.

The last couple of contributions I pushed had green checks on
qa.guix.gnu.org and I felt at a bit of a loss what to do while checking
it over. After checking that it was in fact green I double-checked the
commit message and then also some of the layout of the commit and the
package itself, and made sure it passed `guix lint`. More resources for
qa.guix.gnu.org would let us build more patches more quickly.

-- 
Efraim Flashner  רנשלפ םירפא
GPG key = A28B F40C 3E55 1372 662D  14F7 41AA E7DC CA3D 8351
Confidentiality cannot be guaranteed on emails sent or received unencrypted


signature.asc
Description: PGP signature

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

[Liliana Marie Prikler]

Am Samstag, dem 09.09.2023 um 21:40 +0200 schrieb Ricardo Wurmus:
> 
> Liliana Marie Prikler  writes:
> 
> > > Must we force a single workflow on everyone, even if our track
> > > record in reviewing and merging doesn’t clearly show that our way
> > > is superior?
> > Again, define superior.
> 
> No, I won’t.  I think it’s obvious that our review process isn’t
> working *well*.  So the argument that our current workflow allows for
> effective review is dubious.  Not saying that you made that claim,
> just that it’s hard to convince others of adopting our ways when the
> results just aren’t great.
What do you consider "the results" here?  The rate at which patches are
merged?  This is hardly an issue our project alone is fighting and I'm
not convinced that technology, more or less, will shift it in either
direction.  

Let's take our importers as an example.  Bugs aside, they allow us to
bump any package to the newest released version.  Naturally, similar
tools have evolved over in the forge world as well.  The end result? 
Bots are now writing merge request that end up ignored much like there
are bugs in Guix that receive little attention due to what might as
well be unfortunate timing.

I'm also not sure how we can tie back contribution throughput to
cognitive overhead.  In fact, there might well be a Jevons paradox
hiding somewhere in that less overhead per patch means that more
patches can be written, which results in the same overall cognitive
overhead in the long run.  

Now, you are probably right in that our review process probably isn't
working well for some value of well that yet needs to be defined. 
However, without any frame of reference it is also a statement that can
neither be verified nor falsified.  I could be sitting in a burning
house claiming "this is fine" or sitting in the finest restaurant
claiming "this place sucks" and since you can't see me, there's no way
for you to infer that I'm a cat.

Cheers

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

[Ricardo Wurmus]

Simon Tournier  writes:

> On Fri, 08 Sep 2023 at 17:27, Ricardo Wurmus  wrote:
>
>> Now, this is no longer a problem for me because I’ve been writing so
>> many commit messages over the years (and because I no longer try to
>> adhere to some poorly specified format), but it *is* a problem for
>> people that I’ve mentored.
>
> Well, from my point of view, you cannot know if another way to write
> commit message format would not be a problem either. :-)

Let’s not write them at all and have them generated.  People are still
expected to read them before sending them off, to be sure that they say
what was intended.

> I think we have a consensus about the complexity for contributing.  From
> my point of view, all the “cognitive complexity” are not equal.  Some
> cognitive loads are totally useless and just pure friction – the number
> of steps for checking and submitting for example – and it brings no
> value at all for the project.  Other, as commit message format, also
> leads to some friction but it also brings value for the project.

Agreed.

-- 
Ricardo

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

[Ricardo Wurmus]

Liliana Marie Prikler  writes:

>> Must we force a single workflow on everyone, even if our track record
>> in reviewing and merging doesn’t clearly show that our way is
>> superior?
> Again, define superior.

No, I won’t.  I think it’s obvious that our review process isn’t working
*well*.  So the argument that our current workflow allows for effective
review is dubious.  Not saying that you made that claim, just that it’s
hard to convince others of adopting our ways when the results just
aren’t great.

>> Recall that the reason for my response at this point in the thread is
>> your statement:
>> 
>> > Hiding obsolete versions of a pull request is in practice
>> > implemented either by pushing more commits on top of the existing
>> > one, often with dubious commit messages or by force-pushing a
>> > branch, neither of which is an acceptable solution for Guix.
>> 
>> I’m trying to convey that this workflow is similar to how we would
>> push to wip-* branches and informally discuss open issues out of
>> band.  (And even in that scenario, we are rather limited by the way
>> our shared repository with all-or-nothing permission management
>> works.)
> I think this is a bit of an apples to oranges comparison.

Exactly.  Apples and oranges are both fruit, full of sugar and fiber,
and some people prefer one over the other.

> Even for our
> wip branches, we mostly adhere to the guidelines that govern master,
> it's mostly the rule regarding breaking changes that is relaxed.  We
> wouldn't have well-functioning wip branches if those forewent *all*
> communication efforts.  The only common ground I can see is that all
> feature branches – or at least those that don't die – get merged to the
> main branch in either workflow.

Yes, that’s my point.

-- 
Ricardo

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

[Liliana Marie Prikler]

Am Donnerstag, dem 07.09.2023 um 14:39 -0600 schrieb Katherine Cox-
Buday:
> > Somehow, that’s the remark by Liliana [1],
> > 
> >  Maybe it's time to take a step back and instead of asking 
> >  “How can we decrease the cognitive overhead for
> >  contributors?”, we should perhaps ask “For which 
> >  contributors do we want to/can we decrease the cognitive
> >  overhead?”
> 
> That quote is at the end of a dismissive ad hominem response which
> has grossly misinterpreted this discussion, even attributes it to
> malice [...]
Hi, pot, kettle speaking.  Now, I appreciate the ways in which you
think I might be misrepresenting your points even as I talk about the
points other people are making, but I'd appreciate even more if you
considered that you might also be (intentionally or otherwise)
misrepresenting the points others make.  You did so when Simon used an
idiomatic phrase for voicing disbelief, and you did it again here.

> seems to draw the conclusion that contributing to Guix should be left
> to those for whom the current situation is fine
This is the antithesis of what I am aiming for.  To quote my reply to
your initial message.

> Contributions are open to everybody (as long as they pass the first
> hurdle which is a very manual check to see if they spam our mailing
> lists or not), but the review process ensures that the outcome
> remains high quality.  This is desirable.
> 
> Now you might say that this leads to less diversity in the team of
> committers and maintainers as you need a certain level of privilege
> to seriously entertain the idea of dedicating that much time and
> effort to a project and I agree, but I also think this is a bigger
> reality of volunteer work in general.
TL;DR: Guix follows a model where contribution is open to everyone but
a select few decide which contributions make it upstream.  This is the
best we can get for the sole reason that we need quality control.  If
we didn't have the select few or the select few didn't do their job of
only accepting changes that don't "break the world" for all Guixers out
there properly, things would be very bad.

Now, Guix also has channels, which are fully free to all in that
everyone can run their own channel, but coming back to cognitive
overhead, maintaining your own channels *and* contributing to Guix
proper would at least in some instances be double work. 

> , and even intimates that those who would like to improve the
> situation are incompetent.
I assume you meant insinuates – maybe I don't do English like a native
speaker after all and intimates means the same – but again, I don't
think you're incompetent because you, say, fail to type a perfect
ChangeLog.  I would think it to be a little selfish if you submitted a
series of 100 patches and none of them had an even slightly useful
commit message, but that's only tangentially related to the point in
that I am so vocal about the ChangeLog thing because I already see
people not adhering to the convention and I'd really hate to encourage
the sending of such series.

Now, you say that you would "like to improve the situation", but I'd
like you to take a step back and first consider whether a given change
would actually end up "improving the situation" before committing to
it.  In the ChangeLog case, there is a lot to be gained from
automation, assuming the automation produces correct results and
doesn't hallucinate ChangeLogs à la ChatGPT.  On the other hand, there
is also much information to be lost if we were to switch formats to
something else, even if that something else is preferred by a group of
people that dislikes ChangeLogs.

> Contextualized, this quote is insinuating that I'm trying many
> different arguments in an attempt to push an agenda, and that because
> of this, any of the points I've made are suspect and should be
> dismissed.
If you're talking about the many different arguments thrown
specifically against ChangeLogs that I mentioned in the same message,
these actually came from different folks and I attributed them to no
one.  

> Read charitably, this quote suggests that there is a singular, best,
> way to do things, and that if it doesn't work for some, the problem
> is not the process, but that "those people" are incompetent.
> 
> This is classic gatekeeping.
Uhm, no it doesn't?  What I actually mean when I wrote these lines, is
that we all have (whether we are aware of it or not) a group of people
in mind that we care about when we say that we would like to improve
things.  Picturing this group clearly helps you when deciding your
priorities – which just like adjacency, is indeed subjective, and most
of the time we are thinking about an adjacent group.

For example, whenever people say that "forges would improve stuff", my
reply is (modulo phrasing) "yes, for the people who are already used to
forges".  Now, forges might indeed be familiar to many, but they would
also braid more things together.  You have to consider 

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

[Simon Tournier]

Hi Ricardo, all,

On Fri, 08 Sep 2023 at 17:27, Ricardo Wurmus  wrote:

> Now, this is no longer a problem for me because I’ve been writing so
> many commit messages over the years (and because I no longer try to
> adhere to some poorly specified format), but it *is* a problem for
> people that I’ve mentored.

Well, from my point of view, you cannot know if another way to write
commit message format would not be a problem either. :-)

I think commit message are for communicating and communication implies
norms and norms are by definition excluding.

Once we have said that, we are locked. :-)

Well, somehow, I think Vagrant’s words [1] captures the situation.
Somehow, I am paraphrasing using my own words. ;-)

IMHO, the questions is not about pros and cons for some non well-defined
ChangeLog-like commit format message, but what are the values of the
commit messages for the project?

If we answer there is no value, then yeah we could use full-free form
commit message.  Somehow, that’s what the Julia language is doing [2].

If we answer there is a value, can we say explicitly which one?  Or
which ones?  And what could be the format that captures these values.

For me, the value is first to have a common structure (uniformity
similar as coding style), and this common structure then 1. allows to
easily navigate through the history and 2. eases the reading for the
people who knows the structure.

And second the value is something like « it forces some discipline on me
by having me review my changes in details and write out what I did » as
Maxim is describing in [3].

However, this structure comes with friction. It is not possible to have
a structure (norm) which is fully without friction.

The question is thus: what is the structure that maximize the value and
minimize the friction?  And the optimum is person-dependant.

I think we have a consensus about the complexity for contributing.  From
my point of view, all the “cognitive complexity” are not equal.  Some
cognitive loads are totally useless and just pure friction – the number
of steps for checking and submitting for example – and it brings no
value at all for the project.  Other, as commit message format, also
leads to some friction but it also brings value for the project.

For these latter case, the improvement is not clear for me.


Cheers,
simon


1: Re: How can we decrease the cognitive overhead for contributors?
Vagrant Cascadian 
Wed, 06 Sep 2023 10:52:45 -0700
id:87h6o7mbo2.fsf@wireframe
https://lists.gnu.org/archive/html/guix-devel/2023-09
https://yhetil.org/guix/87h6o7mbo2.fsf@wireframe

2:
https://github.com/JuliaLang/julia/commit/7ac7c3d5d5f21e42555cdf99e699a246f8ec

3: Re: How can we decrease the cognitive overhead for contributors?
Maxim Cournoyer 
Mon, 28 Aug 2023 23:00:00 -0400
id:874jkift8v@gmail.com
https://lists.gnu.org/archive/html/guix-devel/2023-08
https://yhetil.org/guix/874jkift8v@gmail.com

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

[Simon Tournier]

Hi Katherine,

On Thu, 07 Sep 2023 at 14:39, Katherine Cox-Buday  
wrote:

 
>>  Maybe it's time to take a step back and instead of asking “How can 
>> we
>>  decrease the cognitive overhead for contributors?”, we should 
>> perhaps
>>  ask “For which contributors do we want to/can we decrease the 
>> cognitive
>>  overhead?”
>
> That's interesting, because I view this as the antithesis of what Rich 
> was trying to convey.
>
> That quote is at the end of a dismissive ad hominem response which has 
> grossly misinterpreted this discussion, even attributes it to malice, 
> seems to draw the conclusion that contributing to Guix should be left to 
> those for whom the current situation is fine, and even intimates that 
> those who would like to improve the situation are incompetent.

About the dismissive ad hominem response, sorry.  I should have clearly
mentioned that I was fully rejecting the rest but only keeping the
argument I was quoting.

> Here's the quote from Rich's talk:
>
> The fact that we throw these things around sort of casually 
> saying, "Oh I
> like to use that technology because it's simple. And when I say 
> simple I
> mean easy. *And when I'm saying easy, I mean, because I already know
> something that looks very much like that*" is how this whole thing
> degrades, and we can never have objective discussion about the 
> qualities
> that matter to us in our software.
>
> Rich is saying that there are intrinsic properties to approaches that 
> make them simple, but possibly not easy, and that we shouldn't rest our 
> arguments on claiming something is "easy", because that term is 
> relative, and often related to familiarity. Familiarity is a hard bias 
> to overcome.

Yeah.  I think I had already gotten it. ;-)

For someone who already plays guitar, then ukulele is “easy”.  For
someone who does not know any instrument or nothing about music, ukulele
is “hard”.  Although, the complexity of the ukulele is the same in both
cases.

« For which contributors do we want to/can we decrease the cognitive
overhead? », so I read it as: do we discuss about someone who is already
playing guitar or someone who is knowing nothing about music.

We already have the answer: we are speaking about someone who already
plays guitar (a skilled programmer).  As you said elsewhere in the
thread, we are all different, we all have different backgrounds,
etc. and the idea behind “easy is relative” implies that we have to
bound for whom it needs to be easy.

“How can we decrease the cognitive overhead for contributors?”  Here,
contributor is not explicitly defined.  In all the thread, the term
’contributor’ is interpreted very differently.  Well, I repeat my very
first message:

Well, from my point of view, we are using here the term
“contribution” as it was one homogeneous thing.

[...]

For example, a two-line patch trivially updating one package is
not the same contribution as several-to-many two-line patches
more some package additions for updating all the R ecosystem.
And that’s not the same as rewriting the Python build system or
as packaging the last version TensorFlow.

The cognitive overhead for these 3 contributions is not the
same.  Therefore, the way to reduce the friction will not be the
same, IMHO.

A task is not “easy“ by itself.  It depends on 1. the complexity of the
task and 2. on the person who does it.

We are saying the same thing, no?

Now, this discussion has identified various frictions that are useless
and bring no value for the project.  It is clear that we need to improve
by smoothing or even maybe removing some of them.

Somehow, now we have to discuss about specific task, task by task, and
propose how to improve.  Survey is one next action for collecting data.

The other action for more automation is not clear yet.  We need to open
discussions about QA, scripts, etc.  For what my opinion is worth.


> Read charitably, this quote suggests that there is a singular, best, way 
> to do things, and that if it doesn't work for some, the problem is not 
> the process, but that "those people" are incompetent.

Saying it plainly and stretching a bit, yes “easy is relative” means
some people do not have the background to complete some process.

Reading the word “incompetent” as “not possessing the necessary ability,
skill, etc to do or carry out a task; incapable”

I am incompetent for playing guitar for example.  And playing music is
really not easy for me.  And so? :-)

It is related to the question: for whom it has to be easy.  A good
example is the switch to some web interface for the translation.  Some
translators does not have programming skills, so they are incompetent
for programming, and it was not easy for them to configure the tools for
contributing to translation.  The improvement had been the removal of

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

[Liliana Marie Prikler]

Am Freitag, dem 08.09.2023 um 22:24 +0200 schrieb Ricardo Wurmus:
> 
> Liliana Marie Prikler  writes:
> 
> > > On Github, Pull Request branches are like our WIP branches.  They
> > > are how we arrive at acceptable changes.  Picky people like me
> > > would then go back and write new atomic commits for the effective
> > > diff, but in my role as a reviewer I usually rebase, squash, and
> > > merge.
> > > 
> > > This workflow is more familiar to some and alienating to others,
> > > but both of these workflows would work fine for Guix.  But today
> > > our tools can only accommodate *one* workflow.  
> > I'd imagine that rebase, squash and merge would exacerbate the
> > workload on the committer side and I think that most popular
> > projects on those forges already experience similar effects to us
> > despite folks just merging the requests as-is and in part even
> > getting paid by big tech for doing so.
> 
> Look, I’m relating merely my work experience here as someone who
> regularly reviews pull requests on Github.  Github has buttons for
> “Rebase and merge”, “Squash and merge”, and “Create a merge commit”,
> so that part is automated.
> 
> I’m not saying that this is the workflow we should adopt.  I’m saying
> that these platforms — for better or worse — encourage *different*
> workflows, and for some this is what they are most comfortable with.
How many different workflows are those?  In my opinion, the one that
folks typically refer to when mentioning comfort is
1. git branch
2. git push elsewhere
[ long conversation using the forge's blessed UI ]
?. git merge
Fair enough, as a committer you get the option of cherry-picking,
rebasing, or whatever else instead of a merge, but the UI support for
those alternatives ranges from "okay, I guess" to "you know how to do
this by command line, don't you?" and "this change will be marked as
rejected even though you actually merged it".  Whenever you're using
these platforms, you are being nudged into its happy path, just as the
contribution via email model really makes it hard to just type "git
merge" and expect success – you do need git am at some point.

> Must we force a single workflow on everyone, even if our track record
> in reviewing and merging doesn’t clearly show that our way is
> superior?
Again, define superior.

> Recall that the reason for my response at this point in the thread is
> your statement:
> 
> > Hiding obsolete versions of a pull request is in practice
> > implemented either by pushing more commits on top of the existing
> > one, often with dubious commit messages or by force-pushing a
> > branch, neither of which is an acceptable solution for Guix.
> 
> I’m trying to convey that this workflow is similar to how we would
> push to wip-* branches and informally discuss open issues out of
> band.  (And even in that scenario, we are rather limited by the way
> our shared repository with all-or-nothing permission management
> works.)
I think this is a bit of an apples to oranges comparison.  Even for our
wip branches, we mostly adhere to the guidelines that govern master,
it's mostly the rule regarding breaking changes that is relaxed.  We
wouldn't have well-functioning wip branches if those forewent *all*
communication efforts.  The only common ground I can see is that all
feature branches – or at least those that don't die – get merged to the
main branch in either workflow.

Cheers

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

[Liliana Marie Prikler]

Am Freitag, dem 08.09.2023 um 17:39 +0200 schrieb Ricardo Wurmus:
> 
> Liliana Marie Prikler  writes:
> 
> > To be completely honest, mumi recalling everything at 0 precision
> > is my biggest pet peeve at the moment
> 
> Can you please make a test case for this and add it to the mumi
> tests?  We have tests for the search feature there.
I would like to, but I'm experiencing some trouble getting the data. 
How do you populate the mocked spool?

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

[Ricardo Wurmus]

Liliana Marie Prikler  writes:

> Am Freitag, dem 08.09.2023 um 17:27 +0200 schrieb Ricardo Wurmus:
>> I have the same positive view on our faux ChangeLogs commit messages,
>> though I also would like to have them generated.  The benefit is
>> still there: I still get to *review* an effective summary of the
>> changes before pushing or sending them off for review.  But at least
>> I don’t have to write them myself.
>> 
>> Now, this is no longer a problem for me because I’ve been writing so
>> many commit messages over the years (and because I no longer try to
>> adhere to some poorly specified format), but it *is* a problem for
>> people that I’ve mentored.
>> 
>> etc/committer.scm and the yasnippets are supposed to alleviate some
>> of the pain, but I don’t need to think for a long time to come up
>> with a number of improvements in this area.
> Can I assume this to mean it'd take you some short time to think of
> snippets that we're currently lacking?  If so, please do contribute
> them.  If not, what do you mean then?

I mean that they have plenty of defects.

When I wrote the first few iterations of etc/committer.scm it was only
really meant and good for bulk package updates (= lots of changes across
files, all upgrades).  It couldn’t (and maybe still can’t) reliably
detect added or removed package definitions.  It doesn’t handle changes
to the arguments field.  It’s also terribly slow because it naively
recomputes information for every hunk in the diff, reading package
definitions from the old vs the changed file after every commit.

The update yasnippet repeatedly gets the order of lines wrong when
adding a patch to dist_patch_DATA in gnu/local.mk; it also doesn’t do
what etc/committer.scm is already able to do: detecting changes to
inputs.  Configuring yasnippet is also not trivial for people who don’t
regularly use Emacs (the snippets are tied to modes set by magit).

I think in light of these defects “Uhm, we have snippets?” isn’t a
satisfying response.

-- 
Ricardo

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

[Ricardo Wurmus]

Liliana Marie Prikler  writes:

>> On Github, Pull Request branches are like our WIP branches.  They are
>> how we arrive at acceptable changes.  Picky people like me would then
>> go back and write new atomic commits for the effective diff, but in
>> my role as a reviewer I usually rebase, squash, and merge.
>> 
>> This workflow is more familiar to some and alienating to others, but
>> both of these workflows would work fine for Guix.  But today our
>> tools can only accommodate *one* workflow.  
> I'd imagine that rebase, squash and merge would exacerbate the workload
> on the committer side and I think that most popular projects on those
> forges already experience similar effects to us despite folks just
> merging the requests as-is and in part even getting paid by big tech
> for doing so.

Look, I’m relating merely my work experience here as someone who
regularly reviews pull requests on Github.  Github has buttons for
“Rebase and merge”, “Squash and merge”, and “Create a merge commit”, so
that part is automated.

I’m not saying that this is the workflow we should adopt.  I’m saying
that these platforms — for better or worse — encourage *different*
workflows, and for some this is what they are most comfortable with.

Must we force a single workflow on everyone, even if our track record in
reviewing and merging doesn’t clearly show that our way is superior?

Recall that the reason for my response at this point in the thread is
your statement:

> Hiding obsolete versions of a
> pull request is in practice implemented either by pushing more commits
> on top of the existing one, often with dubious commit messages or by
> force-pushing a branch, neither of which is an acceptable solution for
> Guix.

I’m trying to convey that this workflow is similar to how we would push
to wip-* branches and informally discuss open issues out of band.  (And
even in that scenario, we are rather limited by the way our shared
repository with all-or-nothing permission management works.)

-- 
Ricardo

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

[Liliana Marie Prikler]

Am Freitag, dem 08.09.2023 um 17:27 +0200 schrieb Ricardo Wurmus:
> I have the same positive view on our faux ChangeLogs commit messages,
> though I also would like to have them generated.  The benefit is
> still there: I still get to *review* an effective summary of the
> changes before pushing or sending them off for review.  But at least
> I don’t have to write them myself.
> 
> Now, this is no longer a problem for me because I’ve been writing so
> many commit messages over the years (and because I no longer try to
> adhere to some poorly specified format), but it *is* a problem for
> people that I’ve mentored.
> 
> etc/committer.scm and the yasnippets are supposed to alleviate some
> of the pain, but I don’t need to think for a long time to come up
> with a number of improvements in this area.
Can I assume this to mean it'd take you some short time to think of
snippets that we're currently lacking?  If so, please do contribute
them.  If not, what do you mean then?

Cheers

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

[Liliana Marie Prikler]

Hi,

Am Freitag, dem 08.09.2023 um 16:44 +0200 schrieb Ricardo Wurmus:
> I often have to review Github Pull Requests, and I don’t go commit by
> commit by go through the diff and annotate the changes.  I *read* the
> commits to get a sense for how the feature evolved and why changes
> were made, but the fact that new commits are pushed on top of the
> branch is not an obstacle in practice, because the commits don’t
> matter.
> 
> (I know, it hurts me too, but I don’t make the rules, okay?)
Well, thanks to Guix inventing the time machine, individual commits do
matter to us.

> And in these review interfaces we can mark individual comments as
> resolved.  So the flat list of changes with annotations *does* in
> fact provide a clearer organization than a tree of emails.
> 
> Note also that we don’t usually review commits by starting one new
> thread for each issue we address, so we don’t benefit from automatic
> branching of sub-discussions.
To be fair, the summarizing of changes followed by comments to
individual bits are a point that the forges at least get right. 
However, unless you rework a single line multiple times – which
admittedly happens more often in the "push the change on top" model of
the forges than in the "condense your changes to logical units" model
we use – a branching discussion per commit still comes quite close in
practice.  Also, when there are multiple reviewers notice different
things, you also get the branching tree.

> On Github, Pull Request branches are like our WIP branches.  They are
> how we arrive at acceptable changes.  Picky people like me would then
> go back and write new atomic commits for the effective diff, but in
> my role as a reviewer I usually rebase, squash, and merge.
> 
> This workflow is more familiar to some and alienating to others, but
> both of these workflows would work fine for Guix.  But today our
> tools can only accommodate *one* workflow.  
I'd imagine that rebase, squash and merge would exacerbate the workload
on the committer side and I think that most popular projects on those
forges already experience similar effects to us despite folks just
merging the requests as-is and in part even getting paid by big tech
for doing so.  (Perhaps I exaggerate at getting paid for processing
merge requests, I haven't worked for any of these companies, but
especially at the ones more oriented towards doing business, I'd
imagine that you can at least buy yourself a sandwich from the work you
do from time to time.)

> It happens to be the one I’m used to, but let’s please not pretend
> that it’s inherently *better* than the other.
I mean, when we say better, we would have to refer to some metric of
goodness.  And the metric I personally choose is somewhere in the
intersection of accessibility and interoperability, because that is
what matters to me.  With Github, Gitlab and whatever other forges you
have, you are more or less bound to their web interface.  If that works
for you, it works.  If it doesn't, it doesn't.  With the email-based
workflow, I can use whichever tools I am comfortable with, as long as
they work for sending mail (as a contributor) or eventually invoke `git
push' on a bunch of signed-off commits (as a committer).  This both
increases the chances of things working and gives me the tools to build
things that work for myself (and potentially others as well).

Cheers

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

[Liliana Marie Prikler]

Am Freitag, dem 08.09.2023 um 11:16 +0200 schrieb Giovanni Biscuolo:
> [...]
> 
> > > On 2023-09-06, Liliana Marie Prikler wrote:
> 
> [...]
> 
> > > > It's 
> > > > 
> > > > * file (variable)[field]{do you need 4
> > > > levels?}
> 
> The general form of a ChangeLog Style format for Guix code (Guile
> with gexp) could be rewrote as:
> 
> * relative-path-of-changed-file (variable) [field] :
> Description of change.
> 
> I never saw a {4th level} so AFAIU is not needed, unless someone have
> a good example plz: in this case we could add a 4th level to the
> general description.
I have seen four levels in the wild.  They aren't particularly large in
population, but then again, the third level isn't needed in most cases
either.  I think we should start out with (variable)[field] as the one
that covers most changes.

Btw. on the extra spaces, is there any consensus on whether to put them
there or leave them out?  My personal style always leaves them out.


Anyway, looking forward to seeing your series.

Cheers

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

[Giovanni Biscuolo]

Hello Efraim,

Efraim Flashner  writes:

> On Fri, Sep 08, 2023 at 11:53:43AM +0200, Giovanni Biscuolo wrote:
> That wasn't my read of it at all.

I don't understand what part of my message is different from your read,
so I cannot comment

> I too have many packages which I haven't upstreamed.

[...]

> but the effort to go through and see which packages are ACTUALLY
> needed and to clean up everything, it's just too much for me.

Do you find that it's too much due to the Guix ChangeLog guidelines?

[...]

> As far as commit messages, I've found that the script in
> etc/committer.scm to be very nice, even if there are plenty of cases
> where it doesn't do the job. I do think there's room for improvement
> and that may be one of the things we can do to make contributing
> easier.

What do you propose should be changed in the commit messages guidelines
to make contributing easier?

In Messege-Id 87y1hhdnzj@xelera.eu today I tried to make some
actionable proposals considering the contant of this thread: WDYT?

Thanks, Gio'

[...]

-- 
Giovanni Biscuolo

Xelera IT Infrastructures


signature.asc
Description: PGP signature

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

[Ricardo Wurmus]

Liliana Marie Prikler  writes:

> To be completely honest, mumi recalling everything at 0 precision is my
> biggest pet peeve at the moment

Can you please make a test case for this and add it to the mumi tests?
We have tests for the search feature there.

-- 
Ricardo

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

[Ricardo Wurmus]

Maxim Cournoyer  writes:

> I used to think the same about ChangeLogs style commit messages, but I
> have to admit that it forces some discipline on me by having me review
> my changes in details and write out what I did.  It'll sometimes expose
> something that'd be better kept in a separate commit, or something I did
> and forgot about in the early development, that should be dropped.

I have the same positive view on our faux ChangeLogs commit messages,
though I also would like to have them generated.  The benefit is still
there: I still get to *review* an effective summary of the changes
before pushing or sending them off for review.  But at least I don’t
have to write them myself.

Now, this is no longer a problem for me because I’ve been writing so
many commit messages over the years (and because I no longer try to
adhere to some poorly specified format), but it *is* a problem for
people that I’ve mentored.

etc/committer.scm and the yasnippets are supposed to alleviate some of
the pain, but I don’t need to think for a long time to come up with a
number of improvements in this area.

> There's also no stopping you adding a more conventional rationale as a
> paragraph between the topic and the ChangeLog content (which should
> appear at the bottom of the commit message).

Yes, this is something that might not be clear to all.  Before the
somewhat mechanical summary you can write a paragraph or two to give
context.

-- 
Ricardo

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

[Ricardo Wurmus]

Liliana Marie Prikler  writes:

>> one fundamental issue with the email based workflow is that its
>> underlying data model simply does not formally encode enough
>> information to be able to implement a slick workflow and frontend.
>> e.g. with a PR based model the obsolete versions of a PR is hidden
>> until needed (rarely). the email based model is just a flat list of
>> messages that includes all the past mistakes, and the by now
>> irrelevant versions.
> What the?  If anything, emails are like a tree and discussions in most
> forges are a single long list that's rarely well organized.  Virtually
> every mail client supports threads, whereas a certain one of the more
> popular forges still refuses to do so.  Hiding obsolete versions of a
> pull request is in practice implemented either by pushing more commits
> on top of the existing one, often with dubious commit messages or by
> force-pushing a branch, neither of which is an acceptable solution for
> Guix.

I often have to review Github Pull Requests, and I don’t go commit by
commit by go through the diff and annotate the changes.  I *read* the
commits to get a sense for how the feature evolved and why changes were
made, but the fact that new commits are pushed on top of the branch is
not an obstacle in practice, because the commits don’t matter.

(I know, it hurts me too, but I don’t make the rules, okay?)

And in these review interfaces we can mark individual comments as
resolved.  So the flat list of changes with annotations *does* in fact
provide a clearer organization than a tree of emails.

Note also that we don’t usually review commits by starting one new
thread for each issue we address, so we don’t benefit from automatic
branching of sub-discussions.

On Github, Pull Request branches are like our WIP branches.  They are
how we arrive at acceptable changes.  Picky people like me would then go
back and write new atomic commits for the effective diff, but in my role
as a reviewer I usually rebase, squash, and merge.

This workflow is more familiar to some and alienating to others, but
both of these workflows would work fine for Guix.  But today our tools
can only accommodate *one* workflow.  It happens to be the one I’m used
to, but let’s please not pretend that it’s inherently *better* than the
other.

-- 
Ricardo


FWIW: Mumi is the worst of both worlds as it flattens the email tree
while not providing any of the review features that popular forges
have.  So the problem of outdated and repeated mistakes in a flat list
becomes more pronounced there.

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

[Ricardo Wurmus]

Josselin Poiret  writes:

> Regarding the “mom argument”, I would disagree and say that this is
> completely related: interruptions are more costly, you're more likely to
> have less attention span, and overall you probably don't want to commit
> to 20 steps just to send a contribution.

That’s exactly it.

I’m a parent working a full-time job and I’m easily overwhelmed by what
I would have considered to be simple processes 20 years ago.  All these
simple and totally “easy” processes add up and – oops it’s 11:30pm
already and I had been feeling exhausted since 10am…

There’s an hour before I pass out — what will I do with it?  This thread
is about how we can reduce overhead; for me that would mean to have
certain checks automated, or to have commit messages be generated so I
only need to read them to sign off on them, etc.

We all may gain from streamlining our processes.  Personally, I see the
biggest problem in a lack of effective tools for reviewers, which
results in stretching out contribution interactions over weeks, months,
or years.  This, to me, would be a way to increase the weight of the
rewards on the unbalanced scales that are overwhelmed by chores on the
other side.

-- 
Ricardo

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

[Giovanni Biscuolo]

Ricardo,

Ricardo Wurmus  writes:

> Giovanni,
>
>> You are obviously free not to contribute your patches upstream but the
>> fact that you decided not to because it's "too hard" (my executive
>> summary about your complaints about Change Log content rules) to write
>> commit messages suitable for contribution it _not_ a Guix maintainers
>> fault, not at all.
>
> As a former Guix co-maintainer I disagree with this take.  (Nobody even
> brought up the word “fault”, which is a particularly unhelpful lens for
> understanding social issues, in my opinion.)

sorry for using "fault", I can't find a better term

> “too hard” sounds (perhaps unintentionally) derisive.

the complete sentence is: «"too hard" (my executive summary about your
complaints about Change Log content rules)»

what can I add about my intentions?

[...]

> It’s not that writing commit messages is hard.  It’s one of many
> obstacles,

IMO one of the very little ones

> and the lack of clear objective guidelines (fun fact: we aren’t
> actually following the Changelog rules)

Guix have /some/ objective guidelines, they can be enhanced, please help
the project find better rules or document it better; the fun fact Guix
is not actually following the "rules" is because they are actually not
rules but guidelines for best practice in documenting commits for rewiew
purposes

> that means that even something as trivial (compared to the rest of the
> work) as the commit message must be placed on the pile of chores.

You (and others) find it chore, I (and others) find it a very useful
work.

> Add on top of that that there’s a low probability of gratification,
> because committers like myself are getting burned out and so patches
> simply go unacknowledged or only ever see a first cursory review.

I know and understand this class of probolems but this have nothing to
do with the ChangeLog format.

> We can’t blame anyone for seeing these two piles and come to the
> conclusion that it’s not worth the hassle — especially when operating
> your own channel is so easy in comparison.

I'm not blaming Katherine, I respect her decision; I just wanted to say:
please don't blame the guidelines about ChangeLog for the two (or more)
piles.

I see there are several different management problems, I'm not trying to
say all is fine and good, but IMO the "manage git commit messages
following the Guix guidelines" is the last of this management problems.

-- 
Giovanni Biscuolo

Xelera IT Infrastructures


signature.asc
Description: PGP signature

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

[Efraim Flashner]

On Fri, Sep 08, 2023 at 11:53:43AM +0200, Giovanni Biscuolo wrote:
> Hello Katherine,
> 
> Katherine Cox-Buday  writes:
> 
> [...]
> 
> > By "standard" I mean the GNU Changelog format
> > (https://www.gnu.org/prep/standards/standards.html#Change-Logs). As
> > in: it's expected that commit messages use this format.
> 
> [...]
> 
> > In my response I was trying to point out a flaw in your comparison: that 
> > with style guidelines, which are also complicated, there is usually a 
> > formatter that will do it for me, or a linter that will tell me that 
> > something is not meeting the standard. This is because languages have 
> > grammars, and linters have higher-order system grammars.
> 
> AFAIU you are talking about the "Formatting Code" /subset/ of a "Coding
> style", because there is no linter that will tell you if you are
> following the subset called "Data Types and Pattern Matching" [1]: am I
> wrong?
> 
> Back to the git commit message formatting: please can you provide us
> with one or two examples of how a commit message should be formatted and
> what linter is available for that syntax?
> 
> [...]
> 
> > Here is my channel with things I intend to upstream, but haven't,
> > largely because of this friction.
> 
> By "this friction" you mean you miss a linter for commit messages?
> 
> Or do you mean you do not agree with the style requested by Guix (and
> GNU) for the commit messages?
> 
> You are obviously free not to contribute your patches upstream but the
> fact that you decided not to because it's "too hard" (my executive
> summary about your complaints about Change Log content rules) to write
> commit messages suitable for contribution it _not_ a Guix maintainers
> fault, not at all.
> 
> Obviously everyone is free to comment, ask for clarifications or
> proposing **patches**, but it's not fair to say "I'm not contributing
> largerly because I've a specific friction with the rules about commit
> messages" (again, my executive summary).
> 
> [...]
> 
> Ciao, Gio'

That wasn't my read of it at all. I too have many packages which I
haven't upstreamed. One of the major pushes that I did was cleaning up
mailman and pushing them to Guix. I had just finished working on it
earlier in the week and it turned out I didn't actually need it anymore,
but I figured better in Guix than out. It was either one or two 8 hour
days of reviewing my own patches, making sure they all built correctly,
and then finally committing them. I also have almost 500 go packages
which I don't intend to upstream. I'm package them and update them
occasionally when trying to package some big application like gitea or
keybase or tailscale or gotosocial, but the effort to go through and see
which packages are ACTUALLY needed and to clean up everything, it's just
too much for me.

I suppose this could be construed as "I'm not contributing these
packages because I don't like go" but that's not the whole of it. And by
rephrasing it like that takes out the nuance of other bits of why I
haven't worked on those packages and neuters the discussion about why
these are my packages instead of our packages.

As far as commit messages, I've found that the script in
etc/committer.scm to be very nice, even if there are plenty of cases
where it doesn't do the job. I do think there's room for improvement and
that may be one of the things we can do to make contributing easier.

-- 
Efraim Flashner  רנשלפ םירפא
GPG key = A28B F40C 3E55 1372 662D  14F7 41AA E7DC CA3D 8351
Confidentiality cannot be guaranteed on emails sent or received unencrypted


signature.asc
Description: PGP signature

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

[Ricardo Wurmus]

Giovanni,

> You are obviously free not to contribute your patches upstream but the
> fact that you decided not to because it's "too hard" (my executive
> summary about your complaints about Change Log content rules) to write
> commit messages suitable for contribution it _not_ a Guix maintainers
> fault, not at all.

As a former Guix co-maintainer I disagree with this take.  (Nobody even
brought up the word “fault”, which is a particularly unhelpful lens for
understanding social issues, in my opinion.)

“too hard” sounds (perhaps unintentionally) derisive.  It’s a real issue
for the projects when very capable contributors like Katherine encounter
numerous little obstacles that in aggregate lead to a very rational
decision to be selective about what contribution to send off on this
unnecessarily long journey.

It’s not that writing commit messages is hard.  It’s one of many
obstacles, and the lack of clear objective guidelines (fun fact: we
aren’t actually following the Changelog rules) that means that even
something as trivial (compared to the rest of the work) as the commit
message must be placed on the pile of chores.  Add on top of that that
there’s a low probability of gratification, because committers like
myself are getting burned out and so patches simply go unacknowledged or
only ever see a first cursory review.

We can’t blame anyone for seeing these two piles and come to the
conclusion that it’s not worth the hassle — especially when operating
your own channel is so easy in comparison.

Katherine, I’m very happy you brought this up and continue to respond in
this thread to clarify and steer the discussion into a fruitful
direction.  I know I couldn’t do it.  I thank you for this work, and I
hope that the project can come up with ways to lower the barriers to
entry.

-- 
Ricardo


PS: It’s probably no exaggeration to say that I’m only still
contributing to Guix because I already *have* commit access and I’m
committed to ensuring that support for R and science packages doesn’t
degrade.  That alone keeps me busy.  While commit messages aren’t really
an obstacle for me personally (probably because nobody judges my
messages), I probably wouldn’t be able to justify spending my now very
limited free time to contributing to Guix now that the reward/effort
scale is so unbalanced.

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

[Giovanni Biscuolo]

Hi!

Simon Tournier  writes:

[...]

> For example, we communicate in English.  It appears to me impossible to
> send a contribution without having some basic knowledge of English.

And, believe me or not, for me /that/ is a **significant** cognitive
overhead not just to contribute to international projects [1] (including
our company internal projects), but also to efficiently communicate in
international mailing lists like this one.

For me (actually for all) using a natural language, especially a foreign
one, is a constant hack! :-)

[...]

> What is the thing that will tell me that the English I wrote is not
> meeting the standard?

> Why do we accept this “friction” about English filtering people?
>
> Well, I am stretching a bit to make my point. :-)

Yes, it's a stretch but IMO it helps making the poing about the sources
of friction when participating in discussions and trying to contribute
to a "crowded" international project, with people with very different
competences in English language, including technical English,
programming languages **and** tools.

[...]

>> In the US, the phrase "I don't buy it" is usually the response to 
>> someone trying to trick you into something. This is a little hurtful 
>> because it's either saying:
>
> Sorry, it was not my intent.  I was expressing: I do not believe it is
> *the* real problem.

(Let me use some humor please)

The frinction here comes from the fact that all natural languages suck,
no one sucks less :-O

The 5th definition of the transitive verb "buy" taken from
Merriam-Webster is:

--8<---cut here---start->8---

5: ACCEPT, BELIEVE
   I don't buy that hooey.
   — often used with into
   buy into a compromise

--8<---cut here---end--->8---

So AFAIU "I don't buy it" means "I dont's [accept|believe] it": no?

...but maybe the Merriam-Webster is too British :-D

[...]

Happy haking! Gio'



[1] have you an idea of the time I spend to translate concepts to be
expressed in commit message in English?  Why I cannot just write in my
very good Italian and "git send-email" happily?

-- 
Giovanni Biscuolo

Xelera IT Infrastructures


signature.asc
Description: PGP signature

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

[Giovanni Biscuolo]

Hello Katherine,

Katherine Cox-Buday  writes:

[...]

> By "standard" I mean the GNU Changelog format
> (https://www.gnu.org/prep/standards/standards.html#Change-Logs). As
> in: it's expected that commit messages use this format.

[...]

> In my response I was trying to point out a flaw in your comparison: that 
> with style guidelines, which are also complicated, there is usually a 
> formatter that will do it for me, or a linter that will tell me that 
> something is not meeting the standard. This is because languages have 
> grammars, and linters have higher-order system grammars.

AFAIU you are talking about the "Formatting Code" /subset/ of a "Coding
style", because there is no linter that will tell you if you are
following the subset called "Data Types and Pattern Matching" [1]: am I
wrong?

Back to the git commit message formatting: please can you provide us
with one or two examples of how a commit message should be formatted and
what linter is available for that syntax?

[...]

> Here is my channel with things I intend to upstream, but haven't,
> largely because of this friction.

By "this friction" you mean you miss a linter for commit messages?

Or do you mean you do not agree with the style requested by Guix (and
GNU) for the commit messages?

You are obviously free not to contribute your patches upstream but the
fact that you decided not to because it's "too hard" (my executive
summary about your complaints about Change Log content rules) to write
commit messages suitable for contribution it _not_ a Guix maintainers
fault, not at all.

Obviously everyone is free to comment, ask for clarifications or
proposing **patches**, but it's not fair to say "I'm not contributing
largerly because I've a specific friction with the rules about commit
messages" (again, my executive summary).

[...]

Ciao, Gio'


[1] 
https://guix.gnu.org/en/manual/devel/en/html_node/Data-Types-and-Pattern-Matching.html

-- 
Giovanni Biscuolo

Xelera IT Infrastructures


signature.asc
Description: PGP signature

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

[Giovanni Biscuolo]

Hi all!

I think the discussion about ChangeLog Style shows we probably need to:

1. enhance the manual section "22.6 Submitting Patches"
https://guix.gnu.org/en/manual/devel/en/html_node/Submitting-Patches.html

--8<---cut here---start->8---

Please write commit logs in the ChangeLog format (see Change Logs in GNU Coding 
Standards); you can check the commit history for examples.

You can help make the review process more efficient, and increase the chance 
that your patch will be reviewed quickly, by describing the context of your 
patch and the impact you expect it to have. For example, if your patch is 
fixing something that is broken, describe the problem and how your patch fixes 
it. Tell us how you have tested your patch. Will users of the code changed by 
your patch have to adjust their workflow at all? If so, tell us how. In 
general, try to imagine what questions a reviewer will ask, and answer those 
questions in advance.

--8<---cut here---end--->8---

IMO we should move the above paragraphs to a new subsection "22.6.N
Change Logs" and add some rationale (summarized from the GNU Standards
section and maybe with some specific Guix ratio expressed in this
section), a general rule (to be interpreted by humans, see below) and
some examples taken by one or two relevant commits recently made.

2. enhance the section section "22.3 The Perfect Setup" 

The proposed new "22.6.N Change Logs" subsection above should also
provide a link to the relevant information about the snippets documented
in section "22.3 The Perfect Setup"... and /vice versa/: the "snippets
section" should reference the "Change Log" section, since snippets are
made to automate the general rules provided in "Change Log"; I'd also
separate the paragraph related to snippets in a "22.3.1 Emacs snippets"
section

3. wellcome snippets for different IDEs

Somewhere™ in our manual we should say that we are very glad to accept
patches (alco to documentation) to add snippets for free software IDEs
templating systems other than Emacs Yasnippet or Tempel, like
vim-neosnippet for vim or the native templating system of Kate [1], for
example.  Other examples?

4. add a git commit message template

https://www.git-scm.com/book/en/v2/Customizing-Git-Git-Configuration#_commit_template

--8<---cut here---start->8---

If your team has a commit-message policy, then putting a template for that 
policy on your system and configuring Git to use it by default can help 
increase the chance of that policy being followed regularly.

--8<---cut here---end--->8---

I'd write a template with a very short explanation on the commit message
*basics* (first line is Subject max 50 chars, blank line, body) and some
https and info link to the relevant section of the manual about Change
Log format.

Suggestions for other git template content are very wellcome.

This template will be added to the git config file etc/git/gitconfig,
that is automatically configured when building the project as stated in
"22.6.1 Configuring Git".



I'll try to send a patchset for 1., 2. and 3; a separate one for 4.

WDYT?

Maxim Cournoyer  writes:

[...]

>> On 2023-09-06, Liliana Marie Prikler wrote:

[...]

>>> It's 
>>>
>>> * file (variable)[field]{do you need 4 levels?}

The general form of a ChangeLog Style format for Guix code (Guile with
gexp) could be rewrote as:

* relative-path-of-changed-file (variable) [field] : Description of 
change.

I never saw a {4th level} so AFAIU is not needed, unless someone have a
good example plz: in this case we could add a 4th level to the general
description.

[...]

> Here's an example in the Guix "dialect":
>
> --8<---cut here---start->8---
> * gnu/packages/file.scm (package-symbol)
> [arguments] <#:phases>: New patch-paths phase.
> --8<---cut here---end--->8---
>
> It could also have been:
>
> --8<---cut here---start->8---
> * gnu/packages/file.scm (package-symbol) [arguments]: Add patch-paths
> phase.
> --8<---cut here---end--->8---

Those are good general examples: I'd use them in the manual section
descibed in 1.

WDYT?

> It doesn't really matter, as long as it's clear and you did the exercise
> of reviewing the code you touched and writing down the changes summary
> for the reviewer (and yourself).

This is a good example of ratio, I'd use that also :-)

Happy hacking! Gio'



[1] 
https://docs.kde.org/stable5/en/kate/kate/kate-application-plugin-snippets.html

-- 
Giovanni Biscuolo

Xelera IT Infrastructures


signature.asc
Description: PGP signature

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

[(]

Simon Tournier  writes:
> Since I am French and it is easier for me to comment about my
> disagreements than the converse. ;-)

Feels like literally every national group makes this up about
themselves; British people are stereotypically very prone to
complaining, too :P

  -- (

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

[Development of GNU Guix and the GNU System distribution.]

Hi Katherine,
Hi Liliana,

On Thu, Sep 7, 2023 at 1:39 PM Katherine Cox-Buday
 wrote:
>
> Liliana, many of your responses in this thread are not OK.

Thank you for your candor! I also sensed some negativity in that
interaction. Both of you, please feel free to direct your comments to
me—privately if needed—so as to defuse the personal interaction.

It is a common strategy in parliaments around the world, where members
do not address each other directly.

My phone number is (617) 229-5005.

Kind regards
Felix

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

[Katherine Cox-Buday]

On 9/6/23 3:07 AM, Simon Tournier wrote:


As you said, we are all different, thus it means that any collaboration
cannot be full-frictionless.  Because any social interaction implies
norms and standards.  Norms and standards are by their definition
excluding.

For example, we communicate in English.  It appears to me impossible to
send a contribution without having some basic knowledge of English.  How
do I know that the English I wrote in the docstring, or in the comments
of code, or the name of the procedures, or in the commit message, etc.
how do I know that English is meeting the standard?  There is an
expectation about the English we are using for communicating and that
expectation is complicated enough that it’s easy to get it wrong.  What
is the thing that will tell me that the English I wrote is not meeting
the standard?

Why do we accept this “friction” about English filtering people?


This is an excellent analogy, and a very good parallel to the 
conversation about the Changelog format. It really made me stop and 
think! Thank you!


I can think of a rebuttal, but I'm going to drop this line of 
conversation, as you suggest, since it's not really the point.



I hope that I am demonstrating to always choose kindness.

Well, if we do not have a common understanding about something, then we
cannot communicate about this something, IMHO.  Sharing a common
understanding about something is a core principle to establish
communication and collaboration.

If group A says ’foo’ and group B does not understand ’foo’, this ’foo’
is real for group A but is it real for group B?  Group A and group B
needs to have a common understanding about ’foo’ in order to agree on
how to deal with ’foo’.

My messages in this thread show, I hope, that I am taking seriously this
discussion.  I am doing my best to be empathetic and I am considering
all the concerns.  However, raising a concern does not make it real or
automatically equal with all the others.

 ( Do not take me wrong, I am not saying that for example commit
message format could not be a real friction for some people, I am sure
it is; as using in English is a real friction for some people.  Instead,
I am saying that I fail to get why is it or what makes this commit
message format a real problem. )


Simon, for whatever it's worth, I think you're doing an amazing job. I 
think few people are able to simultaneously not understand something, 
but still engage in thoughtful and empathetic conversation. Really, well 
done.



- Easy is relative: https://youtu.be/SxdOUGdseq4?t=497


Somehow, that’s the remark by Liliana [1],

 Maybe it's time to take a step back and instead of asking “How can we
 decrease the cognitive overhead for contributors?”, we should perhaps
 ask “For which contributors do we want to/can we decrease the cognitive
 overhead?”


That's interesting, because I view this as the antithesis of what Rich 
was trying to convey.


That quote is at the end of a dismissive ad hominem response which has 
grossly misinterpreted this discussion, even attributes it to malice, 
seems to draw the conclusion that contributing to Guix should be left to 
those for whom the current situation is fine, and even intimates that 
those who would like to improve the situation are incompetent.


Here's the quote from Rich's talk:

   The fact that we throw these things around sort of casually 
saying, "Oh I
   like to use that technology because it's simple. And when I say 
simple I

   mean easy. *And when I'm saying easy, I mean, because I already know
   something that looks very much like that*" is how this whole thing
   degrades, and we can never have objective discussion about the 
qualities

   that matter to us in our software.

Rich is saying that there are intrinsic properties to approaches that 
make them simple, but possibly not easy, and that we shouldn't rest our 
arguments on claiming something is "easy", because that term is 
relative, and often related to familiarity. Familiarity is a hard bias 
to overcome.


I'm here to discuss those intrinsic properties, the contributor 
experience, and see where that leads us.


Contextualized, this quote is insinuating that I'm trying many different 
arguments in an attempt to push an agenda, and that because of this, any 
of the points I've made are suspect and should be dismissed.


Read charitably, this quote suggests that there is a singular, best, way 
to do things, and that if it doesn't work for some, the problem is not 
the process, but that "those people" are incompetent.


This is classic gatekeeping.


which is another way, IMHO, to express what I have tried to say with
“range of contributions” in my first message [2].


- Differentiating the types of complexity (importantly defining
incidental complexity): https://youtu.be/SxdOUGdseq4?t=1173


It appears to me that it is also what I have tried to say in my very
first message [2]. :-)

   

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

[Katherine Cox-Buday]

On 9/5/23 2:43 PM, Liliana Marie Prikler wrote:

Am Dienstag, dem 05.09.2023 um 19:40 +0100 schrieb (:

Liliana Marie Prikler  writes:

Uhm, we have snippets?


Well, those are exclusive to Emacs :)  And without regard to /that/
issue, I do think that there's a problem if the commit format is so
complex that it's not trivial for anyone new to the project to write
them out manually.

By definition, no amount of typing is non-trivial, safe for the empty
amount, which good luck trying to commit your changes by pure mouse
movements, I guess?

Now, if you excuse my French, I think the problem isn't really as much
that people struggle to type out the perfect ChangeLog on the first
try, which also makes it odd to request a linter.  Bear in mind that
committers will sign off anything that appears convincing enough, even
if there are smaller mistakes in the message.  Trust me, I've been
there and seen that; and also done it myself.

Instead, we have seen in this thread appeals to age, appeals to
perceived lack of personal benefit, and now appeals to typing effort,
none of which really make that great of an argument against the
ChangeLog style, especially when they come in combination with a
refusal to make use of already provided tools.  I think we're starting
to see the moving of the goal post as the actual game here.

Maybe it's time to take a step back and instead of asking “How can we
decrease the cognitive overhead for contributors?”, we should perhaps
ask “For which contributors do we want to/can we decrease the cognitive
overhead?”  We have drifted much from the original post that discussed
moms with full-time jobs, who struggle to do “difficult” tasks
(simplified wording; may change the meaning of the OP a little).  Now,
I personally struggle to see how your personal preference for
communication media, commit message style, and other things that were
discussed in any of the preceding threads actually correlate with being
a parent.  However, I do know that with its 150 million users, most
people of the world don't have a Github account.  Being one of the 4
billion email users out there is a comparably low barrier of entry
imho.  So, whose cognitive overhead do you want to reduce (besides the
obvious "my own", which everyone always tries)?


Liliana, many of your responses in this thread are not OK. They have 
been dismissive and have strayed into personal attacks. At times I'm not 
sure if you're intentionally misinterpreting the conversation to try and 
make a point.


If you disagree with something, or have a point to make, please do so 
directly, and without attacking anyone's character or making veiled 
innuendos about their motives or capabilities.


Speaking for myself, I think if you asked me questions instead of 
inferring narratives, you'd find that our values and preferences are 
probably more closely aligned than you realize.


We're all here to try and make Guix better, but we can't do that in a 
hostile environment.

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

[kiasoc5]

Hello,

On 2023-09-06 04:49, Maxim Cournoyer wrote:

Hi Katherine,

Katherine Cox-Buday  writes:


On 9/5/23 10:01 AM, Simon Tournier wrote:

Well, somehow, I consider the commit message format similarly as 
coding

style.  We can discuss which one is better than the other when at the
end it only reflects some artificial preferences and for the sake of 
any

project one needs to be arbitrarily picked.  Why not ChangeLog?


The distinction I draw is that I can usually run a linter against a
coding style.

I don't care very much what the standard for commit messages is other
than if it has an expectation of structure, I be able to run a tool to
tell me if it's wrong.

In other words, the overhead isn't "I don't like this standard", it's
"I can't find a way to reliably adhere to the standard".


'git log' should provide ample examples.  The format is not strict, and
it doesn't matter overly as long as it conveys a summary of the changes
accurately; it is meant for us humans.  The format is described
summarily in the GNU Standards document; to read it, you can run:

  guix shell standards info-reader -- info '(standards) ChangeLog'


Would be good to distill these conversations to the manual.

It would also be nice to add a section to the cookbook on explaining the 
parts of the commit message as it relates to Guix as a quick reference 
instead of grepping around for several wordings of the same action. From 
what I remember there's at least these parts to mention:


- including the package name and version on upgrades
- any changes to phases
- any changes to new input style, G-expressions, removal of trailing #t

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

[Development of GNU Guix and the GNU System distribution.]

Hello,

I wanted to add to this thread my 2 cents. As a person who has recently
(last months) made the first attempts at contributing.

To me, registrations and reliance on JS had always been an obstacle to
using web-based forges. This is one of the reasons I haven't been
contributing to existing projects in the past.

With Guix this issue is gone but there's also another thing that
incentivized me — that, since joining the Guix mailing lists, I am
seeing activity all the time, right at my fingertips (because I have my
email client opened most of the time).

So far I have sent patches 4 times. Once it was a simple update that got
accepted quickly, once I was addressing a problem that turned out to be
better solvable another way and 2 submissions are still waiting for
someone to review them.

Although I had to learn to use `git format-patch` and related tools, I
don't consider it a problem. Actually, I wanted to learn email-based
workflow anyway because it seems to be a more KISS way of software
development.

The amount of new stuff to learn can, however, be a bit overwhelming. I
did learn to use git to send emails but haven't yet started using any of
the templating packages for Emacs that were recommended in Guix
documentation. It would be just too much to process at once.

Do I think Guix has a problem with cognitive overhead? Not at all.
Rather, it seems to be addressing the problems really well.
1. It makes it easy to hack on itself without the need to clone the
   repo first. That's what helped me get familiar with it before I
   could even try to contribute anything.
2. It, by default, updates to the most up-to-date version.
3. It has some detailed documentation.
4. It eases the setting up of one's development environment.

I fact, I suspect the email-based workflow might be automatically
filtering out some bad submissions that would have been made otherwise.
The geeky nature of the project does put it in a kind of a niche where
only geeks dwell. But this is somewhat benefitial because geeks are
those who can build it.

Lastly, sorry if something I wrote is a duplicate of other's opinions —
the thread got s long it'd be hard to read through 100% of it

Best,
Wojtek

-- (sig_start)
website: https://koszko.org/koszko.html
fingerprint: E972 7060 E3C5 637C 8A4F  4B42 4BC5 221C 5A79 FD1A
follow me on Fediverse: https://friendica.me/profile/koszko/profile

♥ R29kIGlzIHRoZXJlIGFuZCBsb3ZlcyBtZQ== | ÷ c2luIHNlcGFyYXRlZCBtZSBmcm9tIEhpbQ==
✝ YnV0IEplc3VzIGRpZWQgdG8gc2F2ZSBtZQ== | ? U2hhbGwgSSBiZWNvbWUgSGlzIGZyaWVuZD8=
-- (sig_end)


On Tue, 05 Sep 2023 22:43:04 +0200 Liliana Marie Prikler 
 wrote:

> Am Dienstag, dem 05.09.2023 um 19:40 +0100 schrieb (:
> > Liliana Marie Prikler  writes:  
> > > Uhm, we have snippets?  
> > 
> > Well, those are exclusive to Emacs :)  And without regard to /that/
> > issue, I do think that there's a problem if the commit format is so
> > complex that it's not trivial for anyone new to the project to write
> > them out manually.  
> By definition, no amount of typing is non-trivial, safe for the empty
> amount, which good luck trying to commit your changes by pure mouse
> movements, I guess?
> 
> Now, if you excuse my French, I think the problem isn't really as much
> that people struggle to type out the perfect ChangeLog on the first
> try, which also makes it odd to request a linter.  Bear in mind that
> committers will sign off anything that appears convincing enough, even
> if there are smaller mistakes in the message.  Trust me, I've been
> there and seen that; and also done it myself.
> 
> Instead, we have seen in this thread appeals to age, appeals to
> perceived lack of personal benefit, and now appeals to typing effort,
> none of which really make that great of an argument against the
> ChangeLog style, especially when they come in combination with a
> refusal to make use of already provided tools.  I think we're starting
> to see the moving of the goal post as the actual game here. 
> 
> Maybe it's time to take a step back and instead of asking “How can we
> decrease the cognitive overhead for contributors?”, we should perhaps
> ask “For which contributors do we want to/can we decrease the cognitive
> overhead?”  We have drifted much from the original post that discussed
> moms with full-time jobs, who struggle to do “difficult” tasks
> (simplified wording; may change the meaning of the OP a little).  Now,
> I personally struggle to see how your personal preference for
> communication media, commit message style, and other things that were
> discussed in any of the preceding threads actually correlate with being
> a parent.  However, I do know that with its 150 million users, most
> people of the world don't have a Github account.  Being one of the 4
> billion email users out there is a comparably low barrier of entry
> imho.  So, whose cognitive overhead do you want to reduce (besides the
> obvious "my own", which everyone always tries)?
> 


pgpVmYY8Y4dB_.pgp

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

[Liliana Marie Prikler]

Am Mittwoch, dem 06.09.2023 um 10:52 -0700 schrieb Vagrant Cascadian:
> I always get tripped up with phases, modify-phases, etc. as there
> seem to be potentially four or more levels deep in some common code
> patterns... for example, a recent commit mentioning phases:
> 
> commit c14c25b4fb625c2a5b9512618b3eb17ff15f7e71
> 
>     gnu: go-github-com-tdewolff-minify-v2: Regenerate hash.
> 
>     * gnu/packages/golang.scm (go-github-com-tdewolff-minify-
> v2)[#:phases]: Add
>     phase 'regenerate-hash.
> ...
> diff --git a/gnu/packages/golang.scm b/gnu/packages/golang.scm
> index 44953d6111..3c486c4121 100644
> --- a/gnu/packages/golang.scm
> +++ b/gnu/packages/golang.scm
> @@ -3685,11 +3685,24 @@ (define-public go-github-com-tdewolff-minify-
> v2
> 
> "0h006wpfkl0ls0skqxblwcanrhmphgq5q0ii26l2ayh7s99cgmy3"
>  (build-system go-build-system)
>  (arguments
> - (list #:import-path "github.com/tdewolff/minify/v2"))
> + (list #:import-path "github.com/tdewolff/minify/v2"
> +   #:phases
> +   #~(modify-phases %standard-phases
> +   (add-after 'unpack 'regenerate-hash
> ...
> 
> Why is it not more like:
> 
>     * gnu/packages/golang.scm
>     (go-github-com-tdewolff-minify-v2)[arguments][phases][modify-
> phases]:
>     Add 'regenerate-hash.
> 
> Honestly, that *seems* ridiculous to me, but I do not understand
> *why* based on the comment above or other patterns I have observed in
> the wild.
For one, reusing the same pair of braces is dangerous when you actually
need to split lines, which eventually, of course, you will.  So don't.
Use different pairs.

> My inclination would be:
> 
>     (go-github-com-tdewolff-minify-v2)[arguments]: Add phase
> 'regenerate-hash.
> 
> What goes in the square brackets? How many levels deep? Do I put
> something in the prose of the comment or in square brackets?
You can use ‘fancy quotes’ in ChangeLogs, which would break scheme
syntax.  So 

(go-github-com-tdewolff-minify-v2)[arguments]: Add ‘regenerate-
hash’ phase.

would be clearer than your suggestion.  Why use [#:phases] then? 
Because people understand it to be a shorthand for
[arguments]<#:phases>, the most common way in which the arguments field
changes.  If you change both that and idk, <#:configure-flags>, you'd
type them out.

> I can see how really not wanting to iterate with N back-and-forth
> discussions in review could hinder someone with a less flexible
> schedule, especially if there are no other significant changes to the
> patch... it could get demotivating.
You won't get N back and forth discussions solely on the format of the
ChangeLog.  If it were just that, the reviewer could just write it on
their own and be done with it; there's typically code changes as well
involved or at the very least undocumented changes that ought to be
documented.


Cheers

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

[Christopher Baines]

Maxim Cournoyer  writes:

> Hi Vagrant,
>
> Vagrant Cascadian  writes:
>
>> On 2023-09-06, Liliana Marie Prikler wrote:
>>> Am Dienstag, dem 05.09.2023 um 19:41 -0400 schrieb brian
 ‘* foo/bar.scm new-package (inputs): add input’
 
 stuff. I literally can never remember this format, no matter how many
 times I do it. I'm reasonably sure square brackes go in there some
 where. It can take me quite a while to put together all that stuff,
 even with magit's help.
>>> It's 
>>>
>>> * file (variable)[field]{do you need 4 levels?}
>>
>> Honestly, not knowing the difference between a variable and field and
>> selector... this comment is of little help to me.
>>
>> I always get tripped up with phases, modify-phases, etc. as there seem
>> to be potentially four or more levels deep in some common code
>> patterns... for example, a recent commit mentioning phases:
>
> The ChangeLog Style section suggests there should be spaces between the
> "markers".  It also says the square brackets should be used to denote a
> change made in a conditional code path, so we're abusing the meaning of
> it in Guix to just a 'field' (which is, a record field, or slot, for the
>  record in Guix).  < > is to precise even more the place
> modified.  They're just shortcuts to avoid less typing while remaining
> readable.
>
> Here's an example in the Guix "dialect":
>
> * gnu/packages/file.scm (package-symbol)
> [arguments] <#:phases>: New patch-paths phase.
>
>
> It could also have been:
>
> * gnu/packages/file.scm (package-symbol) [arguments]: Add patch-paths
> phase.
>
> It doesn't really matter, as long as it's clear and you did the exercise
> of reviewing the code you touched and writing down the changes summary
> for the reviewer (and yourself).

I think I have a similar feeling to Vagrant, and on whether this
matters, I think it matters a lot.

In terms of encouraging people to contribute to Guix, we want the
documentation to set people up for success, or at least feeling like
they're doing things correctly.

The docs say:

  Please write commit logs in the ChangeLog format (see Change Logs in
  GNU Coding Standards); you can check the commit history for examples.

Which is expecting a lot of people who haven't encountered this
before. My view on this is that asking people to perform this task that
isn't very well documented or defined, and which people reviewing and
committing the changes will comment on or revise (maybe to be
objectively better, or maybe just in their own style) discourages people
to continue to contribute, especially those that care more about not
making mistakes/getting things right, or that lack confidence.

I'm indifferent about how we write the commit messages, I'm strongly in
favour of the expectations being clear and documented so that if people
new to the project want to attempt to write a good commit message,
they're setup for success with good documentation, and if something they
write can be improved, there should be some bit of documentation you can
point them to.


signature.asc
Description: PGP signature

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

[Liliana Marie Prikler]

Am Dienstag, dem 05.09.2023 um 20:34 -0600 schrieb Katherine Cox-Buday:
> In the US, the phrase "I don't buy it" is usually the response to 
> someone trying to trick you into something. This is a little hurtful 
> because it's either saying:
> 
> "You have an ulterior motive and are trying to trick me into doing 
> something."
> 
> or
> 
> "I don't have the same experience as you, so you must be lying."
In the US, you also have multi-level marketing schemes, where people,
fully believing in the product itself without any ulterior motive of
their own and without lying (for they know no better), perpetuate
scams.  And since both social media (including our well known code
hosting platforms) operate like multi-level marketing schemes and
conventions at least have the potential to do so, there can be fair
grounds for rejecting ("not buying") them even without assuming malice
on the part of the person proposing them.

In other words, I don't buy that not buying something is expressly
reserved to instances of deliberate trickery.  At the very least, the
dictionary definition of refusing to believe something leaves open the
reasons as for why one does so.

Cheers

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

[Liliana Marie Prikler]

Am Mittwoch, dem 06.09.2023 um 00:04 +0200 schrieb wolf:
> On 2023-09-05 22:43:04 +0200, Liliana Marie Prikler wrote:
> > Am Dienstag, dem 05.09.2023 um 19:40 +0100 schrieb (:
> > > Liliana Marie Prikler  writes:
> > > > Uhm, we have snippets?
> > > 
> > > Well, those are exclusive to Emacs :)  And without regard to
> > > /that/ issue, I do think that there's a problem if the commit
> > > format is so complex that it's not trivial for anyone new to the
> > > project to write them out manually.
> > By definition, no amount of typing is non-trivial, safe for the
> > empty amount, which good luck trying to commit your changes by pure
> > mouse movements, I guess?
> > 
> > Now, if you excuse my French, I think the problem isn't really as
> > much that people struggle to type out the perfect ChangeLog on the
> > first try, which also makes it odd to request a linter.  Bear in
> > mind that committers will sign off anything that appears convincing
> > enough, even if there are smaller mistakes in the message.  Trust
> > me, I've been there and seen that; and also done it myself.
> > 
> > Instead, we have seen in this thread appeals to age, appeals to
> > perceived lack of personal benefit, and now appeals to typing
> > effort, none of which really make that great of an argument against
> > the ChangeLog style, especially when they come in combination with
> > a refusal to make use of already provided tools.
> 
> I went through the snippets, and through the GNU documentation[0] and
> I am still not clear on how exactly should the commit message for a
> change in .dir-locals.el look like.  Maybe I did miss some tools or
> documentation?
Our snippets cover the most common cases, and editing the .dir-locals
happens quite rarely :)

> The "you can check the commit history for example" advice from the
> 22.6 page of documentations gives me 4 different styles in last 4
> commits.  Ok, just joking, 3 styles, the 4th is a typo (`* .dir-
> localsl.el: Add ...').
Regarding only the ChangeLog, I see 1.5 styles – that is
"* .dir-locals.el:"
and
"* .dir-locals.el (some specifier):"

Both are okay.  Regarding the header, you are free in what to type,
since it's at the top directory anyway.

> 0: https://www.gnu.org/prep/standards/html_node/Change-Logs.html
> 
> > I think we're starting to see the moving of the goal post as the
> > actual game here. 
> > 
> > Maybe it's time to take a step back and instead of asking “How can
> > we decrease the cognitive overhead for contributors?”, we should
> > perhaps ask “For which contributors do we want to/can we decrease
> > the cognitive overhead?”
> 
> While I do risk taking this slightly more off topic, I personally am
> more interested in what can be done to help the committers, not
> contributors.  My biggest grievance with trying to contribute is not
> the process nor the tools, but the lack of reviews.  Having a patch
> sitting there without any reaction nor feedback is frustrating.  Do
> you see any process/tooling changes that could help on this front,
> even if they would make life harder for the contributors?
To be completely honest, mumi recalling everything at 0 precision is my
biggest pet peeve at the moment, but I don't think it's solely
responsible for the lack of reviews.  Even back when it did produce
reasonable results, patches were overlooked, which people often worked
around by asking for attention e.g. on IRC.

I don't think we should make things harder for contributors, but having
an interface where e.g. patches that have been unnoticed for about a
week or longer can easily be retrieved would definitely make things
easier.  Also, stuff like finding issues where CI lights green and
(non-committer) reviewers have said LGTM would be a big help.  I don't
see how we could implement this without rolling out a big knowledge
graph, though ;)

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

[Maxim Cournoyer]

Hi Vagrant,

Vagrant Cascadian  writes:

> On 2023-09-06, Liliana Marie Prikler wrote:
>> Am Dienstag, dem 05.09.2023 um 19:41 -0400 schrieb brian
>>> ‘* foo/bar.scm new-package (inputs): add input’
>>> 
>>> stuff. I literally can never remember this format, no matter how many
>>> times I do it. I'm reasonably sure square brackes go in there some
>>> where. It can take me quite a while to put together all that stuff,
>>> even with magit's help.
>> It's 
>>
>> * file (variable)[field]{do you need 4 levels?}
>
> Honestly, not knowing the difference between a variable and field and
> selector... this comment is of little help to me.
>
> I always get tripped up with phases, modify-phases, etc. as there seem
> to be potentially four or more levels deep in some common code
> patterns... for example, a recent commit mentioning phases:

The ChangeLog Style section suggests there should be spaces between the
"markers".  It also says the square brackets should be used to denote a
change made in a conditional code path, so we're abusing the meaning of
it in Guix to just a 'field' (which is, a record field, or slot, for the
 record in Guix).  < > is to precise even more the place
modified.  They're just shortcuts to avoid less typing while remaining
readable.

Here's an example in the Guix "dialect":

--8<---cut here---start->8---
* gnu/packages/file.scm (package-symbol)
[arguments] <#:phases>: New patch-paths phase.
--8<---cut here---end--->8---

It could also have been:

--8<---cut here---start->8---
* gnu/packages/file.scm (package-symbol) [arguments]: Add patch-paths
phase.
--8<---cut here---end--->8---

It doesn't really matter, as long as it's clear and you did the exercise
of reviewing the code you touched and writing down the changes summary
for the reviewer (and yourself).
  
-- 
Thanks,
Maxim

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

[Vagrant Cascadian]

On 2023-09-06, Liliana Marie Prikler wrote:
> Am Dienstag, dem 05.09.2023 um 19:41 -0400 schrieb brian
>> ‘* foo/bar.scm new-package (inputs): add input’
>> 
>> stuff. I literally can never remember this format, no matter how many
>> times I do it. I'm reasonably sure square brackes go in there some
>> where. It can take me quite a while to put together all that stuff,
>> even with magit's help.
> It's 
>
> * file (variable)[field]{do you need 4 levels?}

Honestly, not knowing the difference between a variable and field and
selector... this comment is of little help to me.

I always get tripped up with phases, modify-phases, etc. as there seem
to be potentially four or more levels deep in some common code
patterns... for example, a recent commit mentioning phases:

commit c14c25b4fb625c2a5b9512618b3eb17ff15f7e71

gnu: go-github-com-tdewolff-minify-v2: Regenerate hash.

* gnu/packages/golang.scm (go-github-com-tdewolff-minify-v2)[#:phases]: Add
phase 'regenerate-hash.
...
diff --git a/gnu/packages/golang.scm b/gnu/packages/golang.scm
index 44953d6111..3c486c4121 100644
--- a/gnu/packages/golang.scm
+++ b/gnu/packages/golang.scm
@@ -3685,11 +3685,24 @@ (define-public go-github-com-tdewolff-minify-v2
 "0h006wpfkl0ls0skqxblwcanrhmphgq5q0ii26l2ayh7s99cgmy3"
 (build-system go-build-system)
 (arguments
- (list #:import-path "github.com/tdewolff/minify/v2"))
+ (list #:import-path "github.com/tdewolff/minify/v2"
+   #:phases
+   #~(modify-phases %standard-phases
+   (add-after 'unpack 'regenerate-hash
...

Why is it not more like:

* gnu/packages/golang.scm
(go-github-com-tdewolff-minify-v2)[arguments][phases][modify-phases]:
Add 'regenerate-hash.

Honestly, that *seems* ridiculous to me, but I do not understand *why*
based on the comment above or other patterns I have observed in the
wild.

My inclination would be:

(go-github-com-tdewolff-minify-v2)[arguments]: Add phase 'regenerate-hash.

What goes in the square brackets? How many levels deep? Do I put
something in the prose of the comment or in square brackets?

For me, all this is only from observing many commits, submitting a few
patches, getting some good feedback, but really at the end of the day I
am just cargo-culting...

I have been submitting patches, and even pushing commits to guix for
several years now, and it is still quite unclear to me.

I can wing it just fine, and am able to submit imperfect patches and
have patience for reviews and suggestions and have the resources to
respond (at least, most of the time)...

I can see how really not wanting to iterate with N back-and-forth
discussions in review could hinder someone with a less flexible
schedule, especially if there are no other significant changes to the
patch... it could get demotivating.

It is obviously tricky, as sometimes people need back-and-forth
discussion to learn... though maybe they would rather focus their
limited energy learning how to program, a new language (guile), or just
learning how guix works in practice.

For some people, they might just not have the time or emotional energy
and just prefer to keep their changes in their local branch so they can
move on to the next thing that actually is motivating their work,
tinkering, play, etc. or move on to something else entirely which is
more rewarding, such as gardening...

This is not to say there is no value in the current commit message
format norms. Obviously some people have described the value it has for
them...

One value may be contextually dependent and sometimes at odds with other
values.


live well,
  vagrant


signature.asc
Description: PGP signature

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

[Liliana Marie Prikler]

Am Dienstag, dem 05.09.2023 um 19:41 -0400 schrieb brian
> ‘* foo/bar.scm new-package (inputs): add input’
> 
> stuff. I literally can never remember this format, no matter how many
> times I do it. I'm reasonably sure square brackes go in there some
> where. It can take me quite a while to put together all that stuff,
> even with magit's help.
It's 

* file (variable)[field]{do you need 4 levels?}

HTH

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

[Maxim Cournoyer]

Hi,

Attila Lendvai  writes:

>> also not as obvious (you search for lines added or removed or changed,
>> not easy language such as 'gnu: package-name: Add').
>
>
> i'm pretty sure that the source of the annoyance is not the strict
> format in the summary line, but the formal details in the commit
> message body.

Agreed, but my point still holds.  The search space of our ChangeLog
messages is much smaller than that of the whole code base, thus is
faster (more efficient) and can be done interactively easily from the
'git log' output in your favorite $PAGER, as Andreas mentioned.

-- 
Thanks,
Maxim

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

[Ekaitz Zarraga]

> > also not as obvious (you search for lines added or removed or changed,
> > not easy language such as 'gnu: package-name: Add').
> 
> 
> 
> i'm pretty sure that the source of the annoyance is not the strict format in 
> the summary line, but the formal details in the commit message body.

Yes.
For me it is. But in any case, this is not a barrier for me to contribute.
It's probably more annoying for those who need to review my commits. Which is 
also bad.

I also feel bad because I always manage to screw them up, but I keep trying.

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

[Attila Lendvai]

> also not as obvious (you search for lines added or removed or changed,
> not easy language such as 'gnu: package-name: Add').


i'm pretty sure that the source of the annoyance is not the strict format in 
the summary line, but the formal details in the commit message body.

-- 
• attila lendvai
• PGP: 963F 5D5F 45C7 DFCD 0A39
--
“Until you make the unconscious conscious, it will direct your life and you 
will call it fate.”
— Carl Jung (1875–1961)

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

[Simon Tournier]

ke to draw your attention 
> to a few points:

Thanks for this pointer, I already knew it.  Yeah, that’s a good talk.
Maybe my first reply was a kind of unconscious digest of this. ;-) Well,
I have just watched it again. :-)

> - Easy is relative: https://youtu.be/SxdOUGdseq4?t=497

Somehow, that’s the remark by Liliana [1],

Maybe it's time to take a step back and instead of asking “How can we
decrease the cognitive overhead for contributors?”, we should perhaps
ask “For which contributors do we want to/can we decrease the cognitive
overhead?”

which is another way, IMHO, to express what I have tried to say with
“range of contributions” in my first message [2].

> - Differentiating the types of complexity (importantly defining 
> incidental complexity): https://youtu.be/SxdOUGdseq4?t=1173

It appears to me that it is also what I have tried to say in my very
first message [2]. :-)

Well, from my point of view, we are using here the term “contribution”
as it was one homogeneous thing.  Instead, I think the term refers to a
range with a gradual complexity.  And the improvements or tools maybe
also need to be gradual depending on this range.

> The crucial point of this talk for me is when Rich draws an analogy to 
> juggling (https://youtu.be/SxdOUGdseq4?t=1353). He poses the question: 
> you can juggle a finite number of balls; how many of those do you want 
> to be incidental complexity balls vs. problem complexity balls. In the 
> Guix world, how many of our balls do we want to be the meta of 
> contributing vs. actual code checked into Guix?

So yeah, I am definitely on that page. :-) I am sorry if you have not
felt that I am aligned since my very first message [2].


Well, now re-reading my first message, I feel I am repeating myself so I
move to other topics.

Thank you for opening the discussion and I am convinced that this
fruitful discussion will have a positive output reducing the current
friction for contributing.

Cheers,
simon

1: Re: How can we decrease the cognitive overhead for contributors?
Liliana Marie Prikler 
Tue, 05 Sep 2023 22:43:04 +0200
id:3b274703acaf446ec678e96c9d875c5d6b1a3e17.ca...@gmail.com
https://lists.gnu.org/archive/html/guix-devel/2023-09
https://yhetil.org/guix/3b274703acaf446ec678e96c9d875c5d6b1a3e17.ca...@gmail.com

2: Re: How can we decrease the cognitive overhead for contributors?
Simon Tournier 
Thu, 24 Aug 2023 20:53:14 +0200
id:871qfsuvad@gmail.com
https://lists.gnu.org/archive/html/guix-devel/2023-08
https://yhetil.org/guix/871qfsuvad@gmail.com

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

[Josselin Poiret]

Hi Lily,

Liliana Marie Prikler  writes:

> Instead, we have seen in this thread appeals to age, appeals to
> perceived lack of personal benefit, and now appeals to typing effort,
> none of which really make that great of an argument against the
> ChangeLog style, especially when they come in combination with a
> refusal to make use of already provided tools.  I think we're starting
> to see the moving of the goal post as the actual game here. 

This seems to me like an unwarranted accusation.  The OP and numerous
other users/contributors have reported that they have actual
frustrations with the process here, and I don't think this is an healthy
interaction.

> Maybe it's time to take a step back and instead of asking “How can we
> decrease the cognitive overhead for contributors?”, we should perhaps
> ask “For which contributors do we want to/can we decrease the cognitive
> overhead?”  We have drifted much from the original post that discussed
> moms with full-time jobs, who struggle to do “difficult” tasks
> (simplified wording; may change the meaning of the OP a little).  Now,
> I personally struggle to see how your personal preference for
> communication media, commit message style, and other things that were
> discussed in any of the preceding threads actually correlate with being
> a parent.  However, I do know that with its 150 million users, most
> people of the world don't have a Github account.  Being one of the 4
> billion email users out there is a comparably low barrier of entry
> imho.  So, whose cognitive overhead do you want to reduce (besides the
> obvious "my own", which everyone always tries)?

We could try to time how long it takes to set up the email vs. forge
workflow and do a first contribution, I can bet the former is much
longer than the latter.  Especially if your email host has funky
authentication systems.  I don't think the number of users of each
system is a compelling argument either: you're not going to say that
mowing your lawn with a knife is inherently better because more people
have knives compared to lawnmowers.

Regarding the “mom argument”, I would disagree and say that this is
completely related: interruptions are more costly, you're more likely to
have less attention span, and overall you probably don't want to commit
to 20 steps just to send a contribution.

Best,
-- 
Josselin Poiret


signature.asc
Description: PGP signature

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

[Katherine Cox-Buday]

On 9/5/23 5:55 PM, Simon Tournier wrote:

Hi Katherine,

I am fully aligned with the Survey proposal; at some past Guix Days I
remember discussing a kind of survey á la Haskell or Emacs surveys.
Well, such appears to me very informative to better know how to improve,
from user to contributor.


OK, great! What are next steps, and how can I help?


On Tue, 05 Sep 2023 at 12:00, Katherine Cox-Buday  
wrote:


1. A list of the issues
2. How we'll measure that they're issues
3. How we'll measure improvement against the issues
4. How we'll address the issues

So often in my long career I've worked with organizations/people that
really want to skip to (5): implement something.

Implement a vertically-integrated solution to gather feedback against
reality: yes. Jump straight to the "final solution" with all the details
managed: no.


Since I am French and it is easier for me to comment about my
disagreements than the converse. ;-)


You keep mentioning you're French as some kind of disparaging thing, but 
all the French people I've met (especially our Guix friends) have been 
kind and thoughtful :)



In my career, I have seen the converse: spending plenty of time cooking
all the details of the plan and then being bitten by implementation
“details” that were impossible to predict beforehand.

Instead, I often see the incremental improvements more productive.
Especially when people are volunteers for their contributions and so
their motivation is variable and non-fungible.


I think you've just said the same thing I've said: implement a 
vertically integrated proof of concept and start iterating.


But you need to know the requirements first because even the basic shape 
of your implementation can swing wildly depending on these. E.g. a 
service with three nines of availability can be a fundamentally 
different service than one with four.



I think we have

  #1. a list of issues; some points discussed in this thread
  could be reported as bugs.
  #4. an hope for addressing some of them using a plan (scripts, fix guix
  edit, etc.)

As we discussed earlier, the ’measures’ are the difficult part and there
is too many bias that it’s almost impossible to measure.  At best, the
number of contributors (#2) and some stats from some survey (#3) would
provide some indicators.


I think almost all surveys ask subjective questions. The bias is OK, 
because in aggregate, it at least points towards a consensus or 
indicates that there are undiscovered problems.


For example: "The Guix logo should be blue: agree/disagree?". This is 
completely subjective, but if 95% of responses disagree, and they 
disagree year-over-year, that's an indication that there's some reason 
it shouldn't be blue.


*Maybe* we even find out that a lot of Guix users are color-blind and 
blue just looks gray.


The point isn't that you practice direct democracy and subject yourself 
to the shifting opinions of the responders. The point is to gather data 
and try and draw conclusions based on what you see.


We should probably go ahead and do what we think is best to improve the 
situation, but we should probably also have a standing question about 
this that we ask in our survey to see if the situation is getting better 
or worse.



Maybe I misread, I think we have a consensus about the issues and
about the concrete actionable next steps, no?

  a. Prepare a survey
  b. Report bugs about “guix style” and “guix edit” (and I am probably
 missing other reported in the thread :-))
  c. Look to Build Coordinator and QA [A,B] (ask Chris?) and try to
 extract what this CI does.

Well, from what my opinion is worth here.

A: https://git.savannah.gnu.org/cgit/guix/build-coordinator.git
B: https://git.savannah.gnu.org/cgit/guix/qa-frontpage.git/


That all sounds good to me.

Before I opened this can of worms, I was planning on trying to work on 
the Go branch/packages 
(https://lists.gnu.org/archive/html/guix-devel/2023-08/msg00058.html). 
But since I'm the cause of all this, and it will indirectly help me with 
Go things (which is why I brought it up), how can I help?

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

[Maxim Cournoyer]

Hi Katherine,

Katherine Cox-Buday  writes:

> On 9/5/23 10:01 AM, Simon Tournier wrote:
>
>> Well, somehow, I consider the commit message format similarly as coding
>> style.  We can discuss which one is better than the other when at the
>> end it only reflects some artificial preferences and for the sake of any
>> project one needs to be arbitrarily picked.  Why not ChangeLog?
>
> The distinction I draw is that I can usually run a linter against a
> coding style.
>
> I don't care very much what the standard for commit messages is other
> than if it has an expectation of structure, I be able to run a tool to
> tell me if it's wrong.
>
> In other words, the overhead isn't "I don't like this standard", it's
> "I can't find a way to reliably adhere to the standard".

'git log' should provide ample examples.  The format is not strict, and
it doesn't matter overly as long as it conveys a summary of the changes
accurately; it is meant for us humans.  The format is described
summarily in the GNU Standards document; to read it, you can run:

  guix shell standards info-reader -- info '(standards) ChangeLog'

-- 
Thanks,
Maxim

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

[Katherine Cox-Buday]

On 9/5/23 4:57 PM, Simon Tournier wrote:

Hi,

On Tue, 05 Sep 2023 at 11:01, Katherine Cox-Buday  
wrote:


Well, somehow, I consider the commit message format similarly as coding
style.  We can discuss which one is better than the other when at the
end it only reflects some artificial preferences and for the sake of any
project one needs to be arbitrarily picked.  Why not ChangeLog?

The distinction I draw is that I can usually run a linter against a
coding style.

I don't care very much what the standard for commit messages is other
than if it has an expectation of structure, I be able to run a tool to
tell me if it's wrong.

In other words, the overhead isn't "I don't like this standard", it's "I
can't find a way to reliably adhere to the standard".

Well, I am not sure to fully understand what you have in mind with the
term “standard“.


I'm sorry if I've not explained this well, Simon. Thank you for trying 
to understand.


By "standard" I mean the GNU Changelog format 
(https://www.gnu.org/prep/standards/standards.html#Change-Logs). As in: 
it's expected that commit messages use this format.



   To me, coding style or similarly commit message format
are about standard or norm, meaning they respect a set of rules.

The question is then: is it possible to explicitly write down all the
rules?  Are all the rules all well-defined or are some ambiguous?  etc.

For some norm or standard, it is possible to have a checker because all
the rules are explicitly well-defined.  For many norms/standards, we do
not have any checker.


This is my point. There is an expectation, but no way to check against 
that expectation, and the expectation is complicated enough that it's 
easy to get wrong. The Changelog format is like a little language with 
conditionals about how "simple" the change is, and line length, and 
blank lines.


In my response I was trying to point out a flaw in your comparison: that 
with style guidelines, which are also complicated, there is usually a 
formatter that will do it for me, or a linter that will tell me that 
something is not meeting the standard. This is because languages have 
grammars, and linters have higher-order system grammars.



Now, I have read the thread and I hear the comments about the commit
message format as ChangeLog.  To be honest, I am somehow surprised.  If
after being enough annoyed by something that then one clones the Guix
repository, finds how to improve and last drops all because writing the
commit message is too “complex” or because one does not know if the
commit message correctly adhere to the standard… Sorry, I do not buy.


I don't think anyone has said this. To be explicit: I am not saying 
this. What my original message said, and what others have said, is that 
in aggregate, the steps to contribute produce enough friction so as to 
keep contributions from being proposed and merged. The commit messages 
are part of that aggregate.


Here are others saying this in this thread:

    - https://lists.gnu.org/archive/html/guix-devel/2023-09/msg00040.html

    - https://lists.gnu.org/archive/html/guix-devel/2023-09/msg00051.html

Here is my channel with things I intend to upstream, but haven't, 
largely because of this friction. It includes services and packages.


https://github.com/kat-co/guix-channels/tree/upstream-staging/upstream

For whatever else has been brought up in this thread, I started with this:

    I have given a list of issues to a group of people who are presumably
    analytical, and I think the natural inclination is to go 
point-by-point and
    make arguments for/against. Instead of that[*], I invite you to 
address the

    more abstract issue: (should/how do) we reduce friction for making
    contributions?


And I do not buy either an issue when resuming after an interruption
because writing commit message can be done from the diff.  More than
often, I tweak stuff, then commit with the oneline subject ’DRAFT foo’,
continue to tweak, commit ’DRAFT bar’.  Days or weeks (or months) later,
I resume my work and run “git rebase” for polishing the commit ’DRAFT
foo’ and preparing it for submission.

Again I hear all the comments and I am trying hard to understand.  From
my point of view and from where I stand, my understanding is that the
core point of commit message format is about 1. discipline – the quality
of being able to behave and work in a controlled way which involves
obeying particular rules or standards – and 2. confidence – the willing
to send the perfect message on the first try.  And there is no tool for
fixing these both issues.


In the US, the phrase "I don't buy it" is usually the response to 
someone trying to trick you into something. This is a little hurtful 
because it's either saying:


"You have an ulterior motive and are trying to trick me into doing 
something."


or

"I don't have the same experience as you, so you must be lying."

The only thing I know to do is to respond with my experiences, and try 
to make 

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

[Simon Tournier]

Hi Katherine,

I am fully aligned with the Survey proposal; at some past Guix Days I
remember discussing a kind of survey á la Haskell or Emacs surveys.
Well, such appears to me very informative to better know how to improve,
from user to contributor.

On Tue, 05 Sep 2023 at 12:00, Katherine Cox-Buday  
wrote:

> 1. A list of the issues
> 2. How we'll measure that they're issues
> 3. How we'll measure improvement against the issues
> 4. How we'll address the issues
>
> So often in my long career I've worked with organizations/people that 
> really want to skip to (5): implement something.
>
> Implement a vertically-integrated solution to gather feedback against 
> reality: yes. Jump straight to the "final solution" with all the details 
> managed: no.

Since I am French and it is easier for me to comment about my
disagreements than the converse. ;-)

In my career, I have seen the converse: spending plenty of time cooking
all the details of the plan and then being bitten by implementation
“details” that were impossible to predict beforehand.

Instead, I often see the incremental improvements more productive.
Especially when people are volunteers for their contributions and so
their motivation is variable and non-fungible.

I think we have

 #1. a list of issues; some points discussed in this thread
 could be reported as bugs.
 #4. an hope for addressing some of them using a plan (scripts, fix guix
 edit, etc.)

As we discussed earlier, the ’measures’ are the difficult part and there
is too many bias that it’s almost impossible to measure.  At best, the
number of contributors (#2) and some stats from some survey (#3) would
provide some indicators.

Maybe I misread, I think we have a consensus about the issues and
about the concrete actionable next steps, no?

 a. Prepare a survey
 b. Report bugs about “guix style” and “guix edit” (and I am probably
missing other reported in the thread :-))
 c. Look to Build Coordinator and QA [A,B] (ask Chris?) and try to
extract what this CI does.

Well, from what my opinion is worth here.

A: https://git.savannah.gnu.org/cgit/guix/build-coordinator.git
B: https://git.savannah.gnu.org/cgit/guix/qa-frontpage.git/


[...]

> So are we unintentionally filtering out contributions from people with 
> compromised executive functioning?

For all the rest, I mostly agree with your words.

Cheers,
simon

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

[Simon Tournier]

Hi,

On Wed, 06 Sep 2023 at 00:11, wolf  wrote:

> But I guess this was supposed to be taken as "run make check' and make sure
> nothing new is broken".  Is there a command for that?

Yes taken like that. :-)

And nothing I am aware.  I agree that the situation with “make check” is
imperfect.

Cheers,
simon

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

[Development of GNU Guix and the GNU System distribution.]

"("  writes:

> Liliana Marie Prikler  writes:
>> Uhm, we have snippets?
>
> Well, those are exclusive to Emacs :)  And without regard to /that/
> issue, I do think that there's a problem if the commit format is so
> complex that it's not trivial for anyone new to the project to write
> them out manually.

Even with the snippets, vc's functionality, and magit, not all cases are
covered. Plus you have ti figure out how to use those tools for this, if
you even know they can do it in the first place. It's a lot.

On top of that, the documentation is lacking. The Guix manual refers you
to the GNU documentation, which doesn't really cover our specific
uses. I, like everyone else from what I can tell, just read existing log
entries to try and figure out what to put in there.

For the record, I don't really object to the header line format[1], it's
the stuff under the commit message proper that gets me. All the

‘* foo/bar.scm new-package (inputs): add input’

stuff. I literally can never remember this format, no matter how many
times I do it. I'm reasonably sure square brackes go in there some
where. It can take me quite a while to put together all that stuff, even
with magit's help.

-bjc

[1] I would like to see the ‘prefix:’ prefixes documented somewhere. If
I'm not messing with packages and can just type ‘gnu:’, I have no idea
what to put in, and often even git logs don't help, so I just wing it.

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

[Simon Tournier]

Hi,

On Tue, 05 Sep 2023 at 11:01, Katherine Cox-Buday  
wrote:

>> Well, somehow, I consider the commit message format similarly as coding
>> style.  We can discuss which one is better than the other when at the
>> end it only reflects some artificial preferences and for the sake of any
>> project one needs to be arbitrarily picked.  Why not ChangeLog?
>
> The distinction I draw is that I can usually run a linter against a
> coding style.
>
> I don't care very much what the standard for commit messages is other
> than if it has an expectation of structure, I be able to run a tool to
> tell me if it's wrong.
>
> In other words, the overhead isn't "I don't like this standard", it's "I
> can't find a way to reliably adhere to the standard".

Well, I am not sure to fully understand what you have in mind with the
term “standard“.  To me, coding style or similarly commit message format
are about standard or norm, meaning they respect a set of rules.

The question is then: is it possible to explicitly write down all the
rules?  Are all the rules all well-defined or are some ambiguous?  etc.

For some norm or standard, it is possible to have a checker because all
the rules are explicitly well-defined.  For many norms/standards, we do
not have any checker.

The current norm/standard for replying to these Guix mailing lists is
bottom-posting.  We do not have a way to reliably adhere to this
norm/standard and we are not commenting or discussing more about it.
Because this norm is easy to internalize.

Now, I have read the thread and I hear the comments about the commit
message format as ChangeLog.  To be honest, I am somehow surprised.  If
after being enough annoyed by something that then one clones the Guix
repository, finds how to improve and last drops all because writing the
commit message is too “complex” or because one does not know if the
commit message correctly adhere to the standard… Sorry, I do not buy.

And I do not buy either an issue when resuming after an interruption
because writing commit message can be done from the diff.  More than
often, I tweak stuff, then commit with the oneline subject ’DRAFT foo’,
continue to tweak, commit ’DRAFT bar’.  Days or weeks (or months) later,
I resume my work and run “git rebase” for polishing the commit ’DRAFT
foo’ and preparing it for submission.

Again I hear all the comments and I am trying hard to understand.  From
my point of view and from where I stand, my understanding is that the
core point of commit message format is about 1. discipline – the quality
of being able to behave and work in a controlled way which involves
obeying particular rules or standards – and 2. confidence – the willing
to send the perfect message on the first try.  And there is no tool for
fixing these both issues.

Example of a imperfect message:
a957171bc41e98e29674f99cf3dd2940ff45a0d3.  Typo! :-)

--8<---cut here---start->8---
Author: Simon Tournier 

gnu: ocaml-mdx: Fix tests.

* gnu/packages/ocaml.scm (ocaml-mdx)[arguments]: Substitue obsolete 'egrep' by
'grep -E'.

Signed-off-by: Julien Lepiller 
--8<---cut here---end--->8---

Oops, that’s npt perfect although I did my best (proofread and
spellchecker), the patch was in the tracker for some time and I am sure
Julien carefully checked.


Yeah, commit messages are boring to write.  However, when investigating
and trying to understand some changes, it appears to me far more useful
this:

--8<---cut here---start->8---
ec0a2fc87bd651ebc8f253f6369ba4485912d9b2

upstream: 'update-package-source' edits input fields.

Previously, 'guix refresh r-ggplot2 -u' and similar commands would print
of list of input changes that would have to be made manually.  With this
change, 'guix refresh -u' takes care of updating input fields
automatically.

* guix/upstream.scm (update-package-inputs): New procedure.
(update-package-source): Call it when 'upstream-source-inputs' returns
true.
* guix/scripts/refresh.scm (update-package): Remove iteration over the
result of 'changed-inputs'.
* guix/import/test.scm (available-updates): Add support for input
lists.
* tests/guix-refresh.sh (GUIX_TEST_UPDATER_TARGETS): Add input list for
"the-test-package".
Make sure 'guix refresh -u' updates 'inputs' accordingly.
* doc/guix.texi (Invoking guix refresh): Mention it.
--8<---cut here---end--->8---

Where the diff looks like:

5 files changed, 72 insertions(+), 45 deletions(-)
doc/guix.texi|  5 +++--
guix/import/test.scm | 13 ++-
guix/scripts/refresh.scm | 36 ---
guix/upstream.scm| 56 

tests/guix-refresh.sh|  7 --

compared to top-notch project as Julia language:

--8<---cut here---start->8---
sysimg: Allow loading a system