How can we decrease the cognitive overhead for contributors?

How can we decrease the cognitive overhead for contributors?

[Katherine Cox-Buday]

Summary: for people who don't contribute to Guix a lot, each 
contribution has
very high cognitive overhead. Can we work to reduce that?

Hey all,

Contributing to Guix is currently pretty difficult for me. I'm a Mom with a
full-time job, and anything outside of my job that requires a lot of 
executive
functioning (e.g. lots of manual, detailed, steps) is very difficult for 
me to
get correct. That last part is what I wanted to discuss, because that's 
the part
that prevents me from contributing more than I do, and I think there are
probably others whom are impacted by this.

When I have some time to contribute, I usually stall out at the "submit 
this for
review" because of the amount of cognitive overhead required. I've written a
script for myself that tries to perform all the steps including running 
the git
command to submit the patch, and this has helped me, but that this is 
necessary
for me to do might be something that, if addressed, could help others.

Here are some examples of things that cause issues for me. This is not a 
list of
grievances; it's my way of attempting to demonstrate the "shape" of the 
issue:

     I signed up on Savannah with the intention of applying to be a 
committer.
     Savannah closed my account one or two days later due to inactivity.

     I can't ever seem to get the GNU style commit messages correct. 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.

     I don't use the email-based patch workflow day-to-day, so this is 
another
     area where I spend a lot of time trying to make sure I'm doing things
     correctly.

     My script runs `guix style` and `guix lint`, but its suggestions aren't
     always correct. I suspect I've submitted some patches with nonsensical
     changes due to implicitly trusting these tools.

     Maybe 
https://lists.gnu.org/archive/html/guile-devel/2023-02/msg00030.html
     addresses this, but manually managing Guile imports is laborious. As a
     fledgling schemer, I often forget which imports I needed just for
     development.

I think I would summarize the core of these examples as:

     "At every step of the contribution process, I must manually check that
     multiple things are correct. With limited available executive 
functioning,
     and no automation, this is very difficult to do correctly, and an 
easy place
     for contributors to stop."

I think that if I were working on Guix more frequently, I would build 
habits I
didn't have to think about, and these wouldn't be the large issues they are
for me. But because of the nature of a project like Guix, we want 
contributions
from people of all kinds of backgrounds, not just people who have the 
privilege
to work on Guix a lot.

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?

Here are some things I've considered:

* Contributing to Guix is not for you

     I would be really sad if someone ever said this, but I guess it's a
     possibility. Maybe someone like me just can't be a contributor to 
Guix until
     I have the bandwidth to manage all the details. I would 
preemptively argue
     that diversity of thought and experiences usually leads to better 
things.

* It's OK to make lots of mistakes

     The people who have reviewed my code have been generous both with 
their time
     and fixing my mistakes and then applying. Maybe this model is OK? I 
still
     feel guilty every time a reviewer has to correct an oversight I've 
made. I
     also want to become a committer, but I don't know how that would 
work if
     I'm regularly making mistakes. Obviously people would still be 
reviewing my
     commits, but presumably a committer should not regularly be making
     mistakes.

* We could support a managed web-based workflow

     I think this has been brought up a lot of times, and I don't have a 
clear
     idea of what's been said. But I think a lot of developers these 
days are
     more familiar with this style, and we could still maintain 
self-sovereignty
     if we hosted something.

* Encourage upstream communities like "Guix 'R Us" 
(https://sr.ht/~whereiseveryone/guixrus/)

     Maybe Guix proper continues as is and we foster various upstream 
communities
     that utilize different styles and batch their contributions?

What do you all think? Does this affect anyone else?

[*] But if you have workflow suggestions, I'm all ears!

--
Katherine

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

[Felix Lechner via Development of GNU Guix and the GNU System distribution.]

Hi Katherine,

On Wed, Aug 23, 2023 at 9:27 AM Katherine Cox-Buday
<cox.katherine.e@gmail.com> wrote:
>
> I'm a Mom

Congratulations, and thanks for dedicating your life to someone else!

>      Savannah closed my account one or two days later due to inactivity.

That happened to me too, although it took a couple of weeks.

>      I can't ever seem to get the GNU style commit messages correct.

Neither can I. The style apparently helps with automated maintenance
of the changelog, but I do not understand why a changelog is useful
for a rolling release model.

No one uses Guix releases other than to install. Even then, we
encourage folks to run 'guix pull' at their earliest opportunity.

>      I don't use the email-based patch workflow day-to-day

Yeah, I can deal with small inline patches, but Guix requires changes
to be split into many tiny commits.

Such a series is then submitted with one message per commit. Then
people argue in between and submit multiple versions of the commit
series to the same bug. I think it requires a lot of practice to work
through that.

Some email clients, such as aerc, may help. I don't think people are
opposed to better tooling. We just don't have it yet. Mumi could be
part of the solution.

>      My script runs `guix style`

According to an authoritative source, hitting TAB on a marked region
in Emacs is actually the preferred way to format submissions.

>      "At every step of the contribution process, I must manually check that
>      multiple things are correct. With limited available executive
> functioning,
>      and no automation, this is very difficult to do correctly, and an
> easy place
>      for contributors to stop."

There is an easy medicine: Lose your worries, and don't be afraid!

Just send in what you have. For example, I ask my reviewers to adjust
commit messages to their liking.

> 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?

Your broader perspective will probably generate a lot of discussion in
which people offer many valuable viewpoints, but it will yield no
resolution.

There is no central authority in Guix, yet people are afraid to step
out of line. In the end, everyone just conforms out of habit.

> * Contributing to Guix is not for you

Guix has a steep learning curve that is not necessarily limited to
contributions. The Guile syntax features, which are so popular in
Guix, can be difficult to understand even for people who know Scheme.
The file system layout, which is brilliant, also takes time to
understand.

> * It's OK to make lots of mistakes

That headline should be on all of Guix's web pages. Peopl focuss on
wayy to meny details in al technicl Forums.

> * We could support a managed web-based workflow

Mumi needs more love. Or, maybe we can co-opt Codeberg or Sourcehut.

> * Encourage upstream communities like "Guix 'R Us"

Every contributor should have their own channels for packages [1] and
for Guix. [2] Testing patches before they are submitted would vastly
improve the code quality in Guix.

Just fork my repos on Codeberg and use the 'prebuilt' branches. (Also,
please tell me when to advance them to more recent commits.) Here is
how you use them via Guix Home. [3]

> What do you all think? Does this affect anyone else?

For now, it's just you and I—unless others speak up. Thanks for your
helpful comments!

Kind regards
Felix

[1] https://codeberg.org/lechner/juix
[2] https://codeberg.org/lechner/guix
[3] https://codeberg.org/lechner/home-config/src/branch/history/service/channels.scm

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

[Andreas Enge]

Hello,

Am Wed, Aug 23, 2023 at 10:27:31AM -0700 schrieb Felix Lechner via Development of GNU Guix and the GNU System distribution.:
> >      I can't ever seem to get the GNU style commit messages correct.
> Neither can I. The style apparently helps with automated maintenance
> of the changelog, but I do not understand why a changelog is useful
> for a rolling release model.

personally, I find them super helpful to grep through commit messages
to find changes, like when a file was touched for the last time (now
I think that git wizards will have a better solution; but you get the
idea). Or when a package was added. Or updated to a specific version.
I have ended up adopting the style for all of my other coding projects
as well because I find it so useful.

For simple updates, there is etc/committer.scm. I use it for package
updates. It would be nice if it could handle more cases, such as removing
patches.

> >      I don't use the email-based patch workflow day-to-day
> Yeah, I can deal with small inline patches, but Guix requires changes
> to be split into many tiny commits.

This is explained here:
   https://guix.gnu.org/de/manual/devel/en/html_node/Sending-a-Patch-Series.html

I also cannot remember what to do when there is more than one patch,
so I follow this approach every time. (Well, this is a white lie; mostly
I propose single patches or work in a branch...)

All in all, I think better tooling will be welcome (but is not a joy to
write).

Am Wed, Aug 23, 2023 at 10:25:58AM -0600 schrieb Katherine Cox-Buday:
> * Contributing to Guix is not for you
> * It's OK to make lots of mistakes

Definitely "no" to the first one, and "yes" to the second one!
I think that even when one only contributes from time to time, but
regularly, habits will form and mistakes disappear.

> * We could support a managed web-based workflow

I am all for it if it supplements the email based workflow (every
time I need to do a modern style pull request type action, I am
completely out of my depths and lost in the web interfaces...).
But someone would have to write and maintain them...

> * Encourage upstream communities like "Guix 'R Us"

Why not, but they also require management (adjusting the schedules
of several busy people, for instance).

Andreas

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

[Liliana Marie Prikler]

Hi Katherine,

Am Mittwoch, dem 23.08.2023 um 10:25 -0600 schrieb Katherine Cox-Buday:
> Summary: for people who don't contribute to Guix a lot, each 
> contribution has very high cognitive overhead. Can we work to reduce
> that?
> 
> Hey all,
> 
> Contributing to Guix is currently pretty difficult for me. I'm a Mom
> with a full-time job, and anything outside of my job that requires a
> lot of executive functioning (e.g. lots of manual, detailed, steps)
> is very difficult for me to get correct. That last part is what I
> wanted to discuss, because that's the part that prevents me from
> contributing more than I do, and I think there are probably others
> whom are impacted by this.
> 
> When I have some time to contribute, I usually stall out at the
> "submit this for review" because of the amount of cognitive overhead
> required. I've written a script for myself that tries to perform all
> the steps including running the git command to submit the patch, and
> this has helped me, but that this is necessary for me to do might be
> something that, if addressed, could help others.
The thing is, most people automate this process in some way or another.
This is a benefit of Guix' contribution model that you can't enjoy e.g.
with Github pull requests, where you basically have to sign up to a
(proprietary) service and most of the time follow whatever conditions
have been laid out by the maintainers or get your patch desk rejected.
In Guix, it's mostly humans on both ends.

> Here are some examples of things that cause issues for me. This is
> not a list of grievances; it's my way of attempting to demonstrate
> the "shape" of the issue:
> 
>      I signed up on Savannah with the intention of applying to be a
>      committer.   Savannah closed my account one or two days later
>      due to inactivity.
I can not comment on the workings of Savannah, but as a committer
myself, I would advise against applying if you have other things in
your life that you consider more important.  While it's not the same as
being responsible for another human, being responsible for a set of
packages can be an emotional burden

>      I can't ever seem to get the GNU style commit messages correct. 
>      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.
It is the task of the committer to actually sign off meaningful commit
messages.  As long as you make an effort to keep with the general
style, little mistakes here and there are forgiven and most often
automatically corrected.

>      I don't use the email-based patch workflow day-to-day, so this
>      is another area where I spend a lot of time trying to make sure
>      I'm doing things correctly.
> 
>      My script runs `guix style` and `guix lint`, but its suggestions
> aren't always correct. I suspect I've submitted some patches
>      with nonsensical changes due to implicitly trusting these tools.
We are quite aware that those tools aren't perfect and at least some of
us recognize their "handwriting" quite easily.

>      Maybe 
> https://lists.gnu.org/archive/html/guile-devel/2023-02/msg00030.html
>      addresses this, but manually managing Guile imports is
>      laborious. As a fledgling schemer, I often forget which imports
>      I needed just for development.
Guix actively fights these import troubles by trying to give you useful
hints as to which modules to include.  Granted, this isn't too
different from your C compiler telling you that you forgot a semicolon,
but it's better than the undefined variable warnings in other contexts.

> I think I would summarize the core of these examples as:
> 
>      "At every step of the contribution process, I must manually 
>      check that multiple things are correct. With limited available
>      executive functioning, and no automation, this is very difficult
> to do correctly, and an easy place for contributors to stop."
> 
> I think that if I were working on Guix more frequently, I would build
> habits I didn't have to think about, and these wouldn't be the large
> issues they are for me. But because of the nature of a project like
> Guix, we want contributions from people of all kinds of backgrounds,
> not just people who have the privilege to work on Guix a lot.
> 
> 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?
> 
> Here are some things I've considered:
> 
> * Contributing to Guix is not for you
> 
>      I would be really sad if someone ever said this, but I guess
>      it's a possibility. Maybe someone like me just can't be a
>      contributor to Guix until I have the bandwidth to manage all the
>      details. I would preemptively argue that diversity of thought
>      and experiences usually leads to better things.
I think you have to separate contributing and being a committer here. 
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.

> * It's OK to make lots of mistakes
> 
>      The people who have reviewed my code have been generous both  
>      with their time and fixing my mistakes and then applying. Maybe
> this model is OK? I still feel guilty every time a reviewer has
>      to correct an oversight I've made. I also want to become a 
>      committer, but I don't know how that would work if I'm regularly
>      making mistakes. Obviously people would still be reviewing my
>      commits, but presumably a committer should not regularly be
>      making mistakes.
To be invited into the club of committers, you have to have existing
committers sign off on your ability to sign off commits (details in the
manual).  As you might have guessed, "I make a lot of mistakes" is not
a very convincing argument in your favour here :)

My question to you is why you feel that you want to be a committer when
you have little time to dedicate to learning our rituals and presumably
even less time to do "productive work"?  

> * We could support a managed web-based workflow
> 
>      I think this has been brought up a lot of times, and I don't
>      have a clear idea of what's been said. But I think a lot of 
>      developers these days are more familiar with this style, and we
>      could still maintain self-sovereignty if we hosted something.
Just because it's brought up a lot of times doesn't mean it's a good
idea.  There is a lot of good things that can be done for our web-based
front ends; improving the search results on issues.guix.gnu.org would
be one of them.  However, I have little hopes for a web based means to
submit contributions.  I think email should be a format that's
understood by folks who know how to operate a web browser.

> * Encourage upstream communities like "Guix 'R Us" 
> (https://sr.ht/~whereiseveryone/guixrus/)
> 
>      Maybe Guix proper continues as is and we foster various upstream
>      communities that utilize different styles and batch their 
>      contributions?
It is not the responsibility of Guix to endorse third party channels
and communities, but rather to provide the basic means to facilitate
them.  These communities have their own goals that may or may not
intersect with ours and it is up to them to decide whether contributing
any particular package or series to Guix proper is a worthwhile idea or
not.  In practice, some of them appear to be seen experimentation
grounds to see "what sticks" and contribute packages once they've
matured a bit.

Cheers

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

[Ricardo Wurmus]

Katherine Cox-Buday <cox.katherine.e@gmail.com> writes:

> * We could support a managed web-based workflow

I started packaging some requirements of sourcehut.  I’d be happy to
retire mumi + debbugs and use whatever sourcehut offers if we can host
it.

I haven’t ever used sourcehut things, but I hear they are good for
web-based and email-based workflows alike.

-- 
Ricardo

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

[Jack Hill]

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

Katherine,

Thanks for starting this thread!

I'd like to offer my perspective on mistake making (of course it's OK, but 
definitely less fun to repeatedly make the same mistakes over again rather 
than new, interesting ones):

My personal experience is the initial steps to submitting a contribution 
don't bother me too much, but when I do make the inevitable mistake (why 
is it so much easier to proofread incoming mail than outgoing‽) making a 
correction seems very much more onerous than other systems.

Unfortunately, I don't have any great ideas for solutions, but I am 
hopeful because when we do have a solution, Guix makes it easy to convey 
it to the people who'll use it.

Best,
Jack

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

[Csepp]

Katherine Cox-Buday <cox.katherine.e@gmail.com> writes:

> Summary: for people who don't contribute to Guix a lot, each
> contribution has
> very high cognitive overhead. Can we work to reduce that?
>
> Hey all,
>
> Contributing to Guix is currently pretty difficult for me. I'm a Mom with a
> full-time job, and anything outside of my job that requires a lot of
> executive
> functioning (e.g. lots of manual, detailed, steps) is very difficult
> for me to
> get correct. That last part is what I wanted to discuss, because
> that's the part
> that prevents me from contributing more than I do, and I think there are
> probably others whom are impacted by this.
>
> When I have some time to contribute, I usually stall out at the
> "submit this for
> review" because of the amount of cognitive overhead required. I've written a
> script for myself that tries to perform all the steps including
> running the git
> command to submit the patch, and this has helped me, but that this is
> necessary
> for me to do might be something that, if addressed, could help others.
>
> Here are some examples of things that cause issues for me. This is not
> a list of
> grievances; it's my way of attempting to demonstrate the "shape" of
> the issue:
>
>     I signed up on Savannah with the intention of applying to be a
> committer.
>     Savannah closed my account one or two days later due to inactivity.
>
>     I can't ever seem to get the GNU style commit messages correct. 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.
>
>     I don't use the email-based patch workflow day-to-day, so this is
> another
>     area where I spend a lot of time trying to make sure I'm doing things
>     correctly.
>
>     My script runs `guix style` and `guix lint`, but its suggestions aren't
>     always correct. I suspect I've submitted some patches with nonsensical
>     changes due to implicitly trusting these tools.
>
>     Maybe
> https://lists.gnu.org/archive/html/guile-devel/2023-02/msg00030.html
>     addresses this, but manually managing Guile imports is laborious. As a
>     fledgling schemer, I often forget which imports I needed just for
>     development.

This definitely falls into the IDE tooling issue that I complained about
a bunch of times.  There seems to be a reality distortion field around
Lisp that makes some users believe that s-expressions automatically lead
to a good IDE experience.  And yet, Java IDEs have had automatic import
management for at least 15 years (around the time I first used Eclipse),
but Guile still doesn't have anything of the sort.
It looks like the only way to move forward is for people to share these
helper scripts they've been using and forging them into a consistent
developer environment, maybe based on Guile Studio.  Hopefully I can
make some contributions towards such a project.

> I think I would summarize the core of these examples as:
>
>     "At every step of the contribution process, I must manually check that
>     multiple things are correct. With limited available executive
> functioning,
>     and no automation, this is very difficult to do correctly, and an
> easy place
>     for contributors to stop."
>
> I think that if I were working on Guix more frequently, I would build
> habits I
> didn't have to think about, and these wouldn't be the large issues they are
> for me. But because of the nature of a project like Guix, we want
> contributions
> from people of all kinds of backgrounds, not just people who have the
> privilege
> to work on Guix a lot.
>
> 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?
>
> Here are some things I've considered:
>
> * Contributing to Guix is not for you
>
>     I would be really sad if someone ever said this, but I guess it's a
>     possibility. Maybe someone like me just can't be a contributor to
> Guix until
>     I have the bandwidth to manage all the details. I would
> preemptively argue
>     that diversity of thought and experiences usually leads to better
> things.

I really hope we can lower the barrier to entry without sacrificing code
quality precisely because of this.  Lots of important use cases that
Guix could serve are ignored because the people who need them are not
represented in our community and/or they can't contribute and no one is
able/willing to write code for them.

> * It's OK to make lots of mistakes
>
>     The people who have reviewed my code have been generous both with
> their time
>     and fixing my mistakes and then applying. Maybe this model is OK?
> I still
>     feel guilty every time a reviewer has to correct an oversight I've
> made. I
>     also want to become a committer, but I don't know how that would
> work if
>     I'm regularly making mistakes. Obviously people would still be
> reviewing my
>     commits, but presumably a committer should not regularly be making
>     mistakes.

In a sense I agree with this, but if mistakes are this easy to make,
then I think something is wrong with the project, not with the
contributor.  Instead of making people learn tightrope walking, maybe we
should be building actual bridges.
Guix actually fares pretty well in this regard compared to some other
projects I tried contributing to (*stares at Plan 9*), but there is
still a lot of knowledge that experienced developers take for granted
and don't actually document.  Writing new packages is mostly documented
well, but as soon as something breaks, you are thrown into the deep end,
having to dissect logs, bisect commit ranges, learn strace, gdb (which
still doesn't work well on Guix), learn how to compile packages with
debug info (and actually waste some more CPU time and IO on rebuilding a
package you already have), learn how to adapt docs from other distros,
etc, etc, etc.
I've been trying to document these at least for myself, but haven't yet
had time to put them together into something others could read.

By the way, that's another issue.  Using a TeX based document format for
the docs is, uuuh, maybe not the best idea.  Info is a pretty okayish
documentation reader, but it's a relatively big barrier to entry
compared to what you need to know to make a small edit to the Arch wiki.
This way mostly just experienced contributors write docs, not the
users who just want to document how they made some weird use case
possible.

> * We could support a managed web-based workflow
>
>     I think this has been brought up a lot of times, and I don't have
> a clear
>     idea of what's been said. But I think a lot of developers these
> days are
>     more familiar with this style, and we could still maintain
> self-sovereignty
>     if we hosted something.

I'm very much in favor of using Sourcehut, since there are people whose
actual main job is to improve Sourcehut.  There was also a project
(although it currently seems to be stalled) at Sourcehut that aimed to
sync pull requests on forges like GitLab with patches on Sourcehut, if
that was completed we could even have a Gitea instance for people who
aren't comfortable with the email workflow.

> * Encourage upstream communities like "Guix 'R Us"
>   (https://sr.ht/~whereiseveryone/guixrus/)
>
>     Maybe Guix proper continues as is and we foster various upstream
> communities
>     that utilize different styles and batch their contributions?
>
> What do you all think? Does this affect anyone else?
>
> [*] But if you have workflow suggestions, I'm all ears!

Personally I think these should at least be linked, even The Forbidden
Channel We Shall Not Name (but at least 50% of us are likely using).
It's better to direct users to a community that can help them when this
one can't.

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

[Ahmed Khanzada via Development of GNU Guix and the GNU System distribution.]

My wife and I are currently trying, so I hope to be a busy parent soon too!

What you have mentioned is a big problem with contributing to anything
GNU. It's hard for people that are familiar with the frictionless
approach of GitHub pull requests to adapt to the decentralized mailing
list approach of contributing code to GNU, myself included. The Emacs
mailing list is having a big convo about this right now.

The debate comes down to: the people contributing the most code already
have a very familiar workflow that they have automated (all probably within
Emacs). Why should they change their contribution model for those who
don't contribute much currently, and may never do so? (Not implying this
is you! Just recounting the debate).

But you're not asking that; you just want to lower the cognitive overhead.

The suggestion of SourceHut made by someone else might be a good one, I
know that they are trying to create a web based portal to the mailing
list workflow.

Another idea I've been playing with in my own personal time is to setup
a distribution of GNU in a Docker container. It will come with all the
tools necessary to hack on GNU and interact with the mailing list:

- Built on Guix
- Tricked out Emacs with Gnus client
- All relevant GNU git repos ready to compile and hack on
- Notmuch tagging, OfflineIMAP syncing
- Optionally signs you up for relevant mailing lists
- Comes with whatever Emacs Lisp / Guile automation the big contributors
  use to automate their workflows (does anyone want to share?)

I can't do much about the brutal learning curve of Emacs, Guix, and GNU,
but I certainly can just package it so it's all ready to go with fancy
scripts for the most common workflows.

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

[(]

Katherine Cox-Buday <cox.katherine.e@gmail.com> writes:
>     I signed up on Savannah with the intention of applying to be a committer.
>     Savannah closed my account one or two days later due to inactivity.

That happened to me, too :|

>     I can't ever seem to get the GNU style commit messages correct. 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.

You do get used to it, but the format is very... verbose, and personally
I think we should abandon it; the signal:noise ratio isn't good, and I
don't think the automatic generation of ChangeLog files is a great idea
anyway, since so many changes to Guix are so trivial.  I think we should
just use the news file more often instead.

>     My script runs `guix style` and `guix lint`, but its suggestions aren't
>     always correct. I suspect I've submitted some patches with nonsensical
>     changes due to implicitly trusting these tools.

Yes, I'd personally advise against the use of `guix style` for now.
`guix lint` is fine, though.

> * Contributing to Guix is not for you

I'd hope nobody says this!  It's definitely not true, and rather
defeatist.

> * It's OK to make lots of mistakes

Yes. :)

> * We could support a managed web-based workflow

The problem with this is that it would not be possible without changing
the git hosting entirely to something like Gitea.  I'm personally a fan
of the email-based workflow; what, specifically, is it that bothers you
about it?  If it's:

- Setting it up: Yes, this is annoying.  Sadly, our mighty oligarchal
  masters have taken it upon themselves to make it as annoying as
  possible to use email from anywhere but their web or mobile clients.
- Sending the emails: This isn't that bad once you get used to it;
  sadly most Git clients (magit sadly included) don't support send-email
  well or at all.  But on the command line, all you need to do is:

  # for a single commit
  $ git send-email --to=guix-patches@gnu.org -1 --base=master -a
  # for several commits
  $ git send-email --to=guix-patches@gnu.org -$N_COMMITS --base=master --cover-letter -a

  Or, if sending an amended series:
  $ git send-email --to=$BUG_NUM@debbugs.gnu.org -$N_COMMITS --base=master -a -v$VERSION

- Switching between branches: The best way to handle this is with
  subtrees; see `git subtree --help`.
- Applying patches: This is a bit annoying.  Most email clients won't
  let you set up commands to pipe mailboxes to, unlike aerc.  Perhaps we
  could have a `mumi apply` command to fetch a patch series from debbugs
  and apply it to the checkout.

  -- (

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

[Wilko Meyer]

Hi Katherine,

Katherine Cox-Buday <cox.katherine.e@gmail.com> writes:

> That last part is what I wanted to discuss, because
> that's the part
> that prevents me from contributing more than I do, and I think there are
> probably others whom are impacted by this.

Yes, I'd actually love contributing more to Guix; but even with
some familiariaty with a patch-based workflow; Guix, from my
perspective, resides on a higher end of effort in terms of overhead/time
spend until a patch series is ready.

I tend to have plenty of half-way finished/not thoroughly tested stuff
on my own (local) guix channel, but wouldn't want to submit "works for
me"-ish patches soliciting the attention and time of reviewers that
could probably be utilized better. I don't have a particular solution
for this, but I think it's important to make contributions easier, as
requiring a certain time privilege as it does now doesn't seem to be
feasible.

Another thing to consider may be the time until a patch is being
discussed/merged. I don't have any metrics for Guix, but from my
experience delayed responses are usually one of the major issues on why
first-time contributors don't become recurring contributors in other
projects. Nix seems to address this here[1] as well. Having a tag for
first time contributions, which is what nixpkgs seem to have, in
debbugs/on issues.guix.gnu.org could probably be beneficial to address
this issue for Guix as well.

>     I signed up on Savannah with the intention of applying to be a
> committer.
>     Savannah closed my account one or two days later due to inactivity.

Happened to me as well, never tried signing up again afterwards.

>     I don't use the email-based patch workflow day-to-day, so this is
> another
>     area where I spend a lot of time trying to make sure I'm doing things
>     correctly.

I feel like the advantages of a email-based workflow nowadays is more on
the maintainer side of things (as managing large projects is easier
using email/threaded discussions instead of the comment-based mode of
discussions the MR/PR web based processes offer), as for a vast majority
of potential contributors it seem to rather complicate things as most
people seem to be rather used with said web-based workflow.

> * It's OK to make lots of mistakes

IMHO this is a pretty important point.

> * We could support a managed web-based workflow

This would, in addition to the email-based workflow, make at least that
part of the contribution process more accessible for a larger crowd. As
others have already mentioned in in this thread: sourcehut seems to be
working into that direction.

[1]: https://discourse.nixos.org/t/showing-first-time-contributors-some-love/29105

Best Regards,

Wilko Meyer

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

[Simon Tournier]

Hi,

At some point, I sympathize.

On Wed, 23 Aug 2023 at 10:25, Katherine Cox-Buday <cox.katherine.e@gmail.com> wrote:

>   I don't use the email-based patch workflow day-to-day, so this is
> another area where I spend a lot of time trying to make sure I'm doing
> things correctly.

I agree that Debbugs is not handy at all for submitting patches.  Send
the cover letter, wait, refresh email, wait, refresh email, loop until
an issue number is assigned, and then send the series.

Well, Debbugs is an issue tracking system and not a patch tracking
system, from my understanding.  And thus this annoyance is not about
email-based workflow.  It is just about using Debbugs for tracking
patches, IMHO.


> 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?

Reduce friction for making contributions?  Yes, we all want that, I
guess.  The question is how?  What is the right balance between the
change of habits and the satisfaction of people used to these habits?

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.

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.


> * It's OK to make lots of mistakes
>
>   The people who have reviewed my code have been generous both with
> their time and fixing my mistakes and then applying. Maybe this model
> is OK? I still feel guilty every time a reviewer has to correct an
> oversight I've made. I also want to become a committer, but I don't
> know how that would work if I'm regularly making mistakes. Obviously
> people would still be reviewing my commits, but presumably a committer
> should not regularly be making mistakes.

Considering this range of contributions above, I do not see this “make
lots of mistakes”.  Or, let say all the mistakes are not equivalent.

I do not think it is all good or all bad.  From my point of view, all
the contributions are a gift.  I appreciate equally the gift of my
sister who knits a tiny half-done scarf and the gift of my father who
crafts a complete wood-chair.  I empathise both with the busy life of my
sister and with the retired full-of-free-time life of my father.  And I
use or reuse the gifts as I am able to.

Well, no pressure.  Software is done by craftperson who internalizes one
step, then another, and it builds the habits above.  I guess.

I am not avoiding tools.  I think tools as guix style and guix lint
deserve improvements.  Therefore, let open bug report when you notice
wrong or not the expected behaviour.  For example, Vagrant suggested
nice improvements for guix lint and spellchecker.

And QA, partially based on these tools, is also improving a lot.  It
helps to detect mistakes.


> * We could support a managed web-based workflow

Here, I am very doubtful that it would help.

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.

Another example is Software Heritage (SWH).  Their web-based workflow is
a Gitlab instance [1].  As an occasional person who deal with the SWH
archive, I am never able to find my way and I just roam on #swh-devel
IRC channel asking for help.

Another example: the channel guix-science [2] based on GitHub.  Well, I
am able to count using one of my hands the number of PRs. ;-) (And I do
not speak about other channels as nonguix)
 
Well, reading the item above about mistake and the item below about
"Guix 'R Us", and maybe I am wrong, somehow I feel that one “cognitive
overhead” is the willing to submit a perfect patch.  Again, maybe I am
wrong, somehow I feel that one part of the issue is a lack of
self-confidence.  Do not take me wrong, I am speaking about submitting a
patch by occasional contributor and not about the personality of person
that I do not personally know. :-)

This “that’s not perfect so I postpone the submission” is something I
often hear by people attending to Café Guix [3].  Hum, I do not know
what we could do differently for reducing this barrier.

The idea of the team Mentor is in this direction but it does not seem
working… :-(

1: https://gitlab.softwareheritage.org/explore
2: https://github.com/guix-science/guix-science
3: https://hpc.guix.info/events/2022/caf%C3%A9-guix/


> * Encourage upstream communities like "Guix 'R Us" 
> (https://sr.ht/~whereiseveryone/guixrus/)
>
>   Maybe Guix proper continues as is and we foster various upstream
> communities that utilize different styles and batch their
> contributions?

For sure, I think it’s a very good thing.  In the same direction, I also
find helpful the initiative by Guixers based on London to physically
meet.  We did similar a couple of times in Paris.  Demoing and showing
that nothing is perfect is helping in reducing some barrier.

During lockdown, we (Jérémy and I) did some remote-pair programming [4].
I think this kind of thing could also be a solution because being two
with an appointment and a fixed slot of time, etc. all that keep the
motivation up and help in reducing some barrier.

4: https://10years.guix.gnu.org/video/remote-pair-programming/

For sure, I think that part of the solution is by finding the way to
collaborate.  Somehow, what would be your expectations for contributing
more?  Or for easing your contributions? :-)

Cheers,
simon

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

[Ekaitz Zarraga]

Hi,

> This definitely falls into the IDE tooling issue that I complained about
> a bunch of times. There seems to be a reality distortion field around
> Lisp that makes some users believe that s-expressions automatically lead
> to a good IDE experience. And yet, Java IDEs have had automatic import
> management for at least 15 years (around the time I first used Eclipse),
> but Guile still doesn't have anything of the sort.
> It looks like the only way to move forward is for people to share these
> helper scripts they've been using and forging them into a consistent
> developer environment, maybe based on Guile Studio. Hopefully I can
> make some contributions towards such a project.

I fully agree with this. I'd also add that everything seems to be emacs
focused and not being an emacs user is kind of an extra barrier for people.
(I'm not an emacs user)

>                                       Lots of important use cases that
> Guix could serve are ignored because the people who need them are not
> represented in our community and/or they can't contribute and no one is
> able/willing to write code for them.

Yes, and even if you manage to write something yourself, many times you
get now answer to your patches because no one else is interested on what
you did. It's perfectly understandable but also discouraging.

Example: I wanted to push Zig support in guix a while ago. Made a build
system and got no answer. <https://issues.guix.gnu.org/60889#3>
The feeling here is that the code proposed is not good enough, but I don't
know how to improve it so I'm stuck. It would be great to feel comfortable
enough with the code to be sure that it can be merged, but I can't find
the resources to make it better. If it was clearer or if it was easier
both sides, maintainers and contributors, would be more effective and
happier.

> > * It's OK to make lots of mistakes
> > 
> > The people who have reviewed my code have been generous both with their
> > time and fixing my mistakes and then applying. Maybe this model is OK? I
> > still feel guilty every time a reviewer has to correct an oversight I've
> > made. I also want to become a committer, but I don't know how that would
> > work if I'm regularly making mistakes. Obviously people would still be
> > reviewing my commits, but presumably a committer should not regularly be
> > making mistakes.

Exactly my feeling. And I've been working with Guix for a while...

> In a sense I agree with this, but if mistakes are this easy to make,
> then I think something is wrong with the project, not with the
> contributor. Instead of making people learn tightrope walking, maybe we
> should be building actual bridges.
> Guix actually fares pretty well in this regard compared to some other
> projects I tried contributing to (stares at Plan 9), but there is
> still a lot of knowledge that experienced developers take for granted
> and don't actually document. Writing new packages is mostly documented
> well, but as soon as something breaks, you are thrown into the deep end,
> having to dissect logs, bisect commit ranges, learn strace, gdb (which
> still doesn't work well on Guix), learn how to compile packages with
> debug info (and actually waste some more CPU time and IO on rebuilding a
> package you already have), learn how to adapt docs from other distros,
> etc, etc, etc.
> I've been trying to document these at least for myself, but haven't yet
> had time to put them together into something others could read.

"As soon as *anything* breaks everything starts to fall apart" is a feeling
I also have a lot. Many things in my system are poorly configured because
I simply can't figure out how to fix. Default things work great, but when
something doesn't you are exposed to a great complexity, there's almost
no midpoint.

Specially, some services feel like nobody use them because they have almost
no options to be configured and there are no examples out there.

I have to say it got better in recent months. We are doing achievements in
this area, which is great.

> By the way, that's another issue. Using a TeX based document format for
> the docs is, uuuh, maybe not the best idea. Info is a pretty okayish
> documentation reader, but it's a relatively big barrier to entry
> compared to what you need to know to make a small edit to the Arch wiki.
> This way mostly just experienced contributors write docs, not the
> users who just want to document how they made some weird use case
> possible.

Again, I'd say this is because of emacs, again. It's not that bad, because you
can use the website, too, but collaboration in the manual is a little bit
daunting.

These are my five cents.

Cheers,
Ekaitz

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

[Attila Lendvai]

another +1 for the general sentiment of Katherine's message.


> I am all for it if it supplements the email based workflow (every
> time I need to do a modern style pull request type action, I am
> completely out of my depths and lost in the web interfaces...).


in my experience learning the quirks of the web based PR model, at least as a contributor, is much less effort than the constant friction of an email based workflow, let alone the learning curve of the emacs based tools.

i couldn't even find out which tools are used by those who are comfortable with the email based workflow. i looked around once, even in the manual, but maybe i should look again.

i'm pretty sure most maintainers have a setup where the emailed patches can be applied to a new branch with a single press of a button, otherwise it'd be hell of a time-waster.

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.


> But someone would have to write and maintain them...


there are some that have already been written. here's an ad-hoc list of references:

#github #gitlab #alternative
https://codeberg.org/
https://notabug.org/
https://sourcehut.org/
https://sr.ht/projects
https://builds.sr.ht/
https://git.lepiller.eu/gitile
codeberg.org is gitea and sr.ht is sourcehut

-- 
• attila lendvai
• PGP: 963F 5D5F 45C7 DFCD 0A39
--
“The condition upon which God hath given liberty to man is eternal vigilance; which condition if he break, servitude is at once the consequence of his crime and the punishment of his guilt.”
	— John Philpot Curran (1750–1817)

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

[Attila Lendvai]

> 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.


the ultimate goal is not just diversity, but high efficiency of the people who cooperate around Guix, which then translates into a better Guix.

if the "rituals" around Guix contribution were merely a steep initial learning curve, then one could argue that it's a kind of filter that helps with the signal to noise ratio. but i think it's also a constant hindrance, not just an initial learning curve.


> Just because it's brought up a lot of times doesn't mean it's a good
> idea. There is a lot of good things that can be done for our web-based
> front ends; improving the search results on issues.guix.gnu.org would
> be one of them. However, I have little hopes for a web based means to
> submit contributions. I think email should be a format that's
> understood by folks who know how to operate a web browser.


again, i would press the argument that it's not about being able to, but about how much effort/attention is wasted on administration (i.e. not on hacking). i often have the impression that it took comparable effort to submit a smaller to mid size patch than making it.

-- 
• attila lendvai
• PGP: 963F 5D5F 45C7 DFCD 0A39
--
“Virtually no idea is too ridiculous to be accepted, even by very intelligent and highly educated people, if it provides a way for them to feel special and important.”
	— Thomas Sowell (1930–)

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

[Andreas Enge]

Hello,

just a quick reply with what I do personally as one irrelevant data point :)

Am Fri, Aug 25, 2023 at 08:07:53AM +0000 schrieb Attila Lendvai:
> i couldn't even find out which tools are used by those who are comfortable with the email based workflow. i looked around once, even in the manual, but maybe i should look again.

No tools at all, I would say, which indeed may be a bit inefficient...
Or: terminal, mutt, vim, git
A bit of web for browsing the manuals (of Guix and Guile)
and issues.guix.gnu.org
But then I type much faster than I click.

> i'm pretty sure most maintainers have a setup where the emailed patches can be applied to a new branch with a single press of a button, otherwise it'd be hell of a time-waster.

mutt
save message to /tmp/x
git am /tmp/x
or something like this

or:
git clone https://git.guix-patches.cbaines.net/guix-patches/
git checkout issue-xxxxx
git format-patch ...
then in the development checkout of Guix:
git am ...; make; ./pre-inst-env guix build

> 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.

For this, I either go to issues.guix.gnu.org to download the newest patches,
in case the message is not in my inbox.
Otherwise I do not get your point: I keep untreated messages with the latest
patch version in my Guix inbox, and file away the others in a separate mbox.
So things are not flat, but have two levels: "to be treated" or "done".

Nothing to be documented, really, and I do not know whether these are just
personal habits or whether others work similarly. These might be the ways
of an aging non-emacs hacker...

> https://sourcehut.org/

This comes up a lot in the discussion and looks like an interesting
solution. It would be nice to be able to accomodate diverse styles
of working on Guix beyond (but including) emacs and vim.

Andreas

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

[Attila Lendvai]

> I feel like the advantages of a email-based workflow nowadays is more on
> the maintainer side of things (as managing large projects is easier


another thing worth pointing out here is that the harder it is to test a submitted patchset locally, the fewer non-committer reviews will happen.

and if all the review work rests on the shoulders of the committers, then there'll be long response times on submissions, or straight out forgotten/ignored submissions (khm). especially if it's about some hw or some sw that none of the committers care about, or could test locally (e.g. Trezor support: https://issues.guix.gnu.org/65037 that doesn't even build in master).

-- 
• attila lendvai
• PGP: 963F 5D5F 45C7 DFCD 0A39
--
“A programming language is low level when its programs require attention to the irrelevant.”
	— Alan Perlis

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

[Attila Lendvai]

> For this, I either go to issues.guix.gnu.org to download the newest patches,
> in case the message is not in my inbox.


some patchsets evolve a lot, and there are countless messages where obsolete patche versions are intermingled with non-obsolete discussion...


> Otherwise I do not get your point: I keep untreated messages with the latest
> patch version in my Guix inbox, and file away the others in a separate mbox.
> So things are not flat, but have two levels: "to be treated" or "done".


my point is that in a PR based model/workflow things like this is done by a program. and each brain cycle you spend on maintaining the sanity of your local inbox, is not spent on hacking, and the results of your effort is not even mirrored into the inbox of the other contributors.

this seems like a small thing, but multiply this with every message, and every potential contributor and maintainer... and then consider its cumulative effect on the emergent order that we call the Guix community.

meta:

the reason i'm contributing to this discussion is not that i'm proposing to move to some specific other platform right now. it's rather to nudge the consensus away from the conclusion that the email based workflow is good and is worth sticking with.

once/if we get closer that consensus, only then should the discussion move on to collect our requirements and evaluate the free sw solutions that are available today. which again could be organized much better in a wiki than in email threads, but that's yet another topic...

-- 
• attila lendvai
• PGP: 963F 5D5F 45C7 DFCD 0A39
--
“The only valid political system is one that can handle an imbecile in power without suffering from it.”
	— Nassim Taleb (1960–)

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

[Wilko Meyer]

Hi Attila,

Attila Lendvai <attila@lendvai.name> writes:

> i couldn't even find out which tools are used by those who are
> comfortable with the email based workflow. i looked around once, even
> in the manual, but maybe i should look again.

I can only speak for myself here, but I tend to use magit[0] from inside
emacs for most of these things (sometimes git format-patch and git
send-email directly on my shell). In magit there's:

- magit-am-* to apply patches[1]
- the magit-patch-popup to create patches[2]

I've written a few elisp functions on top of that, to be able to
e.g. directly apply a patch from a mail I've received (I use mu4e[3] as
my mail client) more conveniently. My set-up is far from being perfect
and quite simple, but more often than not perfectly enough for most of
my contributions to mail based projects.

More generally speaking, there's a pretty good tutorial[4] on
git-send-email written by the sourcehut folks, which also includes steps
on how to get git-send-email going on Guix. I usually refer to that when
being asked how to get started with a email based git workflow (I'm by
no means an expert on using said workflow (so I'd also be interested on
how said workflow looks like for other people on this mailing list), I
however do know enough to ocassionally use it conveniently enough for my
use-cases).

[0]: https://magit.vc
[1]: https://magit.vc/manual/magit/Maildir-Patches.html
[2]: https://magit.vc/manual/2.13.0/magit/Creating-and-Sending-Patches.html
[3]: https://djcbsoftware.nl/code/mu/mu4e.html
[4]: https://git-send-email.io/

Best Regards,

Wilko Meyer

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

[Katherine Cox-Buday]

On 8/23/23 11:27 AM, Felix Lechner via Development of GNU Guix and the 
GNU System distribution. wrote:

>> * Encourage upstream communities like "Guix 'R Us"
> 
> Every contributor should have their own channels for packages [1] and
> for Guix. [2] Testing patches before they are submitted would vastly
> improve the code quality in Guix.
> 
> Just fork my repos on Codeberg and use the 'prebuilt' branches. (Also,
> please tell me when to advance them to more recent commits.) Here is
> how you use them via Guix Home. [3]

I do exactly this! My channels can be found here: 
https://github.com/kat-co/guix-channels/tree/master

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

[Katherine Cox-Buday]

On 8/23/23 12:03 PM, Andreas Enge wrote:
> Hello,
> 
> Am Wed, Aug 23, 2023 at 10:27:31AM -0700 schrieb Felix Lechner via Development of GNU Guix and the GNU System distribution.:
>>>       I can't ever seem to get the GNU style commit messages correct.
>> Neither can I. The style apparently helps with automated maintenance
>> of the changelog, but I do not understand why a changelog is useful
>> for a rolling release model.
> 
> personally, I find them super helpful to grep through commit messages
> to find changes, like when a file was touched for the last time (now
> I think that git wizards will have a better solution; but you get the
> idea). Or when a package was added. Or updated to a specific version.

I have no love for Git's CLI (that's one of the reasons the email-based 
workflow grates on me; I use magit for everything), but I found it 
interesting that here you present a valid argument against having to 
learn Git in one way, and elsewhere people are making arguments for 
learning the git send-email command. I draw no conclusions from that, 
but it caught my eye!

FWIW, the git command you could use is:

git log --grep=foo -- the/file/path.scm

>> * Contributing to Guix is not for you
>> * It's OK to make lots of mistakes
> 
> Definitely "no" to the first one, and "yes" to the second one!
> I think that even when one only contributes from time to time, but
> regularly, habits will form and mistakes disappear.

I've been contributing to Guix since 2018. I've definitely learned a lot 
about Guix idiosyncrasies, but until I wrote my script, I'd forget to do 
something every time I submitted a patch.

--
Katherine

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

[Katherine Cox-Buday]

On 8/25/23 3:57 AM, Attila Lendvai wrote:

>> Otherwise I do not get your point: I keep untreated messages with the latest
>> patch version in my Guix inbox, and file away the others in a separate mbox.
>> So things are not flat, but have two levels: "to be treated" or "done".
> 
> 
> my point is that in a PR based model/workflow things like this is done by a program. and each brain cycle you spend on maintaining the sanity of your local inbox, is not spent on hacking, and the results of your effort is not even mirrored into the inbox of the other contributors.

I was reflecting on what it is about the email-based workflow that I 
find difficult, and I think you've highlighted one thing:

With a PR based workflow, there is a program essentially figuring out 
the equivalent of the `git send-email` flags and doing the submission 
for me. I generally go to the site for a repo's main branch, get 
prompted about my recent branch, click a button, and it's submitted.

And you've also highlighted the core of my original message: it's 
frustrating to spend effort on the meta of changing code instead of 
changing code. There will always be ancillary effort, but it can be 
greatly reduced.

> this seems like a small thing, but multiply this with every message, and every potential contributor and maintainer... and then consider its cumulative effect on the emergent order that we call the Guix community.

A thousand times this.

> 
> meta:
> 
> the reason i'm contributing to this discussion is not that i'm proposing to move to some specific other platform right now. it's rather to nudge the consensus away from the conclusion that the email based workflow is good and is worth sticking with.
> 
> once/if we get closer that consensus, only then should the discussion move on to collect our requirements and evaluate the free sw solutions that are available today. which again could be organized much better in a wiki than in email threads, but that's yet another topic...

I just want to call out that my original message was not strictly about 
the email based workflow. I want reduction of cognitive overhead to be 
an ongoing goal, whatever that comes to mean.

--
Katherine

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

[Katherine Cox-Buday]

On 8/23/23 6:18 PM, Csepp wrote:

>> * Contributing to Guix is not for you
>>
>>      I would be really sad if someone ever said this, but I guess it's a
>>      possibility. Maybe someone like me just can't be a contributor to
>> Guix until
>>      I have the bandwidth to manage all the details. I would
>> preemptively argue
>>      that diversity of thought and experiences usually leads to better
>> things.
> 
> I really hope we can lower the barrier to entry without sacrificing code
> quality precisely because of this.  Lots of important use cases that
> Guix could serve are ignored because the people who need them are not
> represented in our community and/or they can't contribute and no one is
> able/willing to write code for them.

Yes, the goal has to be to lower the cognitive overhead while 
maintaining the level of quality.

> 
>> * It's OK to make lots of mistakes
>>
>>      The people who have reviewed my code have been generous both with
>> their time
>>      and fixing my mistakes and then applying. Maybe this model is OK?
>> I still
>>      feel guilty every time a reviewer has to correct an oversight I've
>> made. I
>>      also want to become a committer, but I don't know how that would
>> work if
>>      I'm regularly making mistakes. Obviously people would still be
>> reviewing my
>>      commits, but presumably a committer should not regularly be making
>>      mistakes.
> 
> In a sense I agree with this, but if mistakes are this easy to make,
> then I think something is wrong with the project, not with the
> contributor.  Instead of making people learn tightrope walking, maybe we
> should be building actual bridges.

Yes! For the same reason that focusing on accessibility helps everyone, 
focusing on making it easy to avoid mistakes helps everyone.

> Guix actually fares pretty well in this regard compared to some other
> projects I tried contributing to (*stares at Plan 9*), but there is
> still a lot of knowledge that experienced developers take for granted
> and don't actually document.  Writing new packages is mostly documented
> well, but as soon as something breaks, you are thrown into the deep end,
> having to dissect logs, bisect commit ranges, learn strace, gdb (which
> still doesn't work well on Guix), learn how to compile packages with
> debug info (and actually waste some more CPU time and IO on rebuilding a
> package you already have), learn how to adapt docs from other distros,
> etc, etc, etc.
> I've been trying to document these at least for myself, but haven't yet
> had time to put them together into something others could read.

A lot of the activities you mentioned fall into the "learn to be a 
developer" category, and I think it's a little too broad of a target, at 
least for what I was trying to point out.

> By the way, that's another issue.  Using a TeX based document format for
> the docs is, uuuh, maybe not the best idea.  Info is a pretty okayish
> documentation reader, but it's a relatively big barrier to entry
> compared to what you need to know to make a small edit to the Arch wiki.
> This way mostly just experienced contributors write docs, not the
> users who just want to document how they made some weird use case
> possible.

Another great example. I don't write much documentation because of this.

--
Katherine

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

[Katherine Cox-Buday]

On 8/24/23 6:10 PM, Ekaitz Zarraga wrote:

>>                                        Lots of important use cases that
>> Guix could serve are ignored because the people who need them are not
>> represented in our community and/or they can't contribute and no one is
>> able/willing to write code for them.
> 
> Yes, and even if you manage to write something yourself, many times you
> get now answer to your patches because no one else is interested on what
> you did. It's perfectly understandable but also discouraging.
> 
> Example: I wanted to push Zig support in guix a while ago. Made a build
> system and got no answer. <https://issues.guix.gnu.org/60889#3>
> The feeling here is that the code proposed is not good enough, but I don't
> know how to improve it so I'm stuck. It would be great to feel comfortable
> enough with the code to be sure that it can be merged, but I can't find
> the resources to make it better. If it was clearer or if it was easier
> both sides, maintainers and contributors, would be more effective and
> happier.

Yes, a point I'm seeing echoed a lot here which I can't highlight enough is:

Any effort made to make it easier to contribute helps everyone, not just 
those having issues.

Your point about your patch going unanswered is indeed a good example. 
Here we sit with no Zig build system. It can't be proven, but maybe if 
contributing and reviewing were easier, we'd have more hands, and 
getting something like that merged would be easier.

>>> * It's OK to make lots of mistakes
>>>
>>> The people who have reviewed my code have been generous both with their
>>> time and fixing my mistakes and then applying. Maybe this model is OK? I
>>> still feel guilty every time a reviewer has to correct an oversight I've
>>> made. I also want to become a committer, but I don't know how that would
>>> work if I'm regularly making mistakes. Obviously people would still be
>>> reviewing my commits, but presumably a committer should not regularly be
>>> making mistakes.
> 
> Exactly my feeling. And I've been working with Guix for a while...

Same here. My first commit was in 2018.

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

[Katherine Cox-Buday]

On 8/23/23 9:33 PM, Ahmed Khanzada via Development of GNU Guix and the 
GNU System distribution. wrote:
> My wife and I are currently trying, so I hope to be a busy parent soon too!

Good luck to you!

> The debate comes down to: the people contributing the most code already
> have a very familiar workflow that they have automated (all probably within
> Emacs). Why should they change their contribution model for those who
> don't contribute much currently, and may never do so? (Not implying this
> is you! Just recounting the debate).

I know it's not your argument, but do you see the circular logic?

This type of "reasoning" is used to great effect in society to maintain 
an "in group" and an "out group". E.g. "There aren't a lot of paralyzed 
people at the top of these stairs, so why should we build a ramp if 
there's no one to use it?"

> But you're not asking that; you just want to lower the cognitive overhead.

Thank you for acknowledging my central point.

> I can't do much about the brutal learning curve of Emacs, Guix, and GNU,
> but I certainly can just package it so it's all ready to go with fancy
> scripts for the most common workflows.

I don't mind the learning. I actually think I know everything that 
should be done, it's just very cumbersome and error-prone to do 
everything, every time.

--
Katherine

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

[Katherine Cox-Buday]

On 8/24/23 12:33 AM, ( wrote:

>> * We could support a managed web-based workflow
> 
> The problem with this is that it would not be possible without changing
> the git hosting entirely to something like Gitea.  I'm personally a fan
> of the email-based workflow; what, specifically, is it that bothers you
> about it?  If it's:

I can envision some kind of upstream branch that's blessed and merged 
daily. The web crowd commits to that, the email crowd commits to main.

> - Setting it up: Yes, this is annoying.  Sadly, our mighty oligarchal
>    masters have taken it upon themselves to make it as annoying as
>    possible to use email from anywhere but their web or mobile clients.

This isn't it at all, but I agree with your comment. I'm fond of email, 
and it's distressing how centralized it's become.

> - Sending the emails: This isn't that bad once you get used to it;
>    sadly most Git clients (magit sadly included) don't support send-email
>    well or at all.  But on the command line, all you need to do is:
> 
>    # for a single commit
>    $ git send-email --to=guix-patches@gnu.org -1 --base=master -a
>    # for several commits
>    $ git send-email --to=guix-patches@gnu.org -$N_COMMITS --base=master --cover-letter -a
> 
>    Or, if sending an amended series:
>    $ git send-email --to=$BUG_NUM@debbugs.gnu.org -$N_COMMITS --base=master -a -v$VERSION

It's this. Having to:

1. Remember the flags and their values
2. Remember the email address (it might seem silly unless you have forms 
of dyslexia. is it guix-patches? or patches-guix? Wait, what was I doing?)
3. And then the whole deal with what to do with follow ups.

I feel like I know my way around git pretty well, but I struggle with 
how those concepts map onto sending emails.

I have only been able to surmount this by lifting these concepts through 
scripts into higher-order concepts with less cognitive overhead.

> - Switching between branches: The best way to handle this is with
>    subtrees; see `git subtree --help`.

Interesting! I use worktrees, but maybe subtrees are easier? I'll have 
to read up on this. Thank you!

> - Applying patches: This is a bit annoying.  Most email clients won't
>    let you set up commands to pipe mailboxes to, unlike aerc.  Perhaps we
>    could have a `mumi apply` command to fetch a patch series from debbugs
>    and apply it to the checkout.

I wrote some elisp to one-key apply patches from GNUS, but I guess my 
point is: not everyone can do that. How are we to expect more 
contributors if that, or something similar, is the barrier to entry?

--
Katherine

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

[Katherine Cox-Buday]

On 8/24/23 12:53 PM, Simon Tournier wrote:
> Hi,
> 
> At some point, I sympathize.
> 
> On Wed, 23 Aug 2023 at 10:25, Katherine Cox-Buday <cox.katherine.e@gmail.com> wrote:
> 
>>    I don't use the email-based patch workflow day-to-day, so this is
>> another area where I spend a lot of time trying to make sure I'm doing
>> things correctly.
> 
> I agree that Debbugs is not handy at all for submitting patches.  Send
> the cover letter, wait, refresh email, wait, refresh email, loop until
> an issue number is assigned, and then send the series.

Yes, and imagine that between every step, it is likely that something 
pulls your attention away. Maybe you have ADHD, maybe a kiddo is asking 
you endless (but interesting) questions.

This is where the overhead begins to erode contributions. People can end 
up spending their limited resources managing the workflow instead of 
improving Guix.

> Reduce friction for making contributions?  Yes, we all want that, I
> guess.  The question is how?  What is the right balance between the
> change of habits and the satisfaction of people used to these habits?

I think a good start is to eliminate toil for everyone. It doesn't 
matter how something is done if it doesn't need doing! Manually 
organizing/pruning imports is a good example.

The good news is that we are working with computers which, among other 
things, are purpose-built for automating away toil :)

> 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.
> 
> 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.

That's a good point, but even along that gradient, there's a baseline of 
toil which is not a function of the complexity of the code.

But also, even for complicated things, a tight loop of exploration is 
useful for getting things right. For some, as I alluded to above, it's 
even a critical component for even completing the task.

>> * We could support a managed web-based workflow
> 
> Here, I am very doubtful that it would help.
> 
> 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.

It's a good question.

> Another example is Software Heritage (SWH).  Their web-based workflow is
> a Gitlab instance [1].  As an occasional person who deal with the SWH
> archive, I am never able to find my way and I just roam on #swh-devel
> IRC channel asking for help.

I think there's utility in distinguishing between familiarity and 
eliminating toil. I think it was incorrect of me to suggest forming 
habits in my original message. I think it's better to focus on 
eliminating toil so that whatever workflow remains can more easily be 
habituated.

> Another example: the channel guix-science [2] based on GitHub.  Well, I
> am able to count using one of my hands the number of PRs. ;-) (And I do
> not speak about other channels as nonguix)
>   
> Well, reading the item above about mistake and the item below about
> "Guix 'R Us", and maybe I am wrong, somehow I feel that one “cognitive
> overhead” is the willing to submit a perfect patch.  Again, maybe I am
> wrong, somehow I feel that one part of the issue is a lack of
> self-confidence.  Do not take me wrong, I am speaking about submitting a
> patch by occasional contributor and not about the personality of person
> that I do not personally know. :-)
> 
> This “that’s not perfect so I postpone the submission” is something I
> often hear by people attending to Café Guix [3].  Hum, I do not know
> what we could do differently for reducing this barrier.
> 
> The idea of the team Mentor is in this direction but it does not seem
> working… :-(
> 
> 1: https://gitlab.softwareheritage.org/explore
> 2: https://github.com/guix-science/guix-science
> 3: https://hpc.guix.info/events/2022/caf%C3%A9-guix/

Similarly, I think there's utility in distinguishing between learning 
and cognitive overhead. I can learn anything, but there are factors 
beyond my control that cause high levels of cognitive overhead to cause 
enough friction to stop me.

Mentorship is a great thing, and I'm sure I"d learn a lot from a mentor, 
but it wouldn't solve the problem I've raised unless the mentor somehow 
showed me how to eliminate the cognitive overhead, in which case: let's 
just do that for everyone.

> For sure, I think that part of the solution is by finding the way to
> collaborate.  Somehow, what would be your expectations for contributing
> more?  Or for easing your contributions? :-)

A fast feedback loop with as few points of interruption between writing 
code and submitting a patch.

--
Katherine

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

[Liliana Marie Prikler]

Am Freitag, dem 25.08.2023 um 08:07 +0000 schrieb Attila Lendvai:
> i couldn't even find out which tools are used by those who are
> comfortable with the email based workflow. i looked around once, even
> in the manual, but maybe i should look again.
Users who have tried curlbash also looked at
  wget https://issues.guix.gnu.org/issue/N/patch-set/M | git am -3

> i'm pretty sure most maintainers have a setup where the emailed
> patches can be applied to a new branch with a single press of a
> button, otherwise it'd be hell of a time-waster.
Well, it's several keys, actually, but as others have already pointed
out, keyboard > mouse.

> 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.

> > But someone would have to write and maintain them...
> 
> 
> there are some that have already been written. here's an ad-hoc list
> of references:
> 
> #github #gitlab #alternative
> https://codeberg.org/
> https://notabug.org/
> https://sourcehut.org/
> https://sr.ht/projects
> https://builds.sr.ht/
> https://git.lepiller.eu/gitile
> codeberg.org is gitea and sr.ht is sourcehut
Gitile is (as far as I'm aware) not yet a full forge.  It also hasn't
loaded for me in ages, but I digress.

It doesn't suffice if you just integrate any of those forges into the
pre-existing workflow somehow.  You must also make it a pleasant
experience for everyone involved.  This is similar to the issue that
already bugs our Matrix<->IRC bridge.  

Other implicit assumptions include that people will be happy to switch
for the particular fork you've chosen (they won't) and will not demand
$new_hot_thing within the next five years (they likely will, just look
at the ChatGPT-related stuff that has been submitted).  There sadly is
no pleasing everyone here and unless these tools are incredibly simple
to maintain, the utilitarian approach of least misery leads you to
plain email.

Cheers

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

[kiasoc5]

On 2023-08-24 08:33, ( wrote:
> Katherine Cox-Buday <cox.katherine.e@gmail.com> writes:
> 
>>     I can't ever seem to get the GNU style commit messages correct. 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.
> 
> You do get used to it, but the format is very... verbose, and 
> personally
> I think we should abandon it; the signal:noise ratio isn't good, and I
> don't think the automatic generation of ChangeLog files is a great idea
> anyway, since so many changes to Guix are so trivial.


I agree with this, the commit messages could be made less verbose. One 
way is to go from this:

     gnu: PACKAGE: Update to VERSION.

     * gnu/packages/SCM.scm (PACKAGE): Update to VERSON.

to this:

     Update PACKAGE to VERSION.

Because I already know that the package was updated, and it doesn't 
matter which .scm file it's in unless the package is moving to a 
different module. I do like the GNU style for changes to packaging style 
(eg inputs/phases) but many package upgrades are just simple version 
bumps.

> I think we should just use the news file more often instead.

Yes. For example, where's the news for the recent KDE system service, or 
the recent Texlive reorganization? (great work from all involved!)

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

[kiasoc5]

On 2023-08-25 11:31, Attila Lendvai wrote:
>> I feel like the advantages of a email-based workflow nowadays is more 
>> on
>> the maintainer side of things (as managing large projects is easier
> 
> 
> another thing worth pointing out here is that the harder it is to test 
> a submitted patchset locally, the fewer non-committer reviews will 
> happen.
> 
> and if all the review work rests on the shoulders of the committers, 
> then there'll be long response times on submissions, or straight out 
> forgotten/ignored submissions (khm). especially if it's about some hw 
> or some sw that none of the committers care about, or could test 
> locally (e.g. Trezor support: https://issues.guix.gnu.org/65037 that 
> doesn't even build in master).

I would like to hear from committers if non-committer reviews are 
helpful, because I don't really know how or what I can comment on for 
incoming patches on packages I'm not really familiar with.

Also do "this builds and works locally" comments help?

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

[Liliana Marie Prikler]

Hi kiasoc5, hi Attila

Am Samstag, dem 26.08.2023 um 19:42 +0200 schrieb kiasoc5@disroot.org:
> On 2023-08-25 11:31, Attila Lendvai wrote:
> > > I feel like the advantages of a email-based workflow nowadays is
> > > more on the maintainer side of things (as managing large projects
> > > is easier
> > 
> > 
> > another thing worth pointing out here is that the harder it is to
> > test a submitted patchset locally, the fewer non-committer reviews
> > will happen.
> > 
> > and if all the review work rests on the shoulders of the
> > committers, then there'll be long response times on submissions, or
> > straight out forgotten/ignored submissions (khm). especially if
> > it's about some hw or some sw that none of the committers care
> > about, or could test locally (e.g. Trezor support:
> > https://issues.guix.gnu.org/65037 that 
> > doesn't even build in master).
Do you mean that Trezor doesn't currently build on master or that this
series doesn't build relative to master any longer?  It'd be quite
weird if it was the latter, but oh well.  I'll review the series
afterwards.

> I would like to hear from committers if non-committer reviews are 
> helpful, because I don't really know how or what I can comment on for
> incoming patches on packages I'm not really familiar with.
If you're not familiar with the package, on which grounds would you
review the patch?  This holds for committers and non-committers all the
same; it's a main reason as to why I don't review many Emacs packages
despite being in the Emacs team.  My init.el is on the smaller side and
only exercises a small portion of the emacs-xyz module.

On the other hand, if you do have relevant information to add, please
do so.  For instance, if you know about the hardware or the software or
even if you've only heard about some anti-feature such as telemetry,
such information is valuable.  If you want to nerd about the way we
write ChangeLogs, that's also fine, and might save someone else the
need to do so (or encourage them to do so as well, you win some, you
lose some).

> Also do "this builds and works locally" comments help?
"Builds locally" not so much, unless it's a package that CI doesn't
handle usually.  "Works locally" should be qualified to distinguish it
from simply "builds locally", but if you say something along the lines
of "I've tested and ran the program; it works as I'd expect", you might
be saving a committer some time and allow them to focus on other
things.  If there are no cosmetic flaws and the committers are aware
that the package works fine for more than just a single person, they
can fast track it more easily.  OTOH, if you write "works locally" and
no committer reads it – for any reason, really – the result will be the
same as if you never wrote it.

TL;DR: "Builds locally" helps maybe, but probably not.
"Works locally" probably helps, but sometimes not.

For cases in which "works locally" doesn't seem to help, you sadly have
to check the CCs and add a committer who might look like they'd be
interested in upstreaming the series :(

Cheers

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

[Attila Lendvai]

> > > straight out forgotten/ignored submissions (khm). especially if
> > > it's about some hw or some sw that none of the committers care
> > > about, or could test locally (e.g. Trezor support:
> > > https://issues.guix.gnu.org/65037 that
> > > doesn't even build in master).
> 
> Do you mean that Trezor doesn't currently build on master or that this
> series doesn't build relative to master any longer? It'd be quite


in master `guix build python-daemon` leads to an attempted local build that fails. the rest of the stack depends on python-daemon.

this has been the case for several months now.

a previous iteration of this fix is back from 2022 dec:

https://issues.guix.gnu.org/58437#7

it was pending long enough to get obsolete by new releases of the projects.

-- 
• attila lendvai
• PGP: 963F 5D5F 45C7 DFCD 0A39
--
“People are always shouting they want to create a better future. It's not true. The future is an apathetic void of no interest to anyone. The past is full of life, eager to irritate us, provoke and insult us, tempt us to destroy or repaint it. The only reason people want to be masters of the future is to change the past.”
	— Milan Kundera (1929–)

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

[Maxim Cournoyer]

Hi,

Csepp <raingloom@riseup.net> writes:

[...]

> but as soon as something breaks, you are thrown into the deep end,
> having to dissect logs, bisect commit ranges, learn strace, gdb (which
> still doesn't work well on Guix)

Hm?  Why GDB on Guix may be sometimes more challenging than say, on
Fedora, I only know of one problem, that is related to grafts (see: #48907).

For running binaries wrapped in shell script, I have this 'run-gdb'
wrapper which reads:

--8<---------------cut here---------------start------------->8---
#!/usr/bin/env bash

wrapper=$(cat $(which $1))
shift
. <(echo "$wrapper" | grep ^export)
binary=$(echo "$wrapper" | grep ^exec | grep -o -E '/gnu/store[^"]*')
gdb --args "$binary" "$@"
--8<---------------cut here---------------end--------------->8---

Hope that helps,

-- 
Thanks,
Maxim

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

[Maxim Cournoyer]

Hi,

Katherine Cox-Buday <cox.katherine.e@gmail.com> writes:

[...]

>> By the way, that's another issue.  Using a TeX based document format for
>> the docs is, uuuh, maybe not the best idea.  Info is a pretty okayish
>> documentation reader, but it's a relatively big barrier to entry
>> compared to what you need to know to make a small edit to the Arch wiki.
>> This way mostly just experienced contributors write docs, not the
>> users who just want to document how they made some weird use case
>> possible.
>
> Another great example. I don't write much documentation because of this.

Texinfo is mostly just plain text until you learn about a few decorators
:-).  It gives us the info manuals that I find very nifty (it's like a
man page, but with hyperlinks and advanced navigation capabilities!) and
used across many GNU projects (e.g. coreutils, Emacs, Bash, GCC, GNU
Make, etc.)  I see it as a strength more than a weakness for the
project.

-- 
Thanks,
Maxim

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

[Maxim Cournoyer]

Hi Katherine,

Katherine Cox-Buday <cox.katherine.e@gmail.com> writes:

> On 8/24/23 12:33 AM, ( wrote:
>
>>> * We could support a managed web-based workflow
>> The problem with this is that it would not be possible without
>> changing
>> the git hosting entirely to something like Gitea.  I'm personally a fan
>> of the email-based workflow; what, specifically, is it that bothers you
>> about it?  If it's:
>
> I can envision some kind of upstream branch that's blessed and merged
> daily. The web crowd commits to that, the email crowd commits to main.
>
>> - Setting it up: Yes, this is annoying.  Sadly, our mighty oligarchal
>>    masters have taken it upon themselves to make it as annoying as
>>    possible to use email from anywhere but their web or mobile clients.
>
> This isn't it at all, but I agree with your comment. I'm fond of
> email, and it's distressing how centralized it's become.
>
>> - Sending the emails: This isn't that bad once you get used to it;
>>    sadly most Git clients (magit sadly included) don't support send-email
>>    well or at all.  But on the command line, all you need to do is:
>>    # for a single commit
>>    $ git send-email --to=guix-patches@gnu.org -1 --base=master -a
>>    # for several commits
>>    $ git send-email --to=guix-patches@gnu.org -$N_COMMITS --base=master --cover-letter -a
>>    Or, if sending an amended series:
>>    $ git send-email --to=$BUG_NUM@debbugs.gnu.org -$N_COMMITS --base=master -a -v$VERSION
>
> It's this. Having to:
>
> 1. Remember the flags and their values
> 2. Remember the email address (it might seem silly unless you have
> forms of dyslexia. is it guix-patches? or patches-guix? Wait, what was
> I doing?)
> 3. And then the whole deal with what to do with follow ups.
>
> I feel like I know my way around git pretty well, but I struggle with
> how those concepts map onto sending emails.

Perhaps you'd like to invest 1 hour (30 minutes?) into learning to use
'patman'.  It allows attaching metadata to a feature branch by means of
Git message tags, e.g. the associated email address with 'Series-to:',
or the current revision with 'Series-version:', etc.  Then submitting
the series is a matter of invoking just 'patman', and following the
indications.

For more information, try: 'guix shell info-reader u-boot -- info
"(u-boot) Patman patch manager"'

> I have only been able to surmount this by lifting these concepts
> through scripts into higher-order concepts with less cognitive
> overhead.
>
>> - Switching between branches: The best way to handle this is with
>>    subtrees; see `git subtree --help`.
>
> Interesting! I use worktrees, but maybe subtrees are easier? I'll have
> to read up on this. Thank you!
>
>> - Applying patches: This is a bit annoying.  Most email clients won't
>>    let you set up commands to pipe mailboxes to, unlike aerc.  Perhaps we
>>    could have a `mumi apply` command to fetch a patch series from debbugs
>>    and apply it to the checkout.
>
> I wrote some elisp to one-key apply patches from GNUS, but I guess my
> point is: not everyone can do that. How are we to expect more
> contributors if that, or something similar, is the barrier to entry?

Using an Emacs-based workflow:

1. C-u M-x debbugs-gnu RET guix-patches RET [then answer prompts]
2. M-x cd RET ~/src/guix or wherever is your guix checkout
3. Select series you want to apply
4. Sort by subject
5. Press '|' (pipe) on any message, and pipe this to the command 'git am
-3'.  To apply multiple patches at once, you can specify an argument
prefix, e.g. 'C-u 10 |' to apply 10 patches at once.

I hope that helps someone.

-- 
Thanks,
Maxim

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

[Maxim Cournoyer]

Hello,

Attila Lendvai <attila@lendvai.name> writes:

>> 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.
>
>
> the ultimate goal is not just diversity, but high efficiency of the
> people who cooperate around Guix, which then translates into a better
> Guix.
>
> if the "rituals" around Guix contribution were merely a steep initial
> learning curve, then one could argue that it's a kind of filter that
> helps with the signal to noise ratio. but i think it's also a constant
> hindrance, not just an initial learning curve.
>
>
>> Just because it's brought up a lot of times doesn't mean it's a good
>> idea. There is a lot of good things that can be done for our web-based
>> front ends; improving the search results on issues.guix.gnu.org would
>> be one of them. However, I have little hopes for a web based means to
>> submit contributions. I think email should be a format that's
>> understood by folks who know how to operate a web browser.
>
>
> again, i would press the argument that it's not about being able to,
> but about how much effort/attention is wasted on administration
> (i.e. not on hacking). i often have the impression that it took
> comparable effort to submit a smaller to mid size patch than making
> it.

In the simplest case, it can be as simple as:

--8<---------------cut here---------------start------------->8---
$ ./pre-inst-env guix refresh -u some-package
[build it, try it, fix if needed]
$ ./etc/committer.scm
$ git send-email
--8<---------------cut here---------------end--------------->8---

Since it's a single patch, there's no jumping through hoops to create
the original issue, and the auto-configured git will CC teams people
subscribed to the scope of your change (if there are any).

-- 
Thanks,
Maxim

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

[宋文武]

Maxim Cournoyer <maxim.cournoyer@gmail.com> writes:

> Perhaps you'd like to invest 1 hour (30 minutes?) into learning to use
> 'patman'.  It allows attaching metadata to a feature branch by means of
> Git message tags, e.g. the associated email address with 'Series-to:',
> or the current revision with 'Series-version:', etc.  Then submitting
> the series is a matter of invoking just 'patman', and following the
> indications.
>
> For more information, try: 'guix shell info-reader u-boot -- info
> "(u-boot) Patman patch manager"'

Oh, patman look interesting for long series, will learn it later..

>> I wrote some elisp to one-key apply patches from GNUS, but I guess my
>> point is: not everyone can do that. How are we to expect more
>> contributors if that, or something similar, is the barrier to entry?
>
> Using an Emacs-based workflow:
>
> 1. C-u M-x debbugs-gnu RET guix-patches RET [then answer prompts]
> 2. M-x cd RET ~/src/guix or wherever is your guix checkout
> 3. Select series you want to apply
> 4. Sort by subject

Also can first read on issues (mumi), find a issue ID,
then M-x gnus-read-ephemeral-emacs-bug-group ID.

> 5. Press '|' (pipe) on any message, and pipe this to the command 'git am
> -3'.  To apply multiple patches at once, you can specify an argument
> prefix, e.g. 'C-u 10 |' to apply 10 patches at once.
>
> I hope that helps someone.

Don't know the 'C-u 10 |' one, cool, thank you!

Non-committer comments on patches

[Andreas Enge]

Hello,

Am Sat, Aug 26, 2023 at 07:42:13PM +0200 schrieb kiasoc5@disroot.org:
> I would like to hear from committers if non-committer reviews are helpful,
> because I don't really know how or what I can comment on for incoming
> patches on packages I'm not really familiar with.
> Also do "this builds and works locally" comments help?

+1 for Liliana's comment on "works locally". "Builds locally" is superfluous,
as I always rebuild packages I commit (and there is QA).

As a member of the science team, I end up being "responsible" for packages
I do not use and cannot really judge. So having a second person comment
that a change works as expected, or that an old version can be dropped,
or cannot be dropped because everyone in the community uses it, or anything
indeed related to the use of the package, is a big help. I have even ended
up solliciting comments by people who have worked on the package in the past.

I can also imagine a go team, say, of non-committers, and then committing
on their behalf when two team members agree with a patch, for instance.
(With the goal of adding committer(s) from the team eventually.)

Andreas

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

[Josselin Poiret]

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

Hi everyone,

Katherine Cox-Buday <cox.katherine.e@gmail.com> writes:

> I have no love for Git's CLI (that's one of the reasons the email-based 
> workflow grates on me; I use magit for everything), but I found it 
> interesting that here you present a valid argument against having to 
> learn Git in one way, and elsewhere people are making arguments for 
> learning the git send-email command. I draw no conclusions from that, 
> but it caught my eye!
>
> FWIW, the git command you could use is:
>
> git log --grep=foo -- the/file/path.scm

Just to add my 2 cents, any editor with decent support for git
(eg. emacs with magit) will have git blame and git log for regions
support baked in, I regularly use that to look at changes.  I don't
think I've ever used git grep with ChangeLog style commits.  Sometimes I
like reading commit explanations for complicated commits, but I feel
like they're a bit orthogonal to the requirements that the ChangeLog
format imposes on us.

With the git tools we have, I'm not sure the ChangeLog format is really
needed, it dates back to an era where they didn't exist.

Best,
-- 
Josselin Poiret

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

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

[Josselin Poiret]

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

Hi everyone,

Maxim Cournoyer <maxim.cournoyer@gmail.com> writes:

> Texinfo is mostly just plain text until you learn about a few decorators
> :-).  It gives us the info manuals that I find very nifty (it's like a
> man page, but with hyperlinks and advanced navigation capabilities!) and
> used across many GNU projects (e.g. coreutils, Emacs, Bash, GCC, GNU
> Make, etc.)  I see it as a strength more than a weakness for the
> project.

I agree with Maxim here, I think the texinfo markup is important to be
able to generate such a nice manual: the Guix and Guile manuals are
among the nicest to browse because of all the formatting that you have
available, and the hyperlinks.  I've also not had any issues adding
stuff to the manual while not knowing anything about the format, just
mimicking stuff found nearby.  YMMV though, depending on what changes
you might want to make.

Best,
-- 
Josselin Poiret

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

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

[Attila Lendvai]

> > 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


not sure how most people consume their emails nowadays, but for me it's one flat list per thread, in a browser (i.e. it's not a tree).

and i haven't used any forges where there's not at least a flat timeline per PR.

i used to use emacs for emails for a while, but i stopped. the learning curve was too steep, and documentation was sparse, for little perceived benefit. at one point i noticed that it was saving unencrypted drafts of encrypted threads into my online mail account, and i decided to abandon it.

now i rely on webmail with Edit in Emacs browser extension. it's good enough for everything i do, except maybe for contributing to Guix.


> 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.


are you by any chance mixing the standards that we set out for the Guix repo, with the means of communication while a patchset is being forged into mergeable quality?

and even if you are not, we could simply add an entry to the requirement list that the commit history of a PR must be retained even when a PR is force-pushed. it's not that emails are inherently superior.


> Other implicit assumptions include that people will be happy to switch
> for the particular fork you've chosen (they won't) and will not demand
> $new_hot_thing within the next five years (they likely will, just look


my implicit assumption is that a project is ready to switch communication technologies every few years, *if* it's justified. and all i'm trying to achieve here is to move the discussion away from email-is-superior-period, to look at what requiremenets we have and what tools satisfy them, if any.


> at the ChatGPT-related stuff that has been submitted). There sadly is
> no pleasing everyone here and unless these tools are incredibly simple
> to maintain, the utilitarian approach of least misery leads you to
> plain email.


but is a least-misery model appropriate here? how do you even account for the contributions that could have happened in a different environment, but did not happen?

similarly, e.g. demanding a dated ChangeLog format for commit messages has a filtering effect on who will contribute, and then who will stick around. most engineers have a hard time jumping through hoops that they find pointless (git automatically encodes that information), and i'd suggest considering what the effect are of such rules on Guix as an emergent order.

what makes it even more tricky is that it's a self-perpetuating meme, because the more such conservative policies are enforced, the fewer people will stick around who would advocate for change.

yes, the balance between change and conservatism is tricky, but i think we have moved on from CVS long enough ago to e.g. abandon the ChangeLog format... (or alternatively, i'm blind to the use-cases that it is crucial for).

-- 
• attila lendvai
• PGP: 963F 5D5F 45C7 DFCD 0A39
--
“I sincerely believe that banking establishments are more dangerous than standing armies, and that the principle of spending money to be paid by posterity, under the name of funding, is but swindling futurity on a large scale.”
	— Thomas Jefferson (1743–1826)

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

[Saku Laesvuori]

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

> > > 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
> 
> 
> not sure how most people consume their emails nowadays, but for me
> it's one flat list per thread, in a browser (i.e. it's not a tree).

The point is that the emails contain the information on how to construct
a tree out of them. It's just that most web clients (which most people
are unfortunately using nowadays) are so bad that they render the tree
as a flat list.

> i used to use emacs for emails for a while, but i stopped. the
> learning curve was too steep, and documentation was sparse, for little
> perceived benefit. at one point i noticed that it was saving
> unencrypted drafts of encrypted threads into my online mail account,
> and i decided to abandon it.
> 
> now i rely on webmail with Edit in Emacs browser extension. it's good
> enough for everything i do, except maybe for contributing to Guix.

Maybe having a proper tree representation of your emails is a sufficient
benefit to change your email client or maybe you don't care about it
that much. Anyway the email-based format gives the *option* to see the
discussion as a tree, while a forge either shows messages as a tree or
it doesn't. There is nothing that can be done to make it show them
differently.

By the way, I don't know what webmail you are using but I would be very
sceptical of it keeping your drafts any more secure. It probably either
stores the encryption keys on the server, sends data from the message
editor to the server for some computation or relies on random javascript
that could read your mails and send them directly to anyone who wants to
snoop on you.

> and all i'm trying to achieve here is to move the discussion away from
> email-is-superior-period, to look at what requiremenets we have and
> what tools satisfy them, if any.

I think that is a good discussion to have, but I think it would be
better to describe some of the requirements you think we should consider
instead of just saying email isn't superior. It might not be, but it
might also be. We should consider what we need and evaluate the
available tools based on that, and if the result is that email is
the best then it is.

> > at the ChatGPT-related stuff that has been submitted). There sadly is
> > no pleasing everyone here and unless these tools are incredibly simple
> > to maintain, the utilitarian approach of least misery leads you to
> > plain email.
> 
> but is a least-misery model appropriate here? how do you even account
> for the contributions that could have happened in a different
> environment, but did not happen?
> 
> similarly, e.g. demanding a dated ChangeLog format for commit messages
> has a filtering effect on who will contribute, and then who will stick
> around. most engineers have a hard time jumping through hoops that
> they find pointless (git automatically encodes that information), and
> i'd suggest considering what the effect are of such rules on Guix as
> an emergent order.

I agree on the ChangeLogs being a weird thing to require in commit
messages. I think of commit messages as the place where you record the
reasons behind the change in the commit. The ChangeLog seems to just
record the changes which the diff of the commit already automatically
records more accurately.

If someone has use cases for the ChangeLog commits, I'd like to hear
them. Maybe there is something that can't be achieved with git history
without ChangeLogs, but I can't think of anything. Someone mentioned
grepping the git log with them, but I think the same thing can be done
with git log and git blame regardless of the commit message format.

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

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

[Liliana Marie Prikler]

Hi,

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

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

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

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

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

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

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

Cheers

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

[(]

Katherine Cox-Buday <cox.katherine.e@gmail.com> writes:
>> - Sending the emails: This isn't that bad once you get used to it;
>>    sadly most Git clients (magit sadly included) don't support send-email
>>    well or at all.  But on the command line, all you need to do is:
>>    # for a single commit
>>    $ git send-email --to=guix-patches@gnu.org -1 --base=master -a
>>    # for several commits
>>    $ git send-email --to=guix-patches@gnu.org -$N_COMMITS --base=master --cover-letter -a
>>    Or, if sending an amended series:
>>    $ git send-email --to=$BUG_NUM@debbugs.gnu.org -$N_COMMITS --base=master -a -v$VERSION
>
> It's this. Having to:
>
> 1. Remember the flags and their values
> 2. Remember the email address (it might seem silly unless you have forms of
> dyslexia. is it guix-patches? or patches-guix? Wait, what was I doing?)
> 3. And then the whole deal with what to do with follow ups.
>
> I feel like I know my way around git pretty well, but I struggle with how those
> concepts map onto sending emails.
>
> I have only been able to surmount this by lifting these concepts through scripts
> into higher-order concepts with less cognitive overhead.

Ah, okay.  This might be solvable with the `mumi` command...

>> - Switching between branches: The best way to handle this is with
>>    subtrees; see `git subtree --help`.
>
> Interesting! I use worktrees, but maybe subtrees are easier? I'll have to read
> up on this. Thank you!

Oops, sorry, I did mean worktrees :)  I ran 'git subtree --help'
forgetting that it's actually 'git worktree', but it turns out subtrees
are a thing too; so I saw that the command worked and assumed I'd got
the correct name for the command... 

>
>> - Applying patches: This is a bit annoying.  Most email clients won't
>>    let you set up commands to pipe mailboxes to, unlike aerc.  Perhaps we
>>    could have a `mumi apply` command to fetch a patch series from debbugs
>>    and apply it to the checkout.
>
> I wrote some elisp to one-key apply patches from GNUS, but I guess my point is:
> not everyone can do that. How are we to expect more contributors if that, or
> something similar, is the barrier to entry?

That's very true.

I think possibly the best way to deal with this would be to invest
effort in improving `mumi`, with a `mumi apply` and better
`mumi send-email` functionality.

  -- (

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

[(]

kiasoc5@disroot.org writes:
> I would like to hear from committers if non-committer reviews are helpful,
> because I don't really know how or what I can comment on for incoming patches on
> packages I'm not really familiar with.

I'm not a committer, but I'd think it's helpful even if you just point
out style or formatting issues.  It's possible to comment on a package
even if you're not familiar with what it contains.

> Also do "this builds and works locally" comments help?

Yes too :)

  -- (

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

[Giovanni Biscuolo]

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

Liliana Marie Prikler <liliana.prikler@gmail.com> writes:

> Am Freitag, dem 25.08.2023 um 08:07 +0000 schrieb Attila Lendvai:
>> i couldn't even find out which tools are used by those who are
>> comfortable with the email based workflow. i looked around once, even
>> in the manual, but maybe i should look again.
> Users who have tried curlbash also looked at
>   wget https://issues.guix.gnu.org/issue/N/patch-set/M | git am -3

Is this documented somewhere plz?

I tried https://issues.guix.gnu.org/issue/65428/patch-set/1 but I get a
blank page: any example plz?

Thanks! Gio'

[...]

-- 
Giovanni Biscuolo

Xelera IT Infrastructures

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

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

[Simon Tournier]

Hi,

On Thu, 24 Aug 2023 at 02:18, Csepp <raingloom@riseup.net> wrote:

> By the way, that's another issue.  Using a TeX based document format for
> the docs is, uuuh, maybe not the best idea.  Info is a pretty okayish
> documentation reader, but it's a relatively big barrier to entry
> compared to what you need to know to make a small edit to the Arch wiki.
> This way mostly just experienced contributors write docs, not the
> users who just want to document how they made some weird use case
> possible.

Similarly as the term “contribution” is large, I would like to point
that the term “docs” is pointless here.  Are we comparing the Archi wiki
with printed-quality manual?  Somehow, there is a range of documentations
and they do not necessary require the same format.

Well, moreover, I think that the format is a fake problem.  To be
explicit, I also dislike the Texi format but the main reason why I do
not contribute much to any documentation kind is clearly not the format,
instead it is, by far far before, my first main reason is the task
appears to me boring and it barely fixes my immediate annoyances.

To be precise, I have between 5 and 10 items on my TODO list mentioning
“Improve the documentation for this” or “Write a blog post for that”.
It’s stuck not because the Texi format but because writing is hard.  For
instance, I could write to my blog using Org-mode format or to one of
the Guix blogs using Markdown format.

Now, if you speak about Fixing-Typo sort of contribution for the
documentation, I am sure that just pointing the section and the typo via
any mailing list or via IRC, and the typo will be fixed before the end
of the next hour. ;-)

Cheers,
simon

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

[Simon Tournier]

Hi,

On Fri, 25 Aug 2023 at 18:39, Katherine Cox-Buday <cox.katherine.e@gmail.com> wrote:

> 2. Remember the email address (it might seem silly unless you have forms 
> of dyslexia. is it guix-patches? or patches-guix? Wait, what was I doing?)
> 3. And then the whole deal with what to do with follow ups.

For what it is worth, I am using Emacs-Notmuch for reading emails and it
provides the key “c G” for stashing the email address.  For instance,
applying to your message:

--to="Katherine Cox-Buday <cox.katherine.e@gmail.com>" --to="guix-devel@gnu.org" --cc="guix-devel@gnu.org" --in-reply-to="547c097a-d805-9a55-11d9-b0434327f89d@gmail.com"

Then, I am able to paste as argument for git-send-email or else.  Well,
it reduces the opportunity for a typo.

That’s said…

> I wrote some elisp to one-key apply patches from GNUS, but I guess my 
> point is: not everyone can do that. How are we to expect more 
> contributors if that, or something similar, is the barrier to entry?

…I agree that Debbugs is not the best system for managing patches.  Many
of us are ending with some custom helpers for working around the
annoyances.  And that seems an indicator that Debbugs is not the best
fit.

Cheers,
simon

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

[Simon Tournier]

Hi,

On Fri, 25 Aug 2023 at 09:31, Attila Lendvai <attila@lendvai.name> wrote:

> another thing worth pointing out here is that the harder it is to test
> a submitted patchset locally, the fewer non-committer reviews will
> happen.

First, please note that thanks to tireless Chris work about QA, testing
is not hard!  Currently, it is poorly documented.  For instance, you can
test using:

    guix time-machine \
      --url=https://git.guix-patches.cbaines.net/git/guix-patches \
      --branch=issue-123456 --disable-authentication \
      -- build <foo>

As discussed in the thread,

        Re: Update on automating testing of patches and qa.guix.gnu.org
        Christopher Baines <mail@cbaines.net>
        Mon, 07 Nov 2022 10:36:13 +0100
        id:877d07f6d5.fsf@cbaines.net
        https://yhetil.org/guix/877d07f6d5.fsf@cbaines.net
        https://lists.gnu.org/archive/html/guix-devel/2022-11

indeed, the pluming details could be hidden under a new Guix subcommand
or via a new Mumi subcommand.

Any help is welcome. :-)

Second, the bottleneck about reviewing and merging is not about how
difficult or easy it is, instead it is because that’s a boring task that
barely fixes the immediate annoyances.  Somehow, the root of the issue
is the feeling of “being accountable”.  Since the motivation is not
fungible, there is not easy and straightforward solution.  From my point
of view, what is behind Teams is one direction for trying to improve the
bottleneck about reviewing.

Cheers,
simon

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

[Giovanni Biscuolo]

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

Hi,

Josselin Poiret <dev@jpoiret.xyz> writes:

> Maxim Cournoyer <maxim.cournoyer@gmail.com> writes:
>
>> Texinfo is mostly just plain text until you learn about a few decorators
>> :-).  It gives us the info manuals that I find very nifty (it's like a
>> man page, but with hyperlinks and advanced navigation capabilities!) and
>> used across many GNU projects (e.g. coreutils, Emacs, Bash, GCC, GNU
>> Make, etc.)  I see it as a strength more than a weakness for the
>> project.
>
> I agree with Maxim here, I think the texinfo markup is important to be
> able to generate such a nice manual

my 2 cents...

I've studied and used (some less than others) many available
"lightweight markup language" for documentation purposes: LaTeX,
markdown (manu flavours), restructured-text, AsciiDoc, org-mode, Texinfo

in my experience markdown - thus every wiki periodically is the alleged
missing tool - is _not_ suited at all for documentation, it lacks so
many _semantics_ needed for documentation purposes.

given that markdown (and a wiki) is not suitable for the task of
"writing good documentation", more or less all other markup languages
are of good quality, including Texinfo

additionally, Texinfo can be browsed directly - I mean without being
transformed in the final output format - by several programs [1], some
of them packaged in Guix: emacs, info-reader, pinfo, khelpcenter (GUI),
yelp (GUI); quite good choiche of Texinfo readers.

after all, Texinfo is a wise choiche IMO.

[...]

Happy hacking, Gio'



P.S.: not that Texinfo is the best /document programming framework/
(yes: the book is a program), the best ones are skribilo (Guile) and
Pollen (https://docs.racket-lang.org/pollen/)... and org-mode publish
:-)


[1] https://en.wikipedia.org/wiki/Info_(Unix)#List_of_Info_readers

-- 
Giovanni Biscuolo

Xelera IT Infrastructures

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

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

[Simon Tournier]

Hi,

On Sat, 26 Aug 2023 at 19:42, kiasoc5@disroot.org wrote:

> I would like to hear from committers if non-committer reviews are 
> helpful, because I don't really know how or what I can comment on for 
> incoming patches on packages I'm not really familiar with.

Well, I do not have enough committer experience.  However, I commented
several patches and my aim was the one I would like to see for helping
me as committer before pushing.

Because I am signing-off the commit, it is my responsibility to check
that the commit is compliant with Guix standards.  So, whatever I will
read as other review, I will check myself.  However, if another person
has also checked, it helps me because it avoids me to double or
triple-check in order to be sure I am not missing something.  Somehow,
another person looking at the patch reinforces my confidence that all is
fine.  Other said, without diluting the responsibility, it dilutes the
pressure, somehow.

Well, from my point of view, the comment “build locally“ is not very
helpful.  The comment “work locally” is a bit more.  IMHO, the most
helpful appears to me, in that order:

 1. the check of license – sometime upstream says the license is GPL
    when it’s true for most of the code but a tiny subpart uses some
    non-free license, such comment is very helpful.

 2. the good writing of synopsis and description.

 3. the ’home-page’ field is correct.

 4. some comments about the ’arguments’ field.

And the next level appears to me:

 5. apply the comments about #2 or #3 or #4 and re-send another version
    (reroll-count).  That’s what committers are often doing and except
    some cases, that is not a co-author ship. :-)


Cheers,
simon

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

[Simon Tournier]

Hi Katherine,

On Fri, 25 Aug 2023 at 19:02, Katherine Cox-Buday <cox.katherine.e@gmail.com> wrote:

> I think there's utility in distinguishing between familiarity and 
> eliminating toil. I think it was incorrect of me to suggest forming 
> habits in my original message. I think it's better to focus on 
> eliminating toil so that whatever workflow remains can more easily be 
> habituated.

Since I am French, I am good as moaner and I would like to avoid the
ramblings of some grumble party. :-)

I agree with you that it is important to reflect ourselves about our
practises and we need to be critical about what does not suit us.

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.

It could be a starting point for something going to etc/ similarly as
etc/committer.scm or etc/teams.scm.  Well, etc/guix-install.sh somehow
started as a script for eliminating toil – it looks similar as the
situation: all the steps are described in the manual but they are too
many effort for installing and most newcomer were dropping before
completing.


Cheers,
simon

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

[Giovanni Biscuolo]

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

Hi,

interesting thread: thank you very much to all for the comments and
tips!

For email based patch workflow one and two things are indispensable: a
mailbox and a MUA capable of piping a message to a command (git am);
this is the one and only obstacle for contrubutors who are accustomed to
less than functional MUAs.

https://git-send-email.io/ is a good primer for the braves.

On the "cognitive overhead" for users like me who are able to (very)
seldom send some patch to projects, I find it much more straightforward
to just send a "git format-patch" generated file via email than to open
a web browser, log-in (or worst: register), fork... naah! 

On the general topic of "email vs. web (fork and PR) patch management" I
found this articles useful and interesting:

- «How I Learned to Love the Email Patch Developer Workflow» by Emily Shaffer
https://nasamuffin.github.io/git/open-source/email/code-review/2019/05/22/how-i-learned-to-love-email-patches.html

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

With some tooling and good practices, I found a workflow that I love - and found myself arguing in defense of emailed patches!

[...]

* Responding to Comments

Note: As with Gerrit and other iterative code review tools based around a Git workflow, making your changes involves using interactive rebase. I won’t cover that here, as it’s not significantly different from other processes, and it’s complex enough to take its own tutorial.

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

- «Code review at the speed of email» by "Drew DeVault"
https://drewdevault.com/2022/07/25/Code-review-with-aerc.html

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

With hundreds of hours of review experience on GitHub, GitLab, and SourceHut, I can say with confidence the email workflow allows me to work much faster than any of the others. I can review small patches in seconds, work quickly with multiple git repositories, easily test changes and make tweaks as necessary, rebase often, and quickly chop up and provide feedback for larger patches. Working my way through a 50-email patch queue usually takes me about 20 minutes, compared to an hour or more for the same number of merge requests.

This workflow also works entirely offline.

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

- «The advantages of an email-driven git workflow» by Drew DeVault
https://drewdevault.com/2018/07/02/Email-driven-git.html

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

Email isn’t as sexy as GitHub (and its imitators), but it has several advantages over the latter. Email is standardized, federated, well-understood, and venerable. A very large body of email-related software exists and is equally reliable and well-understood. You can interact with email using only open source software and customize your workflow at every level of the stack - filtering, organizing, forwarding, replying, and so on; in any manner you choose.

[...] Given that most popular email clients these days are awful and can’t handle basic tasks like “sending email” properly, I strongly recommend this tool (git-send-email) over attempting to send format-patch’s output yourself.

[...] You can also set the default recipient for a given repository by using a local git config: git config sendemail.to admin@example.org. This lets you skip a step if you send your patches to a consistent destination for that project, like a mailing list. I also recommend git config --global sendemail.annotate yes, which will always open the emails in your editor to allow you to make changes (you can get this with --annotate if you don’t want it every time).

[...] The difficult part can be getting the email to git am in the first place. If you simply use the GMail web UI, this can be difficult.

[...] The main disadvantage of email driven development is that some people are more comfortable working with email in clients which are not well-suited to this kind of work. Popular email clients have caused terrible ideas like HTML email to proliferate, not only enabling spam, privacy leaks, and security vulnerabilities, but also making it more difficult for people to write emails that can be understood by git or tolerated by advanced email users.

I don’t think that the solution to these problems is to leave these powerful tools hanging in the wind and move to less powerful models like GitHub’s pull requests.

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

宋文武 <iyzsong@envs.net> writes:

> Maxim Cournoyer <maxim.cournoyer@gmail.com> writes:

[...]

>> For more information, try: 'guix shell info-reader u-boot -- info
>> "(u-boot) Patman patch manager"'
>
> Oh, patman look interesting for long series, will learn it later..

[...]

>> Using an Emacs-based workflow:
>>
>> 1. C-u M-x debbugs-gnu RET guix-patches RET [then answer prompts]
>> 2. M-x cd RET ~/src/guix or wherever is your guix checkout
>> 3. Select series you want to apply
>> 4. Sort by subject
>
> Also can first read on issues (mumi), find a issue ID,
> then M-x gnus-read-ephemeral-emacs-bug-group ID.

[...]

> Don't know the 'C-u 10 |' one, cool, thank you!

I feel like a section in the Cookbook about email based workflows would
be useful to many, even one with just excertps from this thread.

Happy hacking! Gio'

-- 
Giovanni Biscuolo

Xelera IT Infrastructures

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

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

[Liliana Marie Prikler]

Am Montag, dem 28.08.2023 um 10:15 +0200 schrieb Giovanni Biscuolo:
> Liliana Marie Prikler <liliana.prikler@gmail.com> writes:
> 
> > Am Freitag, dem 25.08.2023 um 08:07 +0000 schrieb Attila Lendvai:
> > > i couldn't even find out which tools are used by those who are
> > > comfortable with the email based workflow. i looked around once,
> > > even
> > > in the manual, but maybe i should look again.
> > Users who have tried curlbash also looked at
> >   wget https://issues.guix.gnu.org/issue/N/patch-set/M | git am -3
> 
> Is this documented somewhere plz?
> 
> I tried https://issues.guix.gnu.org/issue/65428/patch-set/1 but I get
> a blank page: any example plz?
That's a mumi bug IIUC, it works for M > 1.  For M = 1, use patch-set
without /M.

Cheers

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

[paul]

Hi Katherine ,

thank you for bringing this up. I too am somewhat of a contributor since 
about 2019 and I completely agree with your points. From reading this 
discussion it appears sourcehut supporting both the web and email 
workflow and being free software is really the best solution. It appears 
to have no downsides (besides for the work required for packaging and 
provisioning the service) and everything else either does not support 
email workflow or does not support web workflow.

What are the blockers in Guix's policies for moving in this direction? 
Should a team with a defined roadmap be created to address Katherine's 
and all other people's point, either way the consensus will fall?

giacomo

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

[paul]

Hi,

>> This definitely falls into the IDE tooling issue that I complained about
>> a bunch of times. There seems to be a reality distortion field around
>> Lisp that makes some users believe that s-expressions automatically lead
>> to a good IDE experience. And yet, Java IDEs have had automatic import
>> management for at least 15 years (around the time I first used Eclipse),
>> but Guile still doesn't have anything of the sort.
>> It looks like the only way to move forward is for people to share these
>> helper scripts they've been using and forging them into a consistent
>> developer environment, maybe based on Guile Studio. Hopefully I can
>> make some contributions towards such a project.
> I fully agree with this. I'd also add that everything seems to be emacs
> focused and not being an emacs user is kind of an extra barrier for people.
> (I'm not an emacs user)

I finally reached the conclusion that the only feasible way out of emacs 
to a modern IDE is LSP. There's an implementation here [0] (and a client 
[1]) that's supposedly working for basic features like Jump to 
Definition but I still haven't managed to make it work on Guix. There's 
also an issue to add it to Guix mainstream [2].

Hope this helps!

giacomo


[0]: https://codeberg.org/rgherdt/scheme-lsp-server

[1]: https://codeberg.org/rgherdt/vscode-scheme-lsp

[2]: https://issues.guix.gnu.org/60286

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

[Maxim Cournoyer]

Hi,

Saku Laesvuori <saku@laesvuori.fi> writes:

[...]

> I agree on the ChangeLogs being a weird thing to require in commit
> messages. I think of commit messages as the place where you record the
> reasons behind the change in the commit. The ChangeLog seems to just
> record the changes which the diff of the commit already automatically
> records more accurately.
>
> If someone has use cases for the ChangeLog commits, I'd like to hear
> them. Maybe there is something that can't be achieved with git history
> without ChangeLogs, but I can't think of anything. Someone mentioned
> grepping the git log with them, but I think the same thing can be done
> with git log and git blame regardless of the commit message format.

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.

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).

-- 
Thanks,
Maxim

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

[Giovanni Biscuolo]

Ciao Giacomo,

I never used nor installed/administered sourcehut services, I've some
questions about them:

paul <goodoldpaul@autistici.org> writes:

> From reading this discussion it appears sourcehut supporting both the
> web and email workflow and being free software is really the best
> solution.

sourcehut is a suite including this tools providing different services
(some of them already covered by specialized tools in Guix, e.g. CI):

- builds.sr.ht
- git.sr.ht
- hg.sr.ht
- hub.sr.ht
- lists.sr.ht
- man.sr.ht
- meta.sr.ht
- pages.sr.ht
- paste.sr.ht
- todo.sr.ht

git.sr.ht is the tool needed for "web workflow" patch management, it's
documented here: https://man.sr.ht/git.sr.ht/#sending-patches-upstream


git.sr.ht provides a web-based patch preparation UI, which you can use to prepare changes to send upstream online. You can even use this to prepare patches for projects that use email for submission, but are not hosted on SourceHut. This tool may be helpful to users who are used to the "pull request" style contribution popularized by GitHub, GitLab, and others.


yesterday I sent a message (id:87il8z9yw8.fsf@xelera.eu) with some
pointers to related articles, two were from Drew DeVault, sourcehut
founder

in the "Tutorials" page I find the section "Contributing to projects on
SourceHut" [1] and the "Read more" link point to
https://git-send-email.io/




> It appears to have no downsides (besides for the work
> required for packaging and provisioning the service) and everything
> else either does not support email workflow or does not support web
> workflow.
>
> What are the blockers in Guix's policies for moving in this direction? 
> Should a team with a defined roadmap be created to address Katherine's 
> and all other people's point, either way the consensus will fall?
>
> giacomo
>

[1] https://man.sr.ht/tutorials/#contributing-to-srht-projects

-- 
Giovanni Biscuolo

Xelera IT Infrastructures

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

[MSavoritias]

Just some remarks here,

Liliana Marie Prikler <liliana.prikler@gmail.com> writes:

> Am Freitag, dem 25.08.2023 um 08:07 +0000 schrieb Attila Lendvai:
>> i couldn't even find out which tools are used by those who are
>> comfortable with the email based workflow. i looked around once, even
>> in the manual, but maybe i should look again.
> Users who have tried curlbash also looked at
>   wget https://issues.guix.gnu.org/issue/N/patch-set/M | git am -3
>
>> i'm pretty sure most maintainers have a setup where the emailed
>> patches can be applied to a new branch with a single press of a
>> button, otherwise it'd be hell of a time-waster.
> Well, it's several keys, actually, but as others have already pointed
> out, keyboard > mouse.
>
That is a subjective thing and its posed as something that is not. We
should all be open to being wrong.

>> 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.
>
Using Emacs with mu4e its also bad to deal with lots of patches here too
:) Now having worked with Gitlab for example the UI is not as chaotic.
Aside from the "Gitlab is proprietary" argument which is NOT the
point. The point is how do we make it as easy as that for the people
that dont want to customize their email clients for optimal "threading"
capabilities?

>> > But someone would have to write and maintain them...
>> 
>> 
>> there are some that have already been written. here's an ad-hoc list
>> of references:
>> 
>> #github #gitlab #alternative
>> https://codeberg.org/
>> https://notabug.org/
>> https://sourcehut.org/
>> https://sr.ht/projects
>> https://builds.sr.ht/
>> https://git.lepiller.eu/gitile
>> codeberg.org is gitea and sr.ht is sourcehut
> Gitile is (as far as I'm aware) not yet a full forge.  It also hasn't
> loaded for me in ages, but I digress.
>
> It doesn't suffice if you just integrate any of those forges into the
> pre-existing workflow somehow.  You must also make it a pleasant
> experience for everyone involved.  This is similar to the issue that
> already bugs our Matrix<->IRC bridge.  
>
> Other implicit assumptions include that people will be happy to switch
> for the particular fork you've chosen (they won't) and will not demand
> $new_hot_thing within the next five years (they likely will, just look
> at the ChatGPT-related stuff that has been submitted).  There sadly is
> no pleasing everyone here and unless these tools are incredibly simple
> to maintain, the utilitarian approach of least misery leads you to
> plain email.
>
Also this is sounds like you think the other person just follows fashion
and you are the one that follows the "enlightened" way because you use
email. This is not the discussion we are having and we don't treat
people as less if they dont use terminal, emails or emacs or whatever
else you find amazing or whatever.

MSavoritias
> Cheers

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

[Giovanni Biscuolo]

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

[I sent this message incomplete by mistake, sorry!]

Ciao Giacomo,

I never used nor installed/administered SourceHut services, I've some
comments from what I learned reading documentation and articles.

Executive summary: it's "just" and **interface** problem; contributors
who like the SourceHut web UI to format and send patchsets via email are
very wellcome to subscribe and use the SourceHut services to send
patches (also) to Guix [1].  There is no reason for Guix to be
(self)hosted on SourceHut.

Also, like there are manu TUI for Git, there are also many Git GUIs
around https://git-scm.com/downloads/guis, maybe some of them also have
a "patch preparation UI" like the Git SourceHut web service.

paul <goodoldpaul@autistici.org> writes:

> From reading this discussion it appears sourcehut supporting both the
> web and email workflow and being free software is really the best
> solution.

SourceHut is a suite including this tools providing different services
(some of them already covered by specialized tools in Guix, e.g. CI):

- builds.sr.ht
- git.sr.ht
- hg.sr.ht
- hub.sr.ht
- lists.sr.ht
- man.sr.ht
- meta.sr.ht
- pages.sr.ht
- paste.sr.ht
- todo.sr.ht

git.sr.ht have a tool for "web-based patch preparation UI", it's
documented [1]: that tool is "just" a web interface to prepare a
patchset to be sent upstream via email; please read all the section and
you'll see that it describes an email based patch management workflow.

Also, in the "Tutorials" page I find the section "Contributing to
projects on SourceHut" [1] and the "Read more" link point to
https://git-send-email.io/

Finally, yesterday I sent a message (id:87il8z9yw8.fsf@xelera.eu) with
some pointers to related articles, two were from Drew DeVault, SourceHut
founder

Given what I found above, I'd say that the workflow model used by
SourceHut hosted projects is email based, not web based, and that the
service "git.sr.ht" provides SourceHut users "just" a web UI helping
them to format and send a patchset via email in the same way "git
format-patch" and "git send-email" do.

...it's "just" an _interface_ question, not an email vs web patch
management question :-)

That said, I understand that some (many?) users are not comfortable with
CLI interfaces and prefers a GUI interface (web UI is the same), but
there is no reason to increase the reviewers cognitive overhead by
introducing an inefficient web based patch management workflow just to
address a "simple" and unrelated interface problem.

> It appears to have no downsides (besides for the work required for
> packaging and provisioning the service)

First, let's start with packaging each SourceHut service in Guix: AFAIU
packaging in other distros is not in good shape, i.e.

- Debian
  https://packages.debian.org/search?keywords=sourcehut&searchon=names&suite=all&section=all
  https://wiki.debian.org/Teams/pkg-sourcehut

- Arch Linux
  https://archlinux.org/packages/?sort=&q=sourcehut&maintainer=&flagged=

- Fedora
  https://packages.fedoraproject.org/search?query=sourcehut

Sure, they have https://man.sr.ht/packages.md for Alpine Linux, Arch
Linux and Debian, but:

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

Warning: SourceHut is still in alpha, and has no stable releases. As such, we do not recommend packaging SourceHut for your upstream distribution repositories until we have shipped stable versions of our software.

--8<---------------cut here---------------end--------------->8---
(from https://man.sr.ht/packages.md)

So we have to wait for SourceHut to exit its alpha status to start
packaging it, no?

> and everything else either does not support email workflow or does not
> support web workflow.

I insist: SourceHut does _not_ support a "web workflow" (fork, PR and
merge all done via a web UI)

> What are the blockers in Guix's policies for moving in this direction?

Guix is a GNU project, GNU have an infrastructure, a set of services and
a policy for their projects.  Maybe one day GNU will provide a self
hosted SourceHut service, now GNU have https://savannah.gnu.org/ and
https://debbugs.gnu.org/

...and please remember: "all forges and all issue trackers suck, some
just sucks less" (stolen from mutt motto)

> Should a team with a defined roadmap be created to address Katherine's 
> and all other people's point, either way the consensus will fall?

First it would be useful to separate each /different/ question raised in
dedicated threads that are actionable, possibly leading to a patch or at
least to a consensus... or to some sort of clarification at least.

I hope I helped to clarify the "email vs web patch management" question
with this message.

Ciao! Gio'


[1] https://man.sr.ht/git.sr.ht/#sending-patches-upstream

[2] https://man.sr.ht/tutorials/#contributing-to-srht-projects

-- 
Giovanni Biscuolo

Xelera IT Infrastructures

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

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

[MSavoritias]

Simon Tournier <zimon.toutoune@gmail.com> writes:

> Hi,
>
> On Fri, 25 Aug 2023 at 18:39, Katherine Cox-Buday <cox.katherine.e@gmail.com> wrote:
>
>> 2. Remember the email address (it might seem silly unless you have forms 
>> of dyslexia. is it guix-patches? or patches-guix? Wait, what was I doing?)
>> 3. And then the whole deal with what to do with follow ups.
>
> For what it is worth, I am using Emacs-Notmuch for reading emails and it
> provides the key “c G” for stashing the email address.  For instance,
> applying to your message:
>
> --to="Katherine Cox-Buday <cox.katherine.e@gmail.com>" --to="guix-devel@gnu.org" --cc="guix-devel@gnu.org" --in-reply-to="547c097a-d805-9a55-11d9-b0434327f89d@gmail.com"
>
> Then, I am able to paste as argument for git-send-email or else.  Well,
> it reduces the opportunity for a typo.
>
> That’s said…
>
>> I wrote some elisp to one-key apply patches from GNUS, but I guess my 
>> point is: not everyone can do that. How are we to expect more 
>> contributors if that, or something similar, is the barrier to entry?
>
> …I agree that Debbugs is not the best system for managing patches.  Many
> of us are ending with some custom helpers for working around the
> annoyances.  And that seems an indicator that Debbugs is not the best
> fit.
>

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.

MSavoritias

> Cheers,
> simon

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

[MSavoritias]

Liliana Marie Prikler <liliana.prikler@gmail.com> writes:

> Hi,
>
> Am Sonntag, dem 27.08.2023 um 16:57 +0300 schrieb Saku Laesvuori:
>> > > 
>> > not sure how most people consume their emails nowadays, but for me
>> > it's one flat list per thread, in a browser (i.e. it's not a tree).
>> 
>> The point is that the emails contain the information on how to
>> construct a tree out of them. It's just that most web clients (which
>> most people are unfortunately using nowadays) are so bad that they
>> render the tree as a flat list.
> Not sure about "most", but Guix folk are definitely biased towards
> dedicated mail clients (terminal, graphical, Emacs…), so perhaps my own
> perception was a little off in that people will always benefit from
> having the tree.  Then again, you can share your email between multiple
> clients, which isn't that easy to do with code repositories sadly.  
>
> Of course, you can mirror the repo, but your bug trackers aren't that
> easily mirrored.
>
>> 
>> > and all i'm trying to achieve here is to move the discussion away
>> > from email-is-superior-period, to look at what requiremenets we
>> > have and what tools satisfy them, if any.
>> 
>> I think that is a good discussion to have, but I think it would be
>> better to describe some of the requirements you think we should
>> consider instead of just saying email isn't superior. It might not
>> be, but it might also be. We should consider what we need and
>> evaluate the available tools based on that, and if the result is that
>> email is the best then it is.
> Not needing to register yet another account for one-off contributions
> is an argument that kills all the forges, sadly :)
>
With Sourcehut you can contribute without an account.
There is also https://forgefed.org/ which is for federated forges using
activitypub. So you can have one account for all forges that
federate. :D

MSavoritias
>> > > at the ChatGPT-related stuff that has been submitted). There
>> > > sadly is no pleasing everyone here and unless these tools are
>> > > incredibly simple to maintain, the utilitarian approach of least
>> > > misery leads you to plain email.
>> > 
>> > but is a least-misery model appropriate here? how do you even
>> > account for the contributions that could have happened in a
>> > different environment, but did not happen?
>> > 
>> > similarly, e.g. demanding a dated ChangeLog format for commit
>> > messages has a filtering effect on who will contribute, and then
>> > who will stick around. most engineers have a hard time jumping
>> > through hoops that they find pointless (git automatically encodes
>> > that information), and i'd suggest considering what the effect are
>> > of such rules on Guix asan emergent order.
>> 
>> I agree on the ChangeLogs being a weird thing to require in commit
>> messages. I think of commit messages as the place where you record
>> the reasons behind the change in the commit. The ChangeLog seems to
>> just record the changes which the diff of the commit already
>> automatically records more accurately.
> First things first, I disagree with the framing here.  Engineers do
> pointless things all the time and both code style and commit message
> style have near endless potential for bikeshedding (which we are
> currently engaged in btw).  There are like thirteen competing standards
> on how to format C code and similar debates in other languages.  In
> fact, I'd go so far as to argue that a language ecosystem that has no
> such debate is potentially lacking in diversity.
>
> A proper ChangeLog doesn't simply "record the changes the diff already
> records more accurately".  It adds semantics.  For instance, when
> bumping a package, we write the same line twice; once for the header,
> once for the ChangeLog.  What we don't write is that we also adjusted
> the hash along with the version.  Doing so would give us no new
> information, but the diff includes it anyway, because diffs are stupid.
> Humans writing (and reading) ChangeLogs aren't stupid and can rely on
> contextual meta-information – however, the ChangeLog should still be
> self-contained in the sense that it doesn't rely on other parts of the
> message to infer the actual changes made.
>
>> If someone has use cases for the ChangeLog commits, I'd like to hear
>> them. Maybe there is something that can't be achieved with git
>> history without ChangeLogs, but I can't think of anything. Someone
>> mentioned grepping the git log with them, but I think the same thing
>> can be done with git log and git blame regardless of the commit
>> message format.
> In my humble opinion, you underestimate the benefits of not having to
> invoke another command on a commit.  For a great number of changes, the
> ChangeLog style allows me to imagine the code that was written without
> having to see it in a way that a simple diffstat just can't.  Of
> course, whether you use ChangeLog style commit messages, Emoji commits
> or any other formatting guide is a political question between everyone
> involved in a project, but there are benefits to having guidelines and
> following them.  
>
> It's similar to following generally accepted etiquette in any circle. 
> People will generally be happy as long as you follow them and can often
> tolerate small deviations, but at a certain point it just becomes
> uncomfortable, so we kindly ask you to follow the established
> practices.
>
> Cheers

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

[Giovanni Biscuolo]

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

Hi

MSavoritias <email@msavoritias.me> writes:

[...]

>> Not needing to register yet another account for one-off contributions
>> is an argument that kills all the forges, sadly :)
>>
> With Sourcehut you can contribute without an account.

Because they use an email based patch send/review workflow :-)

In other words: you can contribute to a SourceHut hosted project with
patches (or just with comments to patches) because everyone can send an
email to an email address provided by the project maintainer(s).

> There is also https://forgefed.org/ which is for federated forges using
> activitypub. So you can have one account for all forges that
> federate. :D

Interesting project, for now the supported (implementations) are:

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

- Vervis is the reference implementation of ForgeFed. It serves as a demo platform for testing the protocol and new features.

- Forgejo is implementing federation.

- Pagure has an unmaintained ForgeFed plugin.

--8<---------------cut here---------------end--------------->8---
(via https://forgefed.org/)

Funny thing is that on the main Vervis instance
(https://vervis.peers.community/browse) they say: «NOTE: Federation is
disabled on this instance!»

Let's say this federation project is stil in early alpha... and probably
we will never see an implementation in GitHub: WDYT?!? :-O

Anyway, since the SourceHut patch management medium is email, it's
federated by default.

Happy hacking! Gio'

[...]

-- 
Giovanni Biscuolo

Xelera IT Infrastructures

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

git interfaces (was Re: How can we decrease the cognitive overhead for contributors?)

[Giovanni Biscuolo]

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

Giovanni Biscuolo <g@xelera.eu> writes:

[...]

> Executive summary: it's "just" and **interface** problem; contributors

"an interface problem"

> who like the SourceHut web UI to format and send patchsets via email are
> very wellcome to subscribe and use the SourceHut services to send
> patches (also) to Guix [1].  There is no reason for Guix to be
> (self)hosted on SourceHut.
>
> Also, like there are manu TUI for Git,

"there are many"

> there are also many Git GUIs
> around https://git-scm.com/downloads/guis, maybe some of them also have
> a "patch preparation UI" like the Git SourceHut web service.

For example, I see that git-cola (https://git-cola.github.io/) have an
interface to apply patches [1] (the user still needs a way to download
the patches to apply them) but AFAIU it does not have an interface for
"git format-patch"; I guess it should not be too hard to add it as a
custom GUI action [2]

Could git-cola be a tool to help people who dislike CLI/TUI tools
contribute to Guix (or other email based patch management projects)
smootly?

[...]

Best regards, Gio'


[1] https://git-cola.readthedocs.io/en/latest/git-cola.html#apply-patches

[2] https://git-cola.readthedocs.io/en/latest/git-cola.html#custom-gui-actions

-- 
Giovanni Biscuolo

Xelera IT Infrastructures

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

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

[Liliana Marie Prikler]

Hi,

Am Dienstag, dem 29.08.2023 um 12:29 +0300 schrieb MSavoritias:
> 
> Just some remarks here,
> 
> Liliana Marie Prikler <liliana.prikler@gmail.com> writes:
> 
> > Am Freitag, dem 25.08.2023 um 08:07 +0000 schrieb Attila Lendvai:
> > > i couldn't even find out which tools are used by those who are
> > > comfortable with the email based workflow. i looked around once,
> > > even
> > > in the manual, but maybe i should look again.
> > Users who have tried curlbash also looked at
> >   wget https://issues.guix.gnu.org/issue/N/patch-set/M | git am -3
> > 
> > > i'm pretty sure most maintainers have a setup where the emailed
> > > patches can be applied to a new branch with a single press of a
> > > button, otherwise it'd be hell of a time-waster.
> > Well, it's several keys, actually, but as others have already
> > pointed out, keyboard > mouse.
> > 
> That is a subjective thing and its posed as something that is not. We
> should all be open to being wrong.
I mean, my comment was meant to be tongue-in-cheek and I'm not a UX
expert, so you might want to consult those, but there appears to be a
shared experience of many hackers that the keyboard is often better at
getting the things you want done done.

> > > 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.
> > 
> Using Emacs with mu4e its also bad to deal with lots of patches here
> too :) 
> Now having worked with Gitlab for example the UI is not as
> chaotic.
> Aside from the "Gitlab is proprietary" argument which is NOT the
> point. The point is how do we make it as easy as that for the people
> that dont want to customize their email clients for optimal
> "threading" capabilities?
To be fair, Gitlab is on the better forges out there, also allowing you
to interact with issues via email for one.  It also has decent support
for threads.  However, apart from being proprietary and thus not likely
adopted by any GNU project serious about software freedom, 

> > > > But someone would have to write and maintain them...
> > > 
> > > 
> > > there are some that have already been written. here's an ad-hoc
> > > list
> > > of references:
> > > 
> > > #github #gitlab #alternative
> > > https://codeberg.org/
> > > https://notabug.org/
> > > https://sourcehut.org/
> > > https://sr.ht/projects
> > > https://builds.sr.ht/
> > > https://git.lepiller.eu/gitile
> > > codeberg.org is gitea and sr.ht is sourcehut
> > Gitile is (as far as I'm aware) not yet a full forge.  It also
> > hasn't loaded for me in ages, but I digress.
> > 
> > It doesn't suffice if you just integrate any of those forges into
> > the pre-existing workflow somehow.  You must also make it a
> > pleasant experience for everyone involved.  This is similar to the
> > issue that already bugs our Matrix<->IRC bridge.  
> > 
> > Other implicit assumptions include that people will be happy to
> > switch for the particular fork you've chosen (they won't) and will
> > not demand $new_hot_thing within the next five years (they likely
> > will, just look at the ChatGPT-related stuff that has been
> > submitted).  There sadly is no pleasing everyone here and unless
> > these tools are incredibly simple to maintain, the utilitarian
> > approach of least misery leads you to plain email.
> > 
> Also this is sounds like you think the other person just follows
> fashion and you are the one that follows the "enlightened" way
> because you use email. This is not the discussion we are having and
> we don't treat people as less if they dont use terminal, emails or
> emacs or whatever else you find amazing or whatever.
There is no singular "other person" here.  There is people, a plural,
and people as a group are very well influenced through fashion.  Of
course, there's some stochastics involved; people wearing adidas from
head to toe don't tend to frequent the same places as elegant gothic
lolita aristocrat vampires.  Indeed, the people now choosing sourcehut
may still do so in five years (though some might choose something
else).  However, the people demanding any other interface in those five
years will undoubtedly be influenced by whatever will be popular then.

I also don't necessarily blame the people making these demands for
doing so; from their perspective it makes sense to demand something
that's "easier to work with".  However, there is some shortsightedness 
to their demand and it has nothing to do with the enlightenment that
one achieves or doesn't achieve when using email (ironic, considering
that most people out of necessity have an email even if they prefer
$hot_instant_messaging_trend or $"outdated"_instant_messaging_niche or
whatever it is that they actually prefer).  Thus, I ask you to consider
that catering to the whims of fashion, even if it doesn't appear to be
catering on the surface, is perhaps not the best strategy.

Cheers

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

[Csepp]

Maxim Cournoyer <maxim.cournoyer@gmail.com> writes:

> Hi,
>
> Csepp <raingloom@riseup.net> writes:
>
> [...]
>
>> but as soon as something breaks, you are thrown into the deep end,
>> having to dissect logs, bisect commit ranges, learn strace, gdb (which
>> still doesn't work well on Guix)
>
> Hm?  Why GDB on Guix may be sometimes more challenging than say, on
> Fedora, I only know of one problem, that is related to grafts (see: #48907).
>
> For running binaries wrapped in shell script, I have this 'run-gdb'
> wrapper which reads:
>
> --8<---------------cut here---------------start------------->8---
> #!/usr/bin/env bash
>
> wrapper=$(cat $(which $1))
> shift
> . <(echo "$wrapper" | grep ^export)
> binary=$(echo "$wrapper" | grep ^exec | grep -o -E '/gnu/store[^"]*')
> gdb --args "$binary" "$@"
> --8<---------------cut here---------------end--------------->8---
>
> Hope that helps,

Thanks, it does somewhat, but this is the kind of thing that should be
either packaged in Guix, documented in the cookbook, or preferably fixed
upstream.
At the very least I try to document these helper Guix-specific helper
scripts on the mailing list.  I've asked where it would be appropriate
to put them (cookbook, package, guix module, etc) but I don't think I
got a response.
This is exactly what I mean by core devs having their own scripts that
others don't have an easy way to find and/or access.

The other problem is the difficulty of accessing debug symbols.
One problem is the need to recompile the package you need symbols for,
the other is loading external symbols.  The first is a CI issue as far
as I know: all the debug outputs would take up too much space
(probably).  This may not be fixable in the short term without
additional funding.  The second is purely technical though.
Maybe someone fixed it since the last time I tried to use GDB, but if
not, it should be a priority IMHO.  Guix packages often have bugs and we
should do everything in our power to make fixing future problems easier,
otherwise the project risks the death of a thousand cuts.
This is why I chose to work on Mirage, to get a better understanding of
the importer and cross-compilation tooling.

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

[Csepp]

Giovanni Biscuolo <g@xelera.eu> writes:

> ...
>> What are the blockers in Guix's policies for moving in this direction?
>
> Guix is a GNU project, GNU have an infrastructure, a set of services and
> a policy for their projects.  Maybe one day GNU will provide a self
> hosted SourceHut service, now GNU have https://savannah.gnu.org/ and
> https://debbugs.gnu.org/
>
> ...and please remember: "all forges and all issue trackers suck, some
> just sucks less" (stolen from mutt motto)

I hope GNU is not so inflexible that it won't support Guix if it
switches to a better maintained forge.

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

[Danny Milosavljevic]

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

Hi,

> review" because of the amount of cognitive overhead required. I've written
> a script for myself that tries to perform all the steps including running
> the git command to submit the patch, and this has helped me, but that this
> is necessary for me to do might be something that, if addressed, could
> help others.

I agree that automating the technical steps of contributing to Guix
would be nice.

I suggest that we preinstall a script that does the equivalent of this:

if [ ! -d guix ]
  then
    git clone --depth=1
    https://git.savannah.gnu.org/git/guix.git guix
  else
    (cd guix && git pull --rebase)
  fi \
  && cd guix
  && guix shell -C -D guix -- ./bootstrap \
  && guix shell -C -D guix -- ./configure --localstatedir=/var
  --disable-daemon \
  && guix shell -C -D guix -- make -j5 \
  && ./pre-inst-env guix edit "$@" \
  && git add gnu/packages/*.scm

Also, we should automate adding an smtp server (after ascertaining that port
25 localhost is not open or something? Not sure.):

git config --global sendemail.smtpencryption tls
git config --global sendemail.smtpserver mail.messagingengine.com
git config --global sendemail.smtpuser foo@example.com
git config --global sendemail.smtpserverport 587
git config --global sendemail.smtppass hackme

There's even a file guix/etc/git/gitconfig already--aha!

This would reduce the barrier to entry a lot.

It's unfortunate that for example pre-inst-env doesn't work correctly (for
me; checked on multiple computers) when you don't invoke "make" beforehand
(sometimes it just picks up the wrong guix and doesn't say anything!). On the
other hand, using a guix.scm anywhere else works without make.

If I do "guix edit xyz" it opens a file in /gnu/store that I can't edit.
Not sure what good that is.

It would be better to ask and then automatically suggest invoking the script
above that prepares a guix development environment.

It's kinda weird we don't just have a "guix contrib" subcommand or something
that automates basic things that any guix contributor needs.

> I can't ever seem to get the GNU style commit messages correct.

Writing the metadata into the commit messages is annoying. It totally should
be automated, especially since Scheme has pretty simple syntax (so it should
be easy to write such a thing/famous-last-words). It should just figure out
which procedures the changed lines were in, automatically.
(This probably does exist in emacs)

Because of the line-based nature of the diff tools and of a lot of git tools, we
do need to have which procedure was changed in the git commit message,
though.

> I don't use the email-based patch workflow day-to-day, so this is another
> area where I spend a lot of time trying to make sure I'm doing things
> correctly.

Especially since one needs to the debbugs dance where one first opens a new
bug report by sending an email to guix-patches@gnu.org, waits for an ID to
be mailed to you, only after that to reply to <ID>@debbugs.gnu.org,
attaching the patches (copying the message-id from the old mail manually as
a reference). That is such a weird workaround for a debbugs limitation.

This definitely should be automated. Why not generate a UUID locally and send
a mail to <UUID>@debbugs.gnu.org ? That may require changes to debbugs,
though.

> manually managing Guile imports is laborious. As a fledgling schemer, I
> often forget which imports I needed just for development. 

Yeah. I like that we now tell the user whether imports are unused, and also
which import it could most likely be if it's missing. But automating the cleanup
and adding like it is in Java IDEs would totally be awesome. With a language
as dynamic as Guile I think this problem is intractable since you can never be
sure someone dynamically does (or doesn't) need the import.
Can still be approximated.

I attached some changes to guix to make the contributor experience less bad.
It doesn't look nice but it does work and I even prefer that workflow myself now.

@Ludo: What do you think?

> Does this affect anyone else?

The basic setup affects one only when one changes workstations--which I suspect
is why it wasn't improved until now. It's just too rare a problem per person. But it's a
very bad barrier of entry for new contributors, and there's no reason for it to be there!

But the other annoyances totally affect me all the time, too.

Cheers,
     Danny

P.S. We could also do git config --local alias.send-patches 'git send-email -r origin/master --cover-letter --annotate --to=guix-patches@gnu.org'

[-- Attachment #2: 0001-guix-scripts-Add-contrib-script.patch --]
[-- Type: text/x-diff, Size: 17732 bytes --]

From 10f16b0b3cf47931db5c9607b95872f477550422 Mon Sep 17 00:00:00 2001
Message-Id: <10f16b0b3cf47931db5c9607b95872f477550422.1693350103.git.dannym@scratchpost.org>
From: Danny Milosavljevic <dannym@scratchpost.org>
Date: Wed, 30 Aug 2023 00:50:00 +0200
Subject: [PATCH] guix: scripts: Add "contrib" script.

* guix/scripts/contrib.scm: New file.
* guix/scripts/edit.scm (spawn-editor): Mention new command "guix contrib" if applicable.
* manifest.scm: New file.
* doc/guix.texi (Invoking guix contrib): New node.
---
 doc/guix.texi            |  17 +++
 guix/scripts/contrib.scm | 266 +++++++++++++++++++++++++++++++++++++++
 guix/scripts/edit.scm    |  53 ++++----
 manifest.scm             |   1 +
 4 files changed, 316 insertions(+), 21 deletions(-)
 create mode 100644 guix/scripts/contrib.scm
 create mode 100644 manifest.scm

diff --git a/doc/guix.texi b/doc/guix.texi
index f82bb99069..c626a5b8ba 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -327,6 +327,7 @@ Top
 
 * Invoking guix build::         Building packages from the command line.
 * Invoking guix edit::          Editing package definitions.
+* Invoking guix contrib::       Contributing changes to Guix.
 * Invoking guix download::      Downloading a file and printing its hash.
 * Invoking guix hash::          Computing the cryptographic hash of a file.
 * Invoking guix import::        Importing package definitions.
@@ -13773,6 +13774,22 @@ Invoking guix edit
 @var{directory}}) allows you to add @var{directory} to the front of the
 package module search path and so make your own packages visible.
 
+@node Invoking guix contrib
+@section Invoking @command{guix contrib}
+The @command{guix contrib edit} command allows new contributors to easily
+get started in contributing to guix.
+
+First, if @command{guix edit} ended up with a file in the store
+(which isn't editable), then guix will give a hint to use
+@command{guix contrib edit} instead.
+
+@command{guix contrib edit} will automatically check out Guix source code
+from version control, build it, optionally set up git in order to send email
+and generally prepare a contributors' machine.  Then it will give a hint
+to use @command {./pre-inst-env guix edit} in order to actually edit
+the file inside that new source code checkout of guix.  It will also give
+a hint on how to send the finished changes to us.
+
 @node Invoking guix download
 @section Invoking @command{guix download}
 
diff --git a/guix/scripts/contrib.scm b/guix/scripts/contrib.scm
new file mode 100644
index 0000000000..3c95293305
--- /dev/null
+++ b/guix/scripts/contrib.scm
@@ -0,0 +1,266 @@
+;;; GNU Guix --- Functional package management for GNU
+;;; Copyright © 2021-2023 Ludovic Courtès <ludo@gnu.org>
+;;; Copyright © 2023 Danny Milosavljevic <dannym@scratchpost.org>
+;;;
+;;; This file is part of GNU Guix.
+;;;
+;;; GNU Guix is free software; you can redistribute it and/or modify it
+;;; under the terms of the GNU General Public License as published by
+;;; the Free Software Foundation; either version 3 of the License, or (at
+;;; your option) any later version.
+;;;
+;;; GNU Guix is distributed in the hope that it will be useful, but
+;;; WITHOUT ANY WARRANTY; without even the implied warranty of
+;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+;;; GNU General Public License for more details.
+;;;
+;;; You should have received a copy of the GNU General Public License
+;;; along with GNU Guix.  If not, see <http://www.gnu.org/licenses/>.
+
+(define-module (guix scripts contrib)
+  #:use-module (guix ui)
+  #:use-module (guix diagnostics) ; #:select (location leave report-error)
+  #:use-module (guix scripts environment)
+  #:autoload   (guix scripts build) (show-build-options-help
+                                     show-native-build-options-help)
+  #:autoload   (guix transformations) (options->transformation
+                                       transformation-option-key?
+                                       show-transformation-options-help)
+  #:use-module (guix scripts)
+  #:use-module (guix git)
+  #:use-module (guix build utils)
+  #:use-module (guix packages)
+  #:use-module (guix profiles)
+  #:use-module (srfi srfi-1)
+  #:use-module (srfi srfi-26)
+  #:use-module (srfi srfi-37)
+  #:use-module (srfi srfi-71)
+  #:use-module (ice-9 match)
+  #:use-module (ice-9 popen)
+  #:use-module (ice-9 textual-ports)
+  #:autoload   (ice-9 rdelim) (read-line)
+  #:autoload   (guix base32) (bytevector->base32-string)
+  #:autoload   (rnrs bytevectors) (string->utf8)
+  #:autoload   (guix utils) (config-directory cache-directory)
+  #:autoload   (guix describe) (current-channels)
+  #:autoload   (guix channels) (channel-commit)
+  #:autoload   (gcrypt hash) (sha256)
+  #:use-module ((guix build utils) #:select (mkdir-p))
+  #:use-module (guix cache)
+  #:use-module ((ice-9 ftw) #:select (scandir))
+  #:autoload   (ice-9 pretty-print) (pretty-print)
+  #:autoload   (gnu packages) (cache-is-authoritative?
+                               package-unique-version-prefix
+                               specification->package
+                               specification->package+output
+                               specifications->manifest)
+  #:export (guix-contrib))
+
+(define (show-help)
+  (display (G_ "Usage: guix contrib edit PACKAGES...
+Create/update a development environment for guix and open a text editor with
+PACKAGES inside it.\n"))
+  (newline)
+
+  ;; These two options differ from 'guix environment'.
+
+  (display (G_ "
+  -h, --help             display this help and exit"))
+  (display (G_ "
+  -V, --version          display version information and exit"))
+  (newline)
+  (show-bug-report-information))
+
+;;; FIXME:
+
+(define (tag-package-arg opts arg)
+  "Return a two-element list with the form (TAG ARG) that tags ARG with either
+'ad-hoc' in OPTS has the 'ad-hoc?' key set to #t, or 'inputs' otherwise."
+  (if (assoc-ref opts 'ad-hoc?)
+      `(ad-hoc-package ,arg)
+      `(package ,arg)))
+
+(define (ensure-ad-hoc alist)
+  (if (assq-ref alist 'ad-hoc?)
+      alist
+      `((ad-hoc? . #t) ,@alist)))
+
+(define (wrapped-option opt)
+  "Wrap OPT, a SRFI-37 option, such that its processor always adds the
+'ad-hoc?' flag to the resulting alist."
+  (option (option-names opt)
+          (option-required-arg? opt)
+          (option-optional-arg? opt)
+          (compose ensure-ad-hoc (option-processor opt))))
+
+(define %options
+  ;; Specification of the command-line options.
+  (let ((to-remove '("ad-hoc" "inherit" "load" "help" "version")))
+    (append
+        (list (option '(#\h "help") #f #f
+                      (lambda args
+                        (show-help)
+                        (exit 0)))
+              (option '(#\V "version") #f #f
+                      (lambda args
+                        (show-version-and-exit "guix contrib"))))
+        (filter-map (lambda (opt)
+                      (and (not (any (lambda (name)
+                                       (member name to-remove))
+                                     (option-names opt)))
+                           (wrapped-option opt)))
+                    %environment-options))))
+
+(define %default-options
+ `())
+
+(define (parse-args args)
+  "Parse the list of command line arguments ARGS."
+  (define (handle-argument arg result)
+    (alist-cons 'package (tag-package-arg result arg)
+                (ensure-ad-hoc result)))
+
+  ;; The '--' token is used to separate the command to run from the rest of
+  ;; the operands.
+  (let ((args command (break (cut string=? "--" <>) args)))
+    (parse-command-line args %options (list %default-options))))
+
+(define (invoke-and-read . args)
+  "Invoke ARGS and read its stdout into a string"
+  (let* ((pipe (apply open-pipe* OPEN_READ args))
+         (result (string-trim-right (get-string-all pipe)))
+         (close-pipe pipe))
+    result))
+
+(define (ensure-git-setting name default-value)
+  (let ((current-value (invoke-and-read "git" "config" "--global" name)))
+    (format #t "Current setting of ~s is ~s~%" name current-value)
+    (let ((default-value (if (string=? current-value "") default-value current-value)))
+      (format #t "What value do you want for git setting ~s? [~a] " name default-value)
+      (force-output)
+      (let ((new-value (string-trim-right (read-line))))
+        (unless (string=? new-value current-value)
+          (invoke "git" "config" "--global" name (if (string=? new-value "") default-value new-value)))))))
+
+(define (configure-git)
+  ; Or just ask user to do `guix shell -C` in the guix checkout directory
+  (format #t "This will set up your user's git. If you don't want us to do that, cancel now.~%")
+
+  (if (string=? (invoke-and-read "git" "-h") "")
+      (exit 1))
+;      Please install `git'--for example by entering the guix environment using `guix shell -C'"
+
+  (if (string=? (invoke-and-read "git" "send-email" "-h") "")
+      (exit 1))
+ ;     (leave "Please install `git send-email'--for example by entering the guix environment using `guix shell -C'")
+
+  (ensure-git-setting "user.email" "")
+  (ensure-git-setting "user.name" "")
+
+  (ensure-git-setting "sendemail.smtpserver" "")
+  (ensure-git-setting "sendemail.smtpencryption" "tls")
+  (ensure-git-setting "sendemail.smtpserverport" "587")
+  (ensure-git-setting "sendemail.smtpuser" "")
+  (ensure-git-setting "sendemail.smtppass" ""))
+
+; duplicate
+(define (authorized-directory-file)
+  "Return the name of the file listing directories for which 'guix shell' may
+automatically load 'guix.scm' or 'manifest.scm' files."
+  (string-append (config-directory) "/shell-authorized-directories"))
+
+; duplicate
+(define (authorized-shell-directory? directory)
+  "Return true if DIRECTORY is among the authorized directories for automatic
+loading.  The list of authorized directories is read from
+'authorized-directory-file'; each line must be either: an absolute file name,
+a hash-prefixed comment, or a blank line."
+  (catch 'system-error
+    (lambda ()
+      (call-with-input-file (authorized-directory-file)
+        (lambda (port)
+          (let loop ()
+            (match (read-line port)
+              ((? eof-object?) #f)
+              ((= string-trim line)
+               (cond ((string-prefix? "#" line)   ;comment
+                      (loop))
+                     ((string-prefix? "/" line)   ;absolute file name
+                      (or (string=? line directory)
+                          (loop)))
+                     ((string-null? (string-trim-right line)) ;blank line
+                      (loop))
+                     (else                        ;bogus line
+                      (let ((loc (location (port-filename port)
+                                           (port-line port)
+                                           (port-column port))))
+                        (warning loc (G_ "ignoring invalid file name: '~a'~%")
+                                 line))))))))))
+    (const #f)))
+
+(define (prepare-guix-checkout destination-directory)
+  (mkdir-p destination-directory)
+  ; TODO: Somehow divine ssh URL ?
+  ; TODO: Resolve /gnu/store/w77psnbryxvpjxh54y1q7l7gby5dr5vk-guix-module-union/share/guile/site/3.0/gnu/packages/android.scm back to channel git url and commit; then check (at least) that out.
+  ;       So: iterate over channels; find where the source file corresponding to the package is?
+  ;       Then: Use starting-commit from the respective channel? Not sure what that's for in the first place
+  ;       Then: Dynamically set destination-directory
+  ; TODO: ref '(branch . "master")
+  ; TODO: --depth 1 or something
+  (update-cached-checkout "https://git.savannah.gnu.org/git/guix.git" #:ref '() #:cache-directory destination-directory)
+  ; More guix-environment* options:
+  ;  (package ad-hoc-package "nano")
+  ;  (ad-hoc? . #t)
+  ;  (system . "x86_64-linux")
+  ;  (substitutes? . #t)
+  ;  (symlinks)
+  ;  (offload? . #t)
+  ;  (graft? . #t)
+  ;  (print-build-trace? . #t)
+  ;  (print-extended-build-trace? . #t)
+  ;  (multiplexed-build-output? . #t)
+  ;  (debug . 0)
+  ;  (verbosity . 1)
+  (define (in-guix-checkout command)
+    (guix-environment* `((package package "guix") (ad-hoc? . #f) (debug . 0) (verbosity . 1) (exec . ,command)))) ; TODO: opts instead of '()
+
+  ;; Append destination-directory to (authorized-directory-file)
+  (unless (authorized-shell-directory? destination-directory)
+    (let ((output-port (open-file (authorized-directory-file) "a")))
+      (newline output-port)
+      (display destination-directory output-port)
+      (newline output-port)
+      (close output-port)))
+
+  ; TODO: ask whether to do a dev mode setup and hint that it will change user-global settings!
+  (format #t "Do you want to reconfigure the `git' version control system? (if you want to contribute your changes, this is useful) [y] ")
+  (force-output)
+  (let ((answer (string-trim-right (read-line))))
+    (when (or (string=? answer "y")
+              (string=? answer "yes"))
+      (configure-git)))
+
+  ; Build Guix
+  (in-guix-checkout '("sh" "-c" "./bootstrap && ./configure --localstatedir=/var --sysconfdir=/etc --disable-daemon && make -j"))
+  ; FIXME: we died because of the exec, but we still wanted to print a hint
+)
+
+
+\f
+(define-command (guix-contrib . args)
+  (category development)
+  (synopsis "contribute to Guix")
+
+  (with-error-handling
+    (define opts
+      (parse-args args))
+    (let ((arguments (reverse (filter-map (match-lambda ((argument . b) b)) opts))))
+      (match arguments
+       (("edit" packages ...)
+        (begin
+          (let ((destination-directory (string-append (getenv "HOME") "/src/guix")))
+            (prepare-guix-checkout destination-directory)
+            (display-hint (G_ "In the future, if you want a much faster workflow, please directly edit files in ~s and also invoke `./pre-inst-env guix ~a' in there.") destination-directory (string-join args " "))
+            (display-hint (G_ "If you are done and you want to email patches for review, you can use `git send-email -r origin/master --cover-letter --annotate' or similar."))
+            #t
+            )))))))
diff --git a/guix/scripts/edit.scm b/guix/scripts/edit.scm
index 5ce2870c5a..29e0fc4191 100644
--- a/guix/scripts/edit.scm
+++ b/guix/scripts/edit.scm
@@ -21,6 +21,7 @@
 (define-module (guix scripts edit)
   #:use-module (guix ui)
   #:use-module (guix scripts)
+  #:use-module (guix store)
   #:use-module ((guix scripts build) #:select (%standard-build-options))
   #:use-module ((guix diagnostics)
                 #:select (location-file location-line))
@@ -71,28 +72,38 @@ (define (search-path* path file)
              file path))
     absolute-file-name))
 
-(define (location->location-specification location)
-  "Return the location specification for LOCATION for a typical editor command
-line."
-  (list (string-append "+"
-                       (number->string
-                        (location-line location)))
-        (search-path* %load-path (location-file location))))
-
-(define (spawn-editor locations)
+(define (spawn-editor locations specs)
   "Spawn (%editor) to edit the code at LOCATIONS, a list of <location>
 records, and exit."
-  (catch 'system-error
-    (lambda ()
-      (let ((file-names (append-map location->location-specification
-                                    locations)))
-        ;; Use `system' instead of `exec' in order to sanely handle
-        ;; possible command line arguments in %EDITOR.
-        (exit (system (string-join (cons (%editor) file-names))))))
-    (lambda args
-      (let ((errno (system-error-errno args)))
-        (leave (G_ "failed to launch '~a': ~a~%")
-               (%editor) (strerror errno))))))
+
+  (let ((location->location-specification
+         (lambda (location)
+           "Return the location specification for LOCATION for a typical
+editor command line.  As a side-effect, if the LOCATION is a store path,
+leave with an error message."
+           (list (string-append "+"
+                                (number->string
+                                 (location-line location)))
+
+                 (let ((path (search-path* %load-path (location-file location))))
+                   (if (store-path? path)
+                       (leave (G_ " '~a' is not directly editable.~%
+Hint: Try 'guix contrib edit ~a' in order to prepare a Guix development environment
+in your home directory and edit it there.~%")
+                              path (string-join specs " "))
+                       path))))))
+
+    (catch 'system-error
+      (lambda ()
+        (let ((file-names (append-map location->location-specification
+                                      locations)))
+          ;; Use `system' instead of `exec' in order to sanely handle
+          ;; possible command line arguments in %EDITOR.
+          (exit (system (string-join (cons (%editor) file-names))))))
+      (lambda args
+        (let ((errno (system-error-errno args)))
+          (leave (G_ "failed to launch '~a': ~a~%")
+                 (%editor) (strerror errno)))))))
 
 \f
 (define-command (guix-edit . args)
@@ -111,4 +122,4 @@ (define-command (guix-edit . args)
       (when (null? specs)
         (leave (G_ "no packages specified, nothing to edit~%")))
 
-      (spawn-editor locations))))
+      (spawn-editor locations (parse-arguments)))))
diff --git a/manifest.scm b/manifest.scm
new file mode 100644
index 0000000000..00aaaae8e9
--- /dev/null
+++ b/manifest.scm
@@ -0,0 +1 @@
+(specifications->manifest '("git" "git:send-email"))

base-commit: 37a8f92340f45baf096629866354bd088475456a
-- 
2.39.2

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

[Maxim Cournoyer]

Hi Csepp,

Csepp <raingloom@riseup.net> writes:

> Maxim Cournoyer <maxim.cournoyer@gmail.com> writes:
>
>> Hi,
>>
>> Csepp <raingloom@riseup.net> writes:
>>
>> [...]
>>
>>> but as soon as something breaks, you are thrown into the deep end,
>>> having to dissect logs, bisect commit ranges, learn strace, gdb (which
>>> still doesn't work well on Guix)
>>
>> Hm?  While GDB on Guix may be sometimes more challenging than say, on
>> Fedora, I only know of one problem, that is related to grafts (see: #48907).
>>
>> For running binaries wrapped in shell script, I have this 'run-gdb'
>> wrapper which reads:
>>
>> --8<---------------cut here---------------start------------->8---
>> #!/usr/bin/env bash
>>
>> wrapper=$(cat $(which $1))
>> shift
>> . <(echo "$wrapper" | grep ^export)
>> binary=$(echo "$wrapper" | grep ^exec | grep -o -E '/gnu/store[^"]*')
>> gdb --args "$binary" "$@"
>> --8<---------------cut here---------------end--------------->8---
>>
>> Hope that helps,
>
> Thanks, it does somewhat, but this is the kind of thing that should be
> either packaged in Guix, documented in the cookbook, or preferably fixed
> upstream.
> At the very least I try to document these helper Guix-specific helper
> scripts on the mailing list.  I've asked where it would be appropriate
> to put them (cookbook, package, guix module, etc) but I don't think I
> got a response.
> This is exactly what I mean by core devs having their own scripts that
> others don't have an easy way to find and/or access.

I think a "Debugging with GDB" section in the Cookbook showcasing such
script would be a good option.  Patches welcome!

> The other problem is the difficulty of accessing debug symbols.
> One problem is the need to recompile the package you need symbols for,
> the other is loading external symbols.  The first is a CI issue as far
> as I know: all the debug outputs would take up too much space
> (probably).

We have tons of disk space on Berlin, at least.  I don't think it'd be
an issue at least there (not sure about Bordeaux).  We could also look
into having our debug symbols de-duplicated with something like dwz
(https://sourceware.org/mailman/listinfo/dwz) to make them smaller, or
see if Fedora does something smart in this regard.

> This may not be fixable in the short term without
> additional funding.  The second is purely technical though.
> Maybe someone fixed it since the last time I tried to use GDB, but if
> not, it should be a priority IMHO.  Guix packages often have bugs and we
> should do everything in our power to make fixing future problems easier,
> otherwise the project risks the death of a thousand cuts.

Loading external (such as from linked libraries?) symbols should work,
provided they are in the profile you're working with, that gdb is there,
and that it has access to the default ~/.guile file (e.g. not in a
container), so that it automatically set 'debug-file-directory' for you,
from the GDB_DEBUG_FILE_DIRECTORY environment variable.

Also, build the profile with --no-grafts to avoid the bug mentioned
earlier (#48907).

-- 
Thanks,
Maxim

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

[Giovanni Biscuolo]

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

Liliana Marie Prikler <liliana.prikler@gmail.com> writes:

[...]

>> I tried https://issues.guix.gnu.org/issue/65428/patch-set/1 but I get
>> a blank page: any example plz?
> That's a mumi bug IIUC, it works for M > 1.  For M = 1, use patch-set
> without /M.

OK, thanks!

-- 
Giovanni Biscuolo

Xelera IT Infrastructures

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

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

[Attila Lendvai]

> That said, I understand that some (many?) users are not comfortable with
> CLI interfaces and prefers a GUI interface (web UI is the same), but
> there is no reason to increase the reviewers cognitive overhead by
> introducing an inefficient web based patch management workflow just to
> address a "simple" and unrelated interface problem.


IMO the crux of the issue here is not so much the UI, but the underlying data model, because it sets the limitations for everything that may be built on top of it.

for now the two contenders seem to be, basically, 1) git and 2) mailbox. 

a PR is just a git branch with extras. it's worth noting that git already provides scriptable CLI tools for dealing with branches and remotes.

and 1) is not better because there already exist different webuis for PR management, but because of the future tools and scripts that it makes possible relative to 2).

and i, for one, would be open to hack on something that is written in scheme and uses the former data model, but i'd never touch something like debbugs. i'm not sure that this is a general sentiment around here, but i suspect that i'm not alone with this.

ideally, there should be something like mumi, maybe mumi itself, that is officially sanctioned and is easy to start up locally to hack on. then frustrated contributors could write out their frustration into its source code (compunding benefit for all!) instead of the mailing list (consuming attention without much benefits).

just now i wanted to take a look at mumi's sources, but the link in the manual (https://git.elephly.net/gitweb.cgi?p=software/mumi.git) times out.

--
• 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?

[Andreas Enge]

Am Wed, Aug 30, 2023 at 08:39:17AM +0000 schrieb Attila Lendvai:
> just now i wanted to take a look at mumi's sources, but the link in the manual (https://git.elephly.net/gitweb.cgi?p=software/mumi.git) times out.

There is a mumi package in guix, and it gives the source location as
   https://git.savannah.gnu.org/git/guix/mumi.git/
So this has become an official guix subproject!

Andreas

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

[Andreas Enge]

Am Wed, Aug 30, 2023 at 02:22:01AM +0200 schrieb Danny Milosavljevic:
> Writing the metadata into the commit messages is annoying. It totally should
> be automated, especially since Scheme has pretty simple syntax (so it should
> be easy to write such a thing/famous-last-words). It should just figure out
> which procedures the changed lines were in, automatically.

It does exist inside git itself for C code; "git diff" always shows the
function in which I make a change. I agree it should be easy to have the
same support for scheme.

Andreas

commit message helpers (was Re: How can we decrease the cognitive overhead for contributors?)

[Giovanni Biscuolo]

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

Hello,

Andreas Enge <andreas@enge.fr> writes:

> Am Wed, Aug 30, 2023 at 02:22:01AM +0200 schrieb Danny Milosavljevic:
>> Writing the metadata into the commit messages is annoying. It totally should
>> be automated, especially since Scheme has pretty simple syntax (so it should
>> be easy to write such a thing/famous-last-words). It should just figure out
>> which procedures the changed lines were in, automatically.
>
> It does exist inside git itself for C code; "git diff" always shows

in the hunk header

> the function in which I make a change.

Does this mean that the function/procedure of the specific language - C
in this case - is/can be automatically provided in the generated draft
commit message by parsing the "git diff" output?

> I agree it should be easy to have the same support for scheme.

The documentation for this git feature is here:
«Defining a custom hunk-header»
https://git-scm.com/docs/gitattributes#_defining_a_custom_hunk_header

All is needed is to enable one of the built in patterns via
.gitattributes; in the Guix git root we defined this:

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

*.scm       diff=scheme
*.scm.in    diff=scheme
*.texi      diff=texinfo

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

This means that when doing "git diff" in a Guix worktree we get
something like:

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

[~/{git}/giovanni.biscuolo.net/guix/gnu/packages]
giovanni@roquette: git diff
diff --git a/gnu/packages/abiword.scm b/gnu/packages/abiword.scm
index 1635ed54fd..a9c937c39b 100644
--- a/gnu/packages/abiword.scm
+++ b/gnu/packages/abiword.scm
@@ -56,7 +56,7 @@ (define-public abiword
           (string-append "https://www.abisource.com/downloads/abiword/" version
                          "/source/abiword-" version ".tar.gz"))
         (sha256
-         (base32 "1d1179pnslijpjhz1q155fsc828rrlqf7lsn2inqsl3hk5z28mqj"))
+         (base32 "BOGUS"))
         (patches
          (search-patches "abiword-explictly-cast-bools.patch"))))
 
@@ -67,7 +67,7 @@ (define-public abiword
           "--enable-clipart"     ;; TODO: The following plugins have unresolved
           "--enable-templates"   ;; dependencies: aiksaurus, grammar, wpg, gda,
           (string-append         ;; wordperfect, psion, mathview.
-            "--enable-plugins="
+            "--enable-plugins= FIXME"
               "applix " "babelfish " "bmp " "clarisworks " "collab " "command "
               "docbook " "eml " "epub " "freetranslation " "garble " "gdict "
               "gimp " "goffice " "google " "hancom " "hrtext " "iscii " "kword "

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

In the example above have two hunk headers:

1. @@ -56,7 +56,7 @@ (define-public abiword

2. @@ -67,7 +67,7 @@ (define-public abiword

each one showing the function I modified.

Furthermore, "git diff -W" (or --function-context) will show the whole
function in the hunk:

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

[~/{git}/giovanni.biscuolo.net/guix/gnu/packages]
giovanni@roquette: git --no-pager diff -W
diff --git a/gnu/packages/abiword.scm b/gnu/packages/abiword.scm
index 1635ed54fd..a9c937c39b 100644
--- a/gnu/packages/abiword.scm
+++ b/gnu/packages/abiword.scm
@@ -48,89 +48,89 @@ (define-module (gnu packages abiword)
 (define-public abiword
   (package
     (name "abiword")
     (version "3.0.5")
     (source
       (origin
         (method url-fetch)
         (uri
           (string-append "https://www.abisource.com/downloads/abiword/" version
                          "/source/abiword-" version ".tar.gz"))
         (sha256
-         (base32 "1d1179pnslijpjhz1q155fsc828rrlqf7lsn2inqsl3hk5z28mqj"))
+         (base32 "BOGUS"))
         (patches
          (search-patches "abiword-explictly-cast-bools.patch"))))
 
     (build-system glib-or-gtk-build-system)
     (arguments                   ;; NOTE: rsvg is disabled, since Abiword
       `(#:configure-flags        ;; supports it directly, and its BS is broken.
         (list                    ;; wmf was removed from Guix for security.
           "--enable-clipart"     ;; TODO: The following plugins have unresolved
           "--enable-templates"   ;; dependencies: aiksaurus, grammar, wpg, gda,
           (string-append         ;; wordperfect, psion, mathview.
-            "--enable-plugins="
+            "--enable-plugins= FIXME"
               "applix " "babelfish " "bmp " "clarisworks " "collab " "command "

[...]

     (license license:gpl2+)))

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

As you can see, here the hunk header is:

3. @@ -48,89 +48,89 @@ (define-module (gnu packages abiword)

showing the function in with "define-public abiword" is defined.

I don't know if this is/could be used to automatically set a more helpful
commit message draft, but this helps to "figure out which procedures the
changed lines were in, automatically."

WDYT?

Also, I can't find if there is some plan or feature request to add
tree-sitter support in the "git diff" parser, but that could be a great
improvement IMO, since it will allow git users to use all tree-sitter
available parsers and not just pattern matching to understand/show the
context in which the changes happened.

In this context, I found this two currently active project of
tree-sitter based diff tools:

1. Difftastic https://difftastic.wilfred.me.uk/

2. diffsitter https://github.com/afnanenayet/diffsitter

Both can be used as external "git difftool"s [1] [2]

None is currently packaged in Guix.


Happy hacking! Gio'


[1] https://difftastic.wilfred.me.uk/git.html#git-difftool

[2] https://github.com/afnanenayet/diffsitter#git-integration

-- 
Giovanni Biscuolo

Xelera IT Infrastructures

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

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

[Katherine Cox-Buday]

Summary of my conclusions:

1. We should use sourcehut or continue to improve mumi
    - QA status should be visable from a patch's page
    - It should be possible to interact with the issue through the page

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

3. We should reify a way for Guix, the project, to measure, and track 
progress,
    against long-term goals. Particularly when they're social and not 
strictly
    technical.

On 8/28/23 4:17 AM, Simon Tournier wrote:
 > Hi Katherine,
 >
 > On Fri, 25 Aug 2023 at 19:02, Katherine Cox-Buday 
<cox.katherine.e@gmail.com> wrote:
 >
 >> I think there's utility in distinguishing between familiarity and
 >> eliminating toil. I think it was incorrect of me to suggest forming
 >> habits in my original message. I think it's better to focus on
 >> eliminating toil so that whatever workflow remains can more easily be
 >> habituated.
 >
 > Since I am French, I am good as moaner and I would like to avoid the
 > ramblings of some grumble party. :-)
 >
 > I agree with you that it is important to reflect ourselves about our
 > practises and we need to be critical about what does not suit us.
 >
 > 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.

[I'm usually starting here]

   4. Run `./pre-inst-env guix refresh --list-dependent <package>`
   5. Create a git worktree for your patch
   6. Run `./bootstrap`, then `./configure --localstatedir=/var 
--sysconfdir=/etc`
   7. Run `make`
   8. Make your changes
   9. Build to ensure your changes are workable.
   10. Try and determine how your changes should be factored into individual
       commits (sometimes it's not always so clear when changing two 
things might
       need to be done atomically).
   11. Try and get each commit message close to correct and commit.
   12. Run `guix lint`
   13. Run `guix style` (this is still in the manual although I have since
       learned this is not actually advisable).
   14. Review the changes these tools have made, and fix things.
   15. Run `guix build --rounds=2 <package>` to check for idempotency.
   16. Run `make` to ensure you didn't break anything elsewhere in Guix.
   17. Run `guix size` to ensure the closure isn't becoming bloated.
   18. Build all the packages that depend on this package.
   19. Run `guix pull --url=/path/to/your/checkout 
--profile=/tmp/guix.master` to
       ensure you didn't break Guix in a different way.
   20. Run `git format-patch -1 --cover-letter [--reroll-count]`
   21. Run `./pre-inst-env ./etc/teams.scm cc-members <patch>` to get 
the CC flags for Git
   22. Remember that if you're sending multiple patches, an email first 
has to be
       sent to `guix-patches@gnu.org` to get an ID, and then...
   23. Run `git send-email --to guix-patches <patches> <CC flags>`

I view steps 1-10 as pretty standard "development" steps common to most
projects, although 11 compounds the effort in 10.

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 not feasible due to asymmetric resources. But having the
option to let CI manage this process is very nice.

For me, steps 20-23 are bothersome. There's a lot of "if" statements 
that lead
to branching operations, and a lot of commands and flags to get right. 
The extra
step to get a debbugs ID is annoying.

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.
   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.

So now that I've enumerated the steps, compared them to contributing to 
projects
I don't find difficult, and reflected on the difference for awhile, I 
think, at
least for me, the highest friction comes from:

- Steps 11-19, or (to assign it a name for easier reference) the "CI steps".

   As I understand it, we're continuing to make progress in having a nice CI
   pipeline (i.e. https://qa.guix.gnu.org), so maybe I need to read more 
about
   that. If we wanted to encourage contributors to run "CI steps" 
locally before
   submitting, maybe this should be another `guix` sub-command? `guix 
pre-check`
   or something? I know there is a potential contributor who had this 
idea first
   who would want to hack on this.

- Steps 19-23, or the "manage patch" steps.

   I think an insight here is that the big button on forges is actually 
a program
   removing the mental overhead for you. It (1) notices you've pushed a 
branch
   when you visit the website and suggests opening a PR with a link. (2) 
Submits
   the PR with appropriate settings (3) Recommends reviewers which you 
can add
   after the fact.

   Also, this workflow doesn't change whether you have one commit or two 
in your
   branch, and it doesn't doesn't change when you need to submit 
follow-ups (e.g.
   changing flags on `git format-patch`).

   I also don't usually have to worry nearly as much about crafting a commit
   message. So long as the title is under a character limit, and the body is
   helpful, it's OK. I think what bothers me most about the GNU changelog
   messages is that it's the worst of both spoken language and programming
   languages: there's an expectation of structure, but no grammar I can 
parse
   against, and it's free-form.

   I would probably have to learn more about it before making this 
assertion, but
   it also seems like any information it provides can be fetched from 
git. And
   when it comes to the steps to contributing, the answer is "memorize these
   flags", but when it comes to retrieving this information, the answer 
is "this
   is easier". I'm not sure about this is a fair comparison, but it might be
   something to collectively reflect on.

- Having multiple places to manage aspects of my patch

   In a web-forge, I generally have a URL I can go to and see everything 
about my
   patch. I think we have that with https://issues.guix.gnu.org with two
   exceptions: (1) QA is a click away, or if you're using email, you're 
not even
   aware that there's a QA process failing (2) If you're not using email,
   context-switching between this page and email to respond.

 > It could be a starting point for something going to etc/ similarly as
 > etc/committer.scm or etc/teams.scm.  Well, etc/guix-install.sh somehow
 > started as a script for eliminating toil – it looks similar as the
 > situation: all the steps are described in the manual but they are too
 > many effort for installing and most newcomer were dropping before
 > completing.

Yeah, after sitting with this a bit, I think this, or new Guix 
sub-commands, is
probably a good path forward. The way I'm thinking about this is that we 
need to
lift the individual steps into higher-order activities and have the 
higher-order
activities encapsulate flags and whatnot.

Thinking about all of this, I am reminded of this[1] picture. If we want 
more
contributions to Guix, we have to do better at providing equitable ways 
to work.
Focusing on this benefits everyone because it makes contributing easier for
everyone.

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.

And finally, I'm wondering how Guix, the project, tracks metrics on 
these kinds
of things? If we wanted to make contributing easier, that's something we 
have to
create a metric for and track over time. Is there a precedent for this 
in Guix?

[1] 
https://external-content.duckduckgo.com/iu/?u=https%3A%2F%2Fwww.lrhsd.org%2Fcms%2Flib%2FNJ01000316%2FCentricity%2FDomain%2F1239%2FEquity%2520graphic.jpg&f=1&nofb=1&ipt=507d2c18cd2643bcb9ba2a67a13dc86d1926301212aaf04bcefc3d17571f982e&ipo=images 

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

[Andreas Enge]

Hello Katherine,

thanks for your summary, which contains many points I would agree with and
actionable items (disclaimer: I do not promise to act on them).

Am Wed, Aug 30, 2023 at 10:11:02AM -0600 schrieb Katherine Cox-Buday:
> Here's my understanding of the process to contribute a patch:

My process is actually a bit easier...

>   5. Create a git worktree for your patch
>   6. Run `./bootstrap`, then `./configure --localstatedir=/var
> --sysconfdir=/etc`

You can drop 6 assuming you do not create a new .scm file.
Instead of 5, I usually just branch off from master, or simply work on
master itself (for instance, for a simple package update). In the latter
case, after creating and sending the patches, a
"git reset --hard origin/master" drops all my work.

>   8. Make your changes
>   9. Build to ensure your changes are workable.
>   10. Try and determine how your changes should be factored into individual
>       commits (sometimes it's not always so clear when changing two things
> might
>       need to be done atomically).
>   11. Try and get each commit message close to correct and commit.

Usually I start with 10, and then make the changes incrementally.
For instance, today I wanted to update a package and change an input.
I simply changed the input first, built and made a commit.
And then I updated the package, built and invoked ./etc/committer.scm.

Admittedly, I also do not do all the checks you mention, like closure
sizes or reproducibility of the builds.

Andreas

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

[MSavoritias]

Yep completely agree with all of this.
Personally I dont think its necessery to move to sourcehut but from the
discussions I saw debbugs does seem to become a burden the more time
passes on.

One of the weirdest things for me in guix is how its based on scheme
which is designed to be hacked in place and instead we have so many
complicated steps to do it.

A much more logical thing as bare minimmum is like you said: Have it as
a subcommand in guix. The first thing i tried to do to contribute
personally was to just do a 'guix edit' and edit the package but turns
out not only i cant do it as easy as that but I also need to clone a
repo and run multiple scripts inside a container(?). We should work on
moving as close to a 'guix edit' and 'mumi push' contribution as
possible.

MSavoritias

Katherine Cox-Buday <cox.katherine.e@gmail.com> writes:

> Summary of my conclusions:
>
> 1. We should use sourcehut or continue to improve mumi
>    - QA status should be visable from a patch's page 
>    - It should be possible to interact with the issue through the page
>
> 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
>
> 3. We should reify a way for Guix, the project, to measure, and track
> progress,
>    against long-term goals. Particularly when they're social and not
> strictly
>    technical.
>
> On 8/28/23 4:17 AM, Simon Tournier wrote:
>> Hi Katherine,
>>
>> On Fri, 25 Aug 2023 at 19:02, Katherine Cox-Buday
>   <cox.katherine.e@gmail.com> wrote:
>>
>>> I think there's utility in distinguishing between familiarity and
>>> eliminating toil. I think it was incorrect of me to suggest forming
>>> habits in my original message. I think it's better to focus on
>>> eliminating toil so that whatever workflow remains can more easily be
>>> habituated.
>>
>> Since I am French, I am good as moaner and I would like to avoid the
>> ramblings of some grumble party. :-)
>>
>> I agree with you that it is important to reflect ourselves about our
>> practises and we need to be critical about what does not suit us.
>>
>> 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.
>
> [I'm usually starting here]
>
>   4. Run `./pre-inst-env guix refresh --list-dependent <package>`
>   5. Create a git worktree for your patch
>   6. Run `./bootstrap`, then `./configure --localstatedir=/var
> --sysconfdir=/etc`
>   7. Run `make`
>   8. Make your changes
>   9. Build to ensure your changes are workable.
>   10. Try and determine how your changes should be factored into individual
>       commits (sometimes it's not always so clear when changing two
> things might
>       need to be done atomically).
>   11. Try and get each commit message close to correct and commit.
>   12. Run `guix lint`
>   13. Run `guix style` (this is still in the manual although I have since
>       learned this is not actually advisable).
>   14. Review the changes these tools have made, and fix things.
>   15. Run `guix build --rounds=2 <package>` to check for idempotency.
>   16. Run `make` to ensure you didn't break anything elsewhere in Guix.
>   17. Run `guix size` to ensure the closure isn't becoming bloated.
>   18. Build all the packages that depend on this package.
>   19. Run `guix pull --url=/path/to/your/checkout
> --profile=/tmp/guix.master` to
>       ensure you didn't break Guix in a different way.
>   20. Run `git format-patch -1 --cover-letter [--reroll-count]`
>   21. Run `./pre-inst-env ./etc/teams.scm cc-members <patch>` to get
> the CC flags for Git
>   22. Remember that if you're sending multiple patches, an email first
> has to be
>       sent to `guix-patches@gnu.org` to get an ID, and then...
>   23. Run `git send-email --to guix-patches <patches> <CC flags>`
>
> I view steps 1-10 as pretty standard "development" steps common to most
> projects, although 11 compounds the effort in 10.
>
> 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 not feasible due to asymmetric resources. But having the
> option to let CI manage this process is very nice.
>
> For me, steps 20-23 are bothersome. There's a lot of "if" statements
> that lead
> to branching operations, and a lot of commands and flags to get
> right. The extra
> step to get a debbugs ID is annoying.
>
> 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.
>   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.
>
> So now that I've enumerated the steps, compared them to contributing
> to projects
> I don't find difficult, and reflected on the difference for awhile, I
> think, at
> least for me, the highest friction comes from:
>
> - Steps 11-19, or (to assign it a name for easier reference) the "CI steps".
>
>   As I understand it, we're continuing to make progress in having a nice CI
>   pipeline (i.e. https://qa.guix.gnu.org), so maybe I need to read
> more about
>   that. If we wanted to encourage contributors to run "CI steps"
> locally before
>   submitting, maybe this should be another `guix` sub-command? `guix
> pre-check`
>   or something? I know there is a potential contributor who had this
> idea first
>   who would want to hack on this.
>
> - Steps 19-23, or the "manage patch" steps.
>
>   I think an insight here is that the big button on forges is actually
> a program
>   removing the mental overhead for you. It (1) notices you've pushed a
> branch
>   when you visit the website and suggests opening a PR with a
> link. (2) Submits
>   the PR with appropriate settings (3) Recommends reviewers which you
> can add
>   after the fact.
>
>   Also, this workflow doesn't change whether you have one commit or
> two in your
>   branch, and it doesn't doesn't change when you need to submit
> follow-ups (e.g.
>   changing flags on `git format-patch`).
>
>   I also don't usually have to worry nearly as much about crafting a commit
>   message. So long as the title is under a character limit, and the body is
>   helpful, it's OK. I think what bothers me most about the GNU changelog
>   messages is that it's the worst of both spoken language and programming
>   languages: there's an expectation of structure, but no grammar I can
> parse
>   against, and it's free-form.
>
>   I would probably have to learn more about it before making this
> assertion, but
>   it also seems like any information it provides can be fetched from
> git. And
>   when it comes to the steps to contributing, the answer is "memorize these
>   flags", but when it comes to retrieving this information, the answer
> is "this
>   is easier". I'm not sure about this is a fair comparison, but it might be
>   something to collectively reflect on.
>
> - Having multiple places to manage aspects of my patch
>
>   In a web-forge, I generally have a URL I can go to and see
> everything about my
>   patch. I think we have that with https://issues.guix.gnu.org with two
>   exceptions: (1) QA is a click away, or if you're using email, you're
> not even
>   aware that there's a QA process failing (2) If you're not using email,
>   context-switching between this page and email to respond.
>
>> It could be a starting point for something going to etc/ similarly as
>> etc/committer.scm or etc/teams.scm.  Well, etc/guix-install.sh somehow
>> started as a script for eliminating toil – it looks similar as the
>> situation: all the steps are described in the manual but they are too
>> many effort for installing and most newcomer were dropping before
>> completing.
>
> Yeah, after sitting with this a bit, I think this, or new Guix
> sub-commands, is
> probably a good path forward. The way I'm thinking about this is that
> we need to
> lift the individual steps into higher-order activities and have the
> higher-order
> activities encapsulate flags and whatnot.
>
> Thinking about all of this, I am reminded of this[1] picture. If we
> want more
> contributions to Guix, we have to do better at providing equitable
> ways to work.
> Focusing on this benefits everyone because it makes contributing easier for
> everyone.
>
> 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.
>
> And finally, I'm wondering how Guix, the project, tracks metrics on
> these kinds
> of things? If we wanted to make contributing easier, that's something
> we have to
> create a metric for and track over time. Is there a precedent for this
> in Guix?
>
> [1]
> https://external-content.duckduckgo.com/iu/?u=https%3A%2F%2Fwww.lrhsd.org%2Fcms%2Flib%2FNJ01000316%2FCentricity%2FDomain%2F1239%2FEquity%2520graphic.jpg&f=1&nofb=1&ipt=507d2c18cd2643bcb9ba2a67a13dc86d1926301212aaf04bcefc3d17571f982e&ipo=images

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

[Imran Iqbal]

On Mon, Aug 28, 2023 at 01:42:15PM +0200, Giovanni Biscuolo wrote:
> Hi,
>
> interesting thread: thank you very much to all for the comments and
> tips!

Seconded, this has been a great thread to read through.

> For email based patch workflow one and two things are indispensable: a
> mailbox and a MUA capable of piping a message to a command (git am);
> this is the one and only obstacle for contrubutors who are accustomed to
> less than functional MUAs.

I think this is the biggest hurdle. A lot of folks are using gmail and
its web based UI and it is just plain awful. I have made the switch to
using neomutt (and isync + notmuch + mstmp) and it has made emails a joy
to use and work with.

> On the "cognitive overhead" for users like me who are able to (very)
> seldom send some patch to projects, I find it much more straightforward
> to just send a "git format-patch" generated file via email than to open
> a web browser, log-in (or worst: register), fork... naah!

This also has the nice side effect of not having to worry about if you
should force push or not to maintain a clean commits the web ui, and in
general I find the email flow to promote better commit hygiene.

> On the general topic of "email vs. web (fork and PR) patch management" I
> found this articles useful and interesting:

One thing I would to this is Linus's rant on the github style workflow,
as seen in a hard to follow list style UI:
https://github.com/torvalds/linux/pull/17

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

[Giovanni Biscuolo]

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

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 <cox.katherine.e@gmail.com> 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 not feasible due to asymmetric resources. But having the
> option to let CI manage this process is very nice.

AFAIU this is where https://qa.guix.gnu.org/ is intended to help, but
now is not working as intended AFAIU

> For me, steps 20-23 are bothersome. There's a lot of "if" statements 
> that lead
> to branching operations, and a lot of commands and flags to get
> right.

oh yes, CLI is a cognitive overhead sometimes, so we need better
interfaces, some have found them

actually, point 21 "Run `./pre-inst-env ./etc/teams.scm cc-members
<patch>` to get the CC flags for Git" is bothersome and we should find a
way to better integrate that in "git format-patch" (so that will be
automatically used in all the git interfaces we use)

> The extra step to get a debbugs ID is annoying.

have you tried mumi CLI with the new feature?

> 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.
>    12. Run `git push` (subsequent changes are still just `git push`).
>    13. Go to forge website, click button to open a pull-request.

Forgive me if I insist: that forge site is _not_ SourceHut

Second: each forge web site have a custom (not standard) way to manage
pull-requests.

Third: git have a pull-request mechanism [1] that could _easily_ be
integrated in each and every forge, allowing projects to use
/interoperable/ email based pull-request workflows if they want to.

[...]

> I don't find difficult, and reflected on the difference for awhile, I 
> think, at
> least for me, the highest friction comes from:
>
> - Steps 11-19, or (to assign it a name for easier reference) the "CI
> steps".

OK: AFAIU https://qa.guix.gnu.org/ is _the_ answer, so we need more
contributors to that project

...and this means more cognitive overhead for Someone™ :-)

[...]

> If we wanted to encourage contributors to run "CI steps" 
> locally before
>    submitting, maybe this should be another `guix` sub-command? `guix 
> pre-check`
>    or something? I know there is a potential contributor who had this 
> idea first
>    who would want to hack on this.

Having such a sub-command maybe could help, maybe not, because IMO the
core and most cognitive challenging steps of all "CI steps" are not if
builds are done locally or not but (in order of importance):

1. having patches reviewed by humans, the "not automatable" part because
Someone™ have to understand the _meaning_ of the patch and verify it
conforms to the coding standards of the project, including "changelog
style" commit messages;

2. understanding why build derivation fail when it fails.

This is real cognitive overhead and this cannot be automated.

> - Steps 19-23, or the "manage patch" steps.
>
>    I think an insight here is that the big button on forges is actually 
> a program
>    removing the mental overhead for you.

On the "web forges" vs "email based" patch workflow management I've said
enough in other messages in this thread, here I just want to add
(repeat) this: please do not only consider the mental overhead of
potential contributors for "managing patches", also consider the mental
overhead for patch reviewers; I've read many articles from professional
patch reviewers that perfectly explains the great advanteges of using an
email based workflow

[...]

>    I also don't usually have to worry nearly as much about crafting a commit
>    message. So long as the title is under a character limit, and the body is
>    helpful, it's OK. I think what bothers me most about the GNU changelog
>    messages is that it's the worst of both spoken language and programming
>    languages: there's an expectation of structure, but no grammar I can 
> parse
>    against, and it's free-form.

I'm sorry that the GNU policy about commit messages bothers you (on the
contrary it makes me happy); please consider that thai is /just/ one of
the policies of the Guix project: code of conduct, coding standards,
others?

[...]

> - Having multiple places to manage aspects of my patch
>
>    In a web-forge, I generally have a URL I can go to and see everything 
> about my
>    patch. I think we have that with https://issues.guix.gnu.org with two
>    exceptions: (1) QA is a click away, or if you're using email, you're 
> not even
>    aware that there's a QA process failing (2) If you're not using email,
>    context-switching between this page and email to respond.

it's "just" an _interface_ issue

[...]

Happy hacking! Gio'


[1] https://www.git-scm.com/docs/git-request-pull

-- 
Giovanni Biscuolo

Xelera IT Infrastructures

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

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

[paul]

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

Hello Giovanni,

I get that you really don't find the web based workflow to bring enough 
advantages to justify the migration, but first please consider the 
picture that Katherine sent and that we are evaluating the adequateness 
of the email medium as a FOSS contribution management tool /over email/.

If we lower the bar for contributions more people are gonna be invested 
in Guix and will have interest in becoming committer and reviewer. My 
impression today is not that there aren't enough resources to cover 
reviews, the bottleneck is the total time that committers are able to 
dedicate to reviewing (potentially re-reviewing if some other 
non-committer contributor has already done a first review) and actually 
commiting changes.

I have many contributions opened more than a year ago where (sometimes 
also because of me obviously, we're all working after work here) the 
interactions on the issue are separated by many weeks, sometimes even 
months.

To ease that bottleneck we just need to give more time to committers or 
to increase the number of committers. All the automation and process 
changes we evaluate should be focused on either one of this two goals. I 
don't have evidence that any web forge will help (maybe someone has?), 
but I wouldn't throw it out of the window just because it does not ease 
the current review process.

cheers

giacomo

[-- Attachment #2: Type: text/html, Size: 1709 bytes --]

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

[Csepp]

Giovanni Biscuolo <g@xelera.eu> 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 <cox.katherine.e@gmail.com> 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.

How easy related issues are to find matters a great deal.  So does TODO
management.
Mumi currently fails at its main function of being a search engine for
issues.  I can't even find my own messages with keyword searches,
because for some reason Mumi connects each words with a logical or and
doesn't rank search results based on how many hits there are, not to
mention handling fuzzy hits, or synonyms, etc.

As I see it, this is an issue of developer resources.  Mumi and Debbugs
have no chance of catching up to any alterntive that already has a
sustainable financial model and professional developers working on it.

Why are we trying to compete with Sourcehut?  What's the end goal?

Mumi search broken? (was: Re: How can we decrease the cognitive overhead for contributors?)

[Liliana Marie Prikler]

Hi,

Am Samstag, dem 02.09.2023 um 18:08 +0200 schrieb Csepp:
> Mumi currently fails at its main function of being a search engine
> for issues.  I can't even find my own messages with keyword searches,
> because for some reason Mumi connects each words with a logical or
> and doesn't rank search results based on how many hits there are, not
> to mention handling fuzzy hits, or synonyms, etc.
To be fair, I remember a time when search results used to be better and
I think it used to be not so long ago (half a year to year maybe). 
Perhaps something in Xapian changed to make our life harder, but I
agree that mumi should probably not go for the fanciest schmanciest ISR
techniques and use (pseudo)booleans instead.

Cheers

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

[Csepp]

paul <goodoldpaul@autistici.org> writes:

> Hello Giovanni,
>
> I get that you really don't find the web based workflow to bring enough advantages to justify the migration, but first please consider the picture that
> Katherine sent and that we are evaluating the adequateness of the email medium as a FOSS contribution management tool over email. 
>
> If we lower the bar for contributions more people are gonna be invested in Guix and will have interest in becoming committer and reviewer. My
> impression today is not that there aren't enough resources to cover reviews, the bottleneck is the total time that committers are able to dedicate to
> reviewing (potentially re-reviewing if some other non-committer contributor has already done a first review) and actually commiting changes.
>
> I have many contributions opened more than a year ago where (sometimes also because of me obviously, we're all working after work here) the
> interactions on the issue are separated by many weeks, sometimes even months.
>
> To ease that bottleneck we just need to give more time to committers or to increase the number of committers. All the automation and process changes
> we evaluate should be focused on either one of this two goals. I don't have evidence that any web forge will help (maybe someone has?), but I wouldn't
> throw it out of the window just because it does not ease the current review process.
>
> cheers
>
> giacomo

To second this, I'd like to note for the record that on fedi at least
1-2 people told me that they chose Nix over Guix because they don't want
to deal with the email based workflow.  At least one of these people is
a highly skilled programmer with decades of experience.

While I mostly argued for Sourcehut, I think the pull-based alternatives
should also be kept in mind.

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

[wolf]

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

On 2023-09-02 21:08:12 +0200, Csepp wrote:
> 
> paul <goodoldpaul@autistici.org> writes:
> 
> > Hello Giovanni,
> >
> > I get that you really don't find the web based workflow to bring enough advantages to justify the migration, but first please consider the picture that
> > Katherine sent and that we are evaluating the adequateness of the email medium as a FOSS contribution management tool over email. 
> >
> > If we lower the bar for contributions more people are gonna be invested in Guix and will have interest in becoming committer and reviewer. My
> > impression today is not that there aren't enough resources to cover reviews, the bottleneck is the total time that committers are able to dedicate to
> > reviewing (potentially re-reviewing if some other non-committer contributor has already done a first review) and actually commiting changes.
> >
> > I have many contributions opened more than a year ago where (sometimes also because of me obviously, we're all working after work here) the
> > interactions on the issue are separated by many weeks, sometimes even months.
> >
> > To ease that bottleneck we just need to give more time to committers or to increase the number of committers. All the automation and process changes
> > we evaluate should be focused on either one of this two goals. I don't have evidence that any web forge will help (maybe someone has?), but I wouldn't
> > throw it out of the window just because it does not ease the current review process.
> >
> > cheers
> >
> > giacomo
> 
> To second this, I'd like to note for the record that on fedi at least
> 1-2 people told me that they chose Nix over Guix because they don't want
> to deal with the email based workflow.  At least one of these people is
> a highly skilled programmer with decades of experience.

Since we are collecting anecdotal data here, I pretty much stopped contributing
to Alpine after they stopped using the mailing list.  The friction (for me)
increased a lot compared to just calling git send-email.

From my circle of acquaintances, all people who picked Nix did it because they
did not like Guix' purism regarding software freedom and wanted something that
"gets the job done".

I am skeptical regarding people picking based on web vs. email flows, there are
more important differences.

> 
> While I mostly argued for Sourcehut, I think the pull-based alternatives
> should also be kept in mind.
> 

-- 
There are only two hard things in Computer Science:
cache invalidation, naming things and off-by-one errors.

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

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

[Ricardo Wurmus]

Maxim Cournoyer <maxim.cournoyer@gmail.com> writes:

> In the simplest case, it can be as simple as:
>
> $ ./pre-inst-env guix refresh -u some-package
> [build it, try it, fix if needed]
> $ ./etc/committer.scm
> $ git send-email
>
> Since it's a single patch, there's no jumping through hoops to create
> the original issue, and the auto-configured git will CC teams people
> subscribed to the scope of your change (if there are any).

Sadly the not-so-simple case is much more annoying.

I like an email-based workflow, don’t get me wrong.  At the same time
I’m really not a fan of Debbugs.  It makes simple things more difficult
than they should be (send a cover letter, wait for your mail to pass the
anti-spam measures, remember that you wanted to send a couple of
patches, etc), and no amount of sugar coating (whether that be a
different frontend like Mumi or a hell of a lot of client-side
scripting) can overcome this inherent clunkiness.

I’m no stranger to clunky or quirky interfaces.  I put up with them
because they unlock workflows and features or flexibility that would
otherwise be unattainable.  Emacs and Guix are great examples of quirky
interfaces that brim with flexibility.  I just think that Debbugs
doesn’t make the cut.

If only we can find a suitable baby sieve, I’d be happy to see the
turbid bathwater drained.  If Mumi and Debbugs went down the drain to
reveal a new hassle-free web/email hybrid patch workflow I’d be
ecstatic.

-- 
Ricardo

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

[Csepp]

wolf <wolf@wolfsden.cz> writes:

> [[PGP Signed Part:Undecided]]
> On 2023-09-02 21:08:12 +0200, Csepp wrote:
>> 
>> paul <goodoldpaul@autistici.org> writes:
>> 
>> > Hello Giovanni,
>> >
>> > I get that you really don't find the web based workflow to bring
>> > enough advantages to justify the migration, but first please
>> > consider the picture that
>> > Katherine sent and that we are evaluating the adequateness of the email medium as a FOSS contribution management tool over email. 
>> >
>> > If we lower the bar for contributions more people are gonna be
>> > invested in Guix and will have interest in becoming committer and
>> > reviewer. My
>> > impression today is not that there aren't enough resources to
>> > cover reviews, the bottleneck is the total time that committers
>> > are able to dedicate to
>> > reviewing (potentially re-reviewing if some other non-committer
>> > contributor has already done a first review) and actually
>> > commiting changes.
>> >
>> > I have many contributions opened more than a year ago where
>> > (sometimes also because of me obviously, we're all working after
>> > work here) the
>> > interactions on the issue are separated by many weeks, sometimes even months.
>> >
>> > To ease that bottleneck we just need to give more time to
>> > committers or to increase the number of committers. All the
>> > automation and process changes
>> > we evaluate should be focused on either one of this two goals. I
>> > don't have evidence that any web forge will help (maybe someone
>> > has?), but I wouldn't
>> > throw it out of the window just because it does not ease the current review process.
>> >
>> > cheers
>> >
>> > giacomo
>> 
>> To second this, I'd like to note for the record that on fedi at least
>> 1-2 people told me that they chose Nix over Guix because they don't want
>> to deal with the email based workflow.  At least one of these people is
>> a highly skilled programmer with decades of experience.
>
> Since we are collecting anecdotal data here, I pretty much stopped contributing
> to Alpine after they stopped using the mailing list.  The friction (for me)
> increased a lot compared to just calling git send-email.
>
> From my circle of acquaintances, all people who picked Nix did it because they
> did not like Guix' purism regarding software freedom and wanted something that
> "gets the job done".
>
> I am skeptical regarding people picking based on web vs. email flows, there are
> more important differences.
>
>> 
>> While I mostly argued for Sourcehut, I think the pull-based alternatives
>> should also be kept in mind.
>> 

The FOSS purism is a bigger deciding factor for sure.  Maybe I'm
conflating things and they said they didn't want to bother
*contributing* to Guix, but I think they also stopped being Guix users.

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

[Vagrant Cascadian]

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

On 2023-09-03, Ricardo Wurmus wrote:
> Maxim Cournoyer <maxim.cournoyer@gmail.com> writes:
>
>> In the simplest case, it can be as simple as:
>>
>> $ ./pre-inst-env guix refresh -u some-package
>> [build it, try it, fix if needed]
>> $ ./etc/committer.scm
>> $ git send-email
>>
>> Since it's a single patch, there's no jumping through hoops to create
>> the original issue, and the auto-configured git will CC teams people
>> subscribed to the scope of your change (if there are any).
>
> Sadly the not-so-simple case is much more annoying.
>
> I like an email-based workflow, don’t get me wrong.  At the same time
> I’m really not a fan of Debbugs.  It makes simple things more difficult
> than they should be (send a cover letter, wait for your mail to pass the
> anti-spam measures, remember that you wanted to send a couple of
> patches, etc), and no amount of sugar coating (whether that be a
> different frontend like Mumi or a hell of a lot of client-side
> scripting) can overcome this inherent clunkiness.

The only thing clunky about this particular aspect of the workflow
described is the fact that the guix community (maintainers?) have
decided on a one patch per mail policy with a cover letter, rather than
submitting the patches as attachments in the initial mail.

Debbugs may have numerous other ugly warts, but that is not really one
of them, in my opinion.

Changing that one policy (expectation?) would probably remove a
significant portion of the friction many people have with patch
submissions...

That change will likely have have other frictions, but I suspect they
would be much easier to adapt to...


> If only we can find a suitable baby sieve, I’d be happy to see the
> turbid bathwater drained.  If Mumi and Debbugs went down the drain to
> reveal a new hassle-free web/email hybrid patch workflow I’d be
> ecstatic.

I cannot complain about wanting the best of both worlds if the cost is
not too high. :)

For most of my work in Debian, I accept patches via bugs.debian.org (the
*original* debbugs instance, primarily email) or salsa.debian.org (a
gitlab instance, primarily web)...

Sometimes it is a little awkward because specific maintainers prefer one
interface over the other, or only pay attention to one or the
other... but for the most part I find it allows people to use whatever
works best for them...


At the end of the day git allows quite a few workflows, and the
submitters and committers do not even have to use the entirely same
workflow. There is plenty of room to be flexible.

I recently learned about and started using:

  https://git.guix-patches.cbaines.net/git/guix-patches

This allows me to pull the latest (usually!) patch submissions and
fiddle with and chew on offline... in the same way I might work with
most other git-based projects, merging and cherry-picking and doing
unmentionable things to those poor patches, all from the comfort of my
local machine. It suppliments the email workflow quite nicely, in my
opinion.


So, on the other end, if there was a central place where people (ideally
very open) could push patch submissions, so that people could more
easily pull them all at once, that might help alleviate some of the
issue from the other direction...


The fact that Guix code is largely a single git repository is something
I really value, and makes many things much easier... compared to Debian
which has largely one git respository per package, which might be hosted
on arbitrary servers, or maybe some other VCS, or maybe not even any VCS
at all (other than the Debian mirror itself)...


live well,
  vagrant

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

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

[Ricardo Wurmus]

Csepp <raingloom@riseup.net> writes:

> Mumi currently fails at its main function of being a search engine for
> issues.  I can't even find my own messages with keyword searches,
> because for some reason Mumi connects each words with a logical or and
> doesn't rank search results based on how many hits there are, not to
> mention handling fuzzy hits, or synonyms, etc.

Mumi commit bda10fa1b37fed8ea313ea8ad49fa6146e65b4c0 changed the AND to
the Xapian default of OR.  Here’s the rationale from the commit message:

    xapian: Do not override the default OR implicit query operator.

    An implicit AND operator is overly restrictive. It was only necessary
    because prefixes that should have been indexed as boolean prefixes
    were not.

Xapian *does* rank search results by score.  It also supports fuzzy
search.  But let me move a little so I won’t stand in the way of a good
rant.

> As I see it, this is an issue of developer resources.  Mumi and Debbugs
> have no chance of catching up to any alterntive that already has a
> sustainable financial model and professional developers working on it.
>
> Why are we trying to compete with Sourcehut?  What's the end goal?

I can’t make myself even clearer about this, but I’ll repeat myself
again: we are not.

“Competition” is a foreign concept to me.  Mumi exists only because I
found the Debbugs web interface kinda ugly and alienating.  It’s a hack
that obviously outlived its welcome.  I have to admit that messages like
this make me regret scratching this itch that gave rise to Mumi in 2016.
(Sourcehut started in 2018.)

Please go ahead and package the rest of Sourcehut, so we can host it and
finally forget about Mumi and Debbugs.

-- 
Ricardo

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

[paul]

Hello Ricardo,

On 9/3/23 09:36, Ricardo Wurmus wrote:
> Mumi commit bda10fa1b37fed8ea313ea8ad49fa6146e65b4c0 changed the AND to
> the Xapian default of OR.  Here’s the rationale from the commit message:
>
>      xapian: Do not override the default OR implicit query operator.
>
>      An implicit AND operator is overly restrictive. It was only necessary
>      because prefixes that should have been indexed as boolean prefixes
>      were not.
>
> Xapian *does* rank search results by score.  It also supports fuzzy
> search.  But let me move a little so I won’t stand in the way of a good
> rant.

I don't think this is a productive attitude, especially from someone 
well known in the community for their historical high quality commitment 
to the Guix project. It's already quite difficult to sustain a 
discussion with what appears to be most of the Guix Project committers 
as less experienced members of the community.

No one's point here is to denigrate work that has been done in the past 
and that enabled us to have this discussion today in the first place.

The point of this discussion is fundamentally a healthy future for the 
Guix Project committers collective imho. If the flow of new contributors 
stops we are doomed, no one can be expected of bearing the 
responsibility having commit access is, for their whole life imho.

We need a healthy "succession" story.

>
>> As I see it, this is an issue of developer resources.  Mumi and Debbugs
>> have no chance of catching up to any alterntive that already has a
>> sustainable financial model and professional developers working on it.
>>
>> Why are we trying to compete with Sourcehut?  What's the end goal?
> I can’t make myself even clearer about this, but I’ll repeat myself
> again: we are not.

We are not and yet one of the most (maybe the second maybe the first) 
successful proposal to address Katherine's points is to rewrite 
everything™. In this sense I believe Csepp's objection is quite clear:

Do we have the resources to maintain a CI suite (Guix Build 
Coordinator), a QA suite (Guix Data Service), a Debbugs frontend (Mumi) 
and a to-be-defined new patch tracking system? What's the story for when 
the current committers will have too much life to do to keep having the 
current commitment level?

What's the story for having a healthy turnover of Guix highest 
responsibilities?
> Please go ahead and package the rest of Sourcehut, so we can host it and
> finally forget about Mumi and Debbugs.

Again, this is not a competition between Sourcehut and Mumi. This is a 
discussion between adults that care very much about the same 
philosophical and political points about technological control and autonomy.

giacomo

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

[Ricardo Wurmus]

paul <goodoldpaul@autistici.org> writes:

>> Please go ahead and package the rest of Sourcehut, so we can host it and
>> finally forget about Mumi and Debbugs.
>
> Again, this is not a competition between Sourcehut and Mumi. This is a
> discussion between adults that care very much about the same
> philosophical and political points about technological control and
> autonomy.

You seem to have managed to miss my point.  I emphatically agree that
there is no competition.

As the original author of Mumi I want it to become obsolete as it
clearly has outlived its usefulness and better alternatives exist.  The
way to get there is to add the replacement to Guix so we can host it.

I won’t contribute to Mumi any more.  Giving it up doesn’t hurt my
feelings.  I’d be glad to see it gone.

-- 
Ricardo

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

[Felix Lechner via Development of GNU Guix and the GNU System distribution.]

Hi all,

On Sun, Sep 3, 2023 at 3:35 AM Ricardo Wurmus <rekado@elephly.net> wrote:
>
> I won’t contribute to Mumi any more.  Giving it up doesn’t hurt my
> feelings.  I’d be glad to see it gone.

For what it's worth, I like Mumi.

One day, I hope to help offer Scheme diffs there. Perhaps it will take
just a pull from the base commit and guile-sexp-diff. [1]

Maybe Git can eventually use such diffs, too. As a group we deserve better.

I like the email-based workflow. I used Debbugs for years. Mumi is an
incremental, man-in-the-middle approach that could help us migrate
gradually away from the underlying bug tracker. I just wish Mumi could
hide old patch sets. And again, ideally the newest patches would be
presented in a nicely colored Sexp diff.

Thanks for contributing to this discussion, and also for making Guix a
better operating system for everyone!

Kind regards
Felix

[1] https://codeberg.org/lechner/guile-diff-sexp

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

[Ekaitz Zarraga]

Hi,

> I think this is the biggest hurdle. A lot of folks are using gmail and
> its web based UI and it is just plain awful. I have made the switch to
> using neomutt (and isync + notmuch + mstmp) and it has made emails a joy
> to use and work with.

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

Protonmail has a bridge that deals with that but we don't have it packaged
because it's written in Go and it has TOO MANY dependencies.

This is not Guix's fault, but it's a problem Guix doesn't help fix either.
The only thing I can do with this is just copy-paste the result of git
format-patch and hope it's not a trouble for committers.

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.

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

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.

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.

Cheers,
Ekaitz

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

[Csepp]

Ricardo Wurmus <rekado@elephly.net> writes:

> paul <goodoldpaul@autistici.org> writes:
>
>>> Please go ahead and package the rest of Sourcehut, so we can host it and
>>> finally forget about Mumi and Debbugs.
>>
>> Again, this is not a competition between Sourcehut and Mumi. This is a
>> discussion between adults that care very much about the same
>> philosophical and political points about technological control and
>> autonomy.
>
> You seem to have managed to miss my point.  I emphatically agree that
> there is no competition.
>
> As the original author of Mumi I want it to become obsolete as it
> clearly has outlived its usefulness and better alternatives exist.  The
> way to get there is to add the replacement to Guix so we can host it.
>
> I won’t contribute to Mumi any more.  Giving it up doesn’t hurt my
> feelings.  I’d be glad to see it gone.

I think given the lack of dev resources, it's impressive that Mumi works
as well as it does, but I'm glad that we have some rough-consensus that
something better is needed.  I'll try to pick up the Sourcehut
packaging, now that I know there is a chance it would be accepted.

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

[Ricardo Wurmus]

Csepp <raingloom@riseup.net> writes:

> I'll try to pick up the Sourcehut
> packaging, now that I know there is a chance it would be accepted.

Excellent.  Thank you!

I started work on the issue tracker a while ago, but only had enough
time for the first two packages which are in gnu/packages/sourcehut.scm.

-- 
Ricardo

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

[indieterminacy]

On 03-09-2023 19:45, Ekaitz Zarraga wrote:
> Hi,
> 
>> I think this is the biggest hurdle. A lot of folks are using gmail and
>> its web based UI and it is just plain awful. I have made the switch to
>> using neomutt (and isync + notmuch + mstmp) and it has made emails a 
>> joy
>> to use and work with.
> 
> I use protonmail and they don't provide smtp access so I can't do git
> send-mail as easy as other people do.
> 
> Protonmail has a bridge that deals with that but we don't have it 
> packaged
> because it's written in Go and it has TOO MANY dependencies.
> 
> This is not Guix's fault, but it's a problem Guix doesn't help fix 
> either.
> The only thing I can do with this is just copy-paste the result of git
> format-patch and hope it's not a trouble for committers.
> 
> 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.
> 
> Some people are forced to use tools for several reasons, too.
> 
> 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).

> 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.
> 
> Cheers,
> Ekaitz

-- 
Jonathan McHugh
indieterminacy@libre.brussels

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

[Ekaitz Zarraga]

> > 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.

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

[Ricardo Wurmus]

Vagrant Cascadian <vagrant@debian.org> writes:

> The only thing clunky about this particular aspect of the workflow
> described is the fact that the guix community (maintainers?) have
> decided on a one patch per mail policy with a cover letter, rather than
> submitting the patches as attachments in the initial mail.

You are right.  When I started contributing I actually did attach all
patches in one email.  I wonder why we stopped doing that.

I’ll say that many of my gripes with (the GNU instance of) Debbugs are
due to the fact that we can’t customize it to better suit our needs — it
is a shared resource with a complicated maintenance story.  So all
changes went into Mumi as crude workarounds.  I think this is a dead end
and we’d be better off leaving the shared GNU instance of Debbugs
behind.

-- 
Ricardo

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

[Giovanni Biscuolo]

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

Hi,

Felix Lechner via "Development of GNU Guix and the GNU System
distribution." <guix-devel@gnu.org> writes:

> Hi all,
>
> On Sun, Sep 3, 2023 at 3:35 AM Ricardo Wurmus <rekado@elephly.net> wrote:
>>
>> I won’t contribute to Mumi any more.  Giving it up doesn’t hurt my
>> feelings.  I’d be glad to see it gone.
>
> For what it's worth, I like Mumi.

me too: it's a very good implementation of a web interface for an
email-based issue tracking (eco)system, in particular it's a very useful
implementation of a web based Xapian interface specialized in issue
_tracking_

> One day, I hope to help offer Scheme diffs there. Perhaps it will take
> just a pull from the base commit and guile-sexp-diff. [1]
>
> Maybe Git can eventually use such diffs, too. As a group we deserve
> better.

Git already have a mechanism to use external diff programs, via
.gitattributes; all we need are better/specialized/semantic diff
programs packaged in Guix

> I like the email-based workflow.

I'd say that an email-based workflow is a conditio sine qua non for
_all_ projects, possibly supplemented by a web based interface, possibly
better than Debbugs, possibly better than mumi

mumi have a _great_ potential to be extended, it could even be extended
to become the web/CLI frontend to other email-based issue tracking
systems

[...]

Happy hacking, Gio'

-- 
Giovanni Biscuolo

Xelera IT Infrastructures

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

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

[Attila Lendvai]

> To second this, I'd like to note for the record that on fedi at least
> 1-2 people told me that they chose Nix over Guix because they don't want
> to deal with the email based workflow. At least one of these people is
> a highly skilled programmer with decades of experience.


FWIW,

i'm 46, programming since my childhood. i have 10+ years of Common Lisp experience using Emacs, most of it on opensource projects.

here's an approximate list of what's consuming/training my frustration-tolerance with Guix:

 - debbugs and related tooling. i could live with an email based
   workflow, but whatever is documented, or at least whatever i have
   put together locally, is very inefficient. the chore vs. coding
   ratio is low.

 - large backlog. contributions somtimes even fall through the cracks.

 - strict adherence to changelog style commit messages without a
   clearly worded and documented argument about why it's worth the
   effort in 2023. whenever 'C' fails to add an entry to the commit
   message in Emacs, i groan out loud.

i came to Guix from a couple of years of NixOS (also contributing), being frustrated by the way they use Nix, the language, to describe OS services. it felt an uphill battle for no good reason that Guix liberated. Guix has much more flexibility and common sense in the coding domain (that compensates for the increased frustration in the social domain).

-- 
• attila lendvai
• PGP: 963F 5D5F 45C7 DFCD 0A39
--
“Toxic people will not be changed by the alchemy of your kindness. Yes, be kind, but move on swiftly and let life be their educator.”
	— Brendon Burchard

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

[David Larsson]

On Wed, 23 Aug 2023 10:25:58 -0600
Katherine Cox-Buday <cox.katherine.e@gmail.com> wrote:

> Summary: for people who don't contribute to Guix a lot, each 
> contribution has
> very high cognitive overhead. Can we work to reduce that?

[..]
 
> * Encourage upstream communities like "Guix 'R Us" 
> (https://sr.ht/~whereiseveryone/guixrus/)
> 
>      Maybe Guix proper continues as is and we foster various upstream 
> communities
>      that utilize different styles and batch their contributions?
> 
> What do you all think? Does this affect anyone else?
> 

It affects me too.

I somewhat frequently end up fixing a broken package I use, adding a
package or package varieties in my private channel (or just locally
and installing with guix package -f <mypkg>), without contributing it to
guix. Sometimes I see someone else eventually contributing a package
I've also packaged which is ofc. wasteful dual effort. It's hard to find
the time to make it nice enough, walk through the steps and submit a
patch for it.


I think Guix 'R Us is a great initiative, and to me anything that's
"pre-release" with lesser standards sounds like a good idea, a place
more experienced Guixer's and committers can pick new packages from and
modify to suit the high standards of guix proper. It's also obvious that
"pre-release" has lesser promises. An official pre-release
channel wouldn't only be able to accept more patches, but can probably
make Guix master less prone to broken builds or packages that are
broken at runtime, and also perhaps fix broken packages faster (like
remote-viewer was broken for months, maybe still is) - easy to fix,
harder to bother walking through the patch submission process to do it
(for the less experienced). A barrier, albeit small, on that front is
that I have issues with package inherits and applying raw patches in a
separate guix channel, which might be a general problem not just me not
knowing how to do it.


For overhead issue with git messages, maybe the Guix manual could
suggest a few tools that are good at assisting with this. emacs-magit
is probably a class of it's own, but there's also vimagit and other GUI
based ones, that helps with rewriting git history and selecting even
specific lines - not just hunks - to add to a patch. Some end to end
contribution workflow example blog posts could help perhaps, if someone
feels up to it?


Best regards,
David

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

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

Attila Lendvai <attila@lendvai.name> writes:

> here's an approximate list of what's consuming/training my frustration-tolerance with Guix:
>
>  - debbugs and related tooling. i could live with an email based
>    workflow, but whatever is documented, or at least whatever i have
>    put together locally, is very inefficient. the chore vs. coding
>    ratio is low.
>
>  - large backlog. contributions somtimes even fall through the cracks.
>
>  - strict adherence to changelog style commit messages without a
>    clearly worded and documented argument about why it's worth the
>    effort in 2023. whenever 'C' fails to add an entry to the commit
>    message in Emacs, i groan out loud.

This is almost exactly my list. I strongly suspect that the issue with
the backlog and lost issues has a lot to due with debbugs just not
cutting the mustard.

I've got something like 6 patches waiting, all have been sitting around
for many months. They'll get some committer attention and then it drops
off and nothing happens. To me, that sounds like people lose track of
it, because debbugs doesn't allow people to stay easily on top of
patches they're interested in. Possibly we need some kind of concept of
patch stewards that can see something through.

I have more things I want to do with Guix, but it's tough, because I
have to maintain each of my patches separately in different branches, so
that I can rebase them as necessary and resubmit them cleanly if
necessary, or simply just to work on them when issues come up. But my
master branch pulls in each of them, so any time I need to pull, I've
got a list of things (switch to every branch, rebase, fix if necessary,
switch back to master, reset to origin/master, then merge all the
branches I'm maintaing). Adding more branches on top of the ones I
already have is just too much.

Regarding the GNU changelog commits, I really dislike them. They're
redundant busy-work as far as I'm concerned. And while I'd like to say
they're no longer necessary, because we have better tooling, I'm old
enough to be familiar with hand editing RCS and CVS files to fix
them. And even back then, in the dark days, only GNU used that
format. Just like today. So I'd argue they've always been pointless
busy-work.

I really like Guix, I like what it promises, I love the community around
it, and that's what keeps me here. But it's a deeply frustrating
experience to try to contribute to. I've been a contributor in various
forms to a great many free and open source software projects over the
years, and Guix is easily one of the worst in that regard.

-bjc

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

[Ricardo Wurmus]

"Danny Milosavljevic" <dannym@scratchpost.org> writes:

> I agree that automating the technical steps of contributing to Guix
> would be nice.

We could provide a VM.  Guix can create systems well enough to make this
feasible, I think.

> This definitely should be automated. Why not generate a UUID locally and send
> a mail to <UUID>@debbugs.gnu.org ? That may require changes to debbugs,
> though.

We cannot change the shared debbugs instance, which is why I think we
should take a closer look at self-hosting sourcehut.

-- 
Ricardo

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

[Attila Lendvai]

> I've got something like 6 patches waiting, all have been sitting around
> for many months. They'll get some committer attention and then it drops
> off and nothing happens. To me, that sounds like people lose track of
> it, because debbugs doesn't allow people to stay easily on top of
> patches they're interested in. Possibly we need some kind of concept of
> patch stewards that can see something through.


yep, same impression here.


> I have more things I want to do with Guix, but it's tough, because I
> have to maintain each of my patches separately in different branches, so
> that I can rebase them as necessary and resubmit them cleanly if
> necessary, or simply just to work on them when issues come up. But my
> master branch pulls in each of them, so any time I need to pull, I've
> got a list of things (switch to every branch, rebase, fix if necessary,
> switch back to master, reset to origin/master, then merge all the
> branches I'm maintaing). Adding more branches on top of the ones I
> already have is just too much.


here's a script that i use to prepare an 'attila' branch that i can `guix pull` from:

$ cat ../rebase-my-guix-branches.sh
#!/usr/bin/env bash

BRANCHES="kludges ui-warnings trezor4"
# kludges-sent shepherd-from-git
# ddclient idris

set -e

initial_branch=$(git branch --show-current)

git rebase attila-baseline attila-initial-commit

git checkout attila
git reset --hard attila-baseline
git pull . attila-initial-commit

for branch in ${BRANCHES}; do
    echo "*** Processing branch ${branch}"
    #git rebase attila-baseline $branch
    git cherry-pick attila-baseline..$branch
done

#git checkout $initial_branch

git -c pager.log=false log --pretty=oneline attila-initial-commit~1..attila-initial-commit

----------------

explanation:

i `git tag -f attila-baseline` on some commit, typically i pull master and on its head. then i have a branch called attila-initial-commit that holds a single commit that adds my key as authorized.

this script cherry-picks all the listed branches, and at the end it prints the commit hash of the initial commit that i can then copy-paste into my channels.scm file.

whenever cherry-picking fails, i abort it, manually rebase the branch in question, and then restart the script.

HTH,

-- 
• attila lendvai
• PGP: 963F 5D5F 45C7 DFCD 0A39
--
“Freedom is strangely ephemeral. It is something like breathing; one only becomes acutely aware of its importance when one is choking.”
	— William E. Simon

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

[Efraim Flashner]

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

On Mon, Sep 04, 2023 at 10:56:39AM +0200, Ricardo Wurmus wrote:
> 
> Vagrant Cascadian <vagrant@debian.org> writes:
> 
> > The only thing clunky about this particular aspect of the workflow
> > described is the fact that the guix community (maintainers?) have
> > decided on a one patch per mail policy with a cover letter, rather than
> > submitting the patches as attachments in the initial mail.
> 
> You are right.  When I started contributing I actually did attach all
> patches in one email.  I wonder why we stopped doing that.

I believe some found it easier to pipe multiple emails to git am than to
pipe attachments. From mutt there's no difference for me.

> I’ll say that many of my gripes with (the GNU instance of) Debbugs are
> due to the fact that we can’t customize it to better suit our needs — it
> is a shared resource with a complicated maintenance story.  So all
> changes went into Mumi as crude workarounds.  I think this is a dead end
> and we’d be better off leaving the shared GNU instance of Debbugs
> behind.

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

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

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

[Andreas Enge]

Am Mon, Sep 04, 2023 at 08:44:18AM -0400 schrieb brian via Development of GNU Guix and the GNU System distribution.:
> >  - strict adherence to changelog style commit messages without a
> >    clearly worded and documented argument about why it's worth the
> >    effort in 2023. whenever 'C' fails to add an entry to the commit
> >    message in Emacs, i groan out loud.
> Regarding the GNU changelog commits, I really dislike them. They're
> redundant busy-work as far as I'm concerned. And while I'd like to say
> they're no longer necessary, because we have better tooling

As said before, I use them all the time through
   git log | grep "whatever I am looking for"
or the interactive
   git log
then "/" for searching inside the less command; I find it useful to a point
that I have moved to this style for all my coding projects.

So as far as I am concerned, they are tremendously useful. Well, that may
be due to a lack of git knowledge, of course! But while in other projects
I often find I need to look at the content of commits, in Guix it is often
enough to just look at the changelog.

Andreas

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

[Andreas Enge]

Am Mon, Sep 04, 2023 at 10:23:45AM +0000 schrieb Attila Lendvai:
>  - large backlog. contributions somtimes even fall through the cracks.

My impression/hope is that the recent introduction of teams leads to
improvements on this front. I am on the science and texlive teams and
have been getting emails from the patch submission workflow; so these
end up in my inbox and I feel responsible for them. As a consequence,
I have been reviewing more commits recently.

For this to work, we would need a 100% coverage of modules by teams
(a necessary, not a sufficient condition...). A consequence of my
focussing on email is that I essentially ignore everything that does
not come in by email (well, I also look at the green badges in QA
from time to time). So, my impression/hope is that also QA leads to
improvements.

This does not solve the problem of finite time and competence, however.

Andreas

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

[phil]

>I really like Guix, I like what it promises, I love the community around
it, and that's what keeps me here. But it's a >deeply frustrating experience
to try to contribute to. I've been a contributor in various forms to a great
many free >and open source software projects over the years, and Guix is
easily one of the worst in that regard.

This aligns with somewhat with my (limited) experience.  I'm a massive fan
of Guix, but I did find the process a bit opaque; even after seeking
clarification from the mailists, and some of my patches eventually fell
through the cracks, or in other cases, someone would kindly submit on my
behalf.  That's really nice of them to do, but it's obviously not the way
things should work.

I've contributed to other Guix channels (some run by people closely
affiliated with Guix proper) and other open source projects and found the
overhead is usually no more than few minutes to read/follow to the how-to
guide.  I don't have a favourite forge nor a specific process I want to
promote - but it should be easy and require little effort to understand and
setup.  Really the typical use-case should be close to push-button - with
the focus being on reviewing the contribution rather than the mechanics of
how this is done.

I (and other colleagues) have a bunch of core enhancements, and quite a few
packages sat in my (now previous) company's Guix channel that would be great
to get into Guix proper (if the wider community deem them appropriate/useful
of course!), but the overhead means we kept avoiding getting this done and
the company runs off a lagged fork of Guix they manually update and rebase
themselves, rather than pushing their work upstream into Guix.

I 100% accept failing to get patches into Guix proper is also lethargy on my
behalf, and perhaps I'm guilty of carping rather than proactively helping,
but in choosing what to contribute to, and when spare-time is sadly limited,
the amount of overhead and chasing required both become inevitable
considerations on where to focus time.

Mumi CLI client (was: How can we decrease the cognitive overhead for contributors?)

[Arun Isaac]

Hi all,

I'm glad we're having this difficult but necessary conversation.

I have been following the conversation with much interest. There seems
to be a developing consensus that we should switch to sourcehut. I am
all in favour of any decision the community comes to on this.

But, meanwhile, I wish to remind everyone that we already have a mumi
CLI client that takes away some of the pain of dealing with Debbugs. It
operates fully on the command-line and does not require Emacs at
all. This CLI client has so far been undocumented. So, I thought it
helpful to document it and put it into the manual. I have sent a patch
to https://issues.guix.gnu.org/65746

Regards,
Arun

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

[Maxim Cournoyer]

Hi,

Katherine Cox-Buday <cox.katherine.e@gmail.com> writes:

[...]

> 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.
>
> [I'm usually starting here]
>
>   4. Run `./pre-inst-env guix refresh --list-dependent <package>`
>   5. Create a git worktree for your patch
>   6. Run `./bootstrap`, then `./configure --localstatedir=/var
> --sysconfdir=/etc`
>   7. Run `make`
>   8. Make your changes
>   9. Build to ensure your changes are workable.
>   10. Try and determine how your changes should be factored into individual
>       commits (sometimes it's not always so clear when changing two
> things might
>       need to be done atomically).
>   11. Try and get each commit message close to correct and commit.
>   12. Run `guix lint`
>   13. Run `guix style` (this is still in the manual although I have since
>       learned this is not actually advisable).

The intent is for it to be advisable -- when it's not, a bug should
be/have been reported against it to track its resolution.

[...]

>   19. Run `guix pull --url=/path/to/your/checkout
> --profile=/tmp/guix.master` to
>       ensure you didn't break Guix in a different way.

'make as-derivation' is probably more efficient to test for that

>   20. Run `git format-patch -1 --cover-letter [--reroll-count]`
>   21. Run `./pre-inst-env ./etc/teams.scm cc-members <patch>` to get
> the CC flags for Git
>   22. Remember that if you're sending multiple patches, an email first
> has to be
>       sent to `guix-patches@gnu.org` to get an ID, and then...
>   23. Run `git send-email --to guix-patches <patches> <CC flags>`

You don't need to manually do 21 (and add the cc flags in 23), as
advances to git and our teams.scm script automates that for you (the
patches are checked for which files they touched; and the team, if any,
that has such files in their scope is CC'd via a X-Debbugs-CC header).

--
Thanks,
Maxim

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

[Maxim Cournoyer]

Hi Ricardo,

Ricardo Wurmus <rekado@elephly.net> writes:

> Vagrant Cascadian <vagrant@debian.org> writes:
>
>> The only thing clunky about this particular aspect of the workflow
>> described is the fact that the guix community (maintainers?) have
>> decided on a one patch per mail policy with a cover letter, rather than
>> submitting the patches as attachments in the initial mail.
>
> You are right.  When I started contributing I actually did attach all
> patches in one email.  I wonder why we stopped doing that.

It's still allowed as far as I know.  But due to missing out on
notifying team members automatically (handled by 'git send-email') and
sometimes causing issues for reviewers to apply patches, it's
understandable that 'git send-email' is the most recommended option.

> I’ll say that many of my gripes with (the GNU instance of) Debbugs are
> due to the fact that we can’t customize it to better suit our needs — it
> is a shared resource with a complicated maintenance story.  So all
> changes went into Mumi as crude workarounds.  I think this is a dead end
> and we’d be better off leaving the shared GNU instance of Debbugs
> behind.

I'd be sad to loose at least two good things from Debbugs:

1. It's hosted by the GNU/FSF for us.  It always work, and the rare
times it doesn't, the folks in #savannah are hard at work resolving the
problems. While hosting sourcehut is probably not too difficult, keeping
it up to date (Go...) and running would be yet another weigh on our
meager sysadmin team.

2. Integration with Emacs.  emacs-debbugs is useful.  I think it's the
only successful thing we have at keeping track of old tickets and
resuming discussion or acting on these.

I like how clean Mumi looks, compared to most forge issue trackers.  I'm
not convinced by its search results (perhaps I'd need to get to know
what Xapian is).

-- 
Thanks,
Maxim

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

[Maxim Cournoyer]

Hi,

Ricardo Wurmus <rekado@elephly.net> writes:

> "Danny Milosavljevic" <dannym@scratchpost.org> writes:
>
>> I agree that automating the technical steps of contributing to Guix
>> would be nice.
>
> We could provide a VM.  Guix can create systems well enough to make this
> feasible, I think.

I'm not convinced.  I typically uses VM for testing quick hacks on
foreign systems, not as my main development environment.  I doubt the
experience would be helped much.  We have 'guix shell' :-).

-- 
Thanks,
Maxim

Replacing Mumi+Debbugs?

[Ricardo Wurmus]

Maxim Cournoyer <maxim.cournoyer@gmail.com> writes:

>> I’ll say that many of my gripes with (the GNU instance of) Debbugs are
>> due to the fact that we can’t customize it to better suit our needs — it
>> is a shared resource with a complicated maintenance story.  So all
>> changes went into Mumi as crude workarounds.  I think this is a dead end
>> and we’d be better off leaving the shared GNU instance of Debbugs
>> behind.
>
> I'd be sad to loose at least two good things from Debbugs:
>
> 1. It's hosted by the GNU/FSF for us.  It always work, and the rare
> times it doesn't, the folks in #savannah are hard at work resolving the
> problems. While hosting sourcehut is probably not too difficult, keeping
> it up to date (Go...) and running would be yet another weigh on our
> meager sysadmin team.

Yes, this is a real concern.  Infrastructure at scale is always a little
messier than one would assume.

> 2. Integration with Emacs.  emacs-debbugs is useful.  I think it's the
> only successful thing we have at keeping track of old tickets and
> resuming discussion or acting on these.
>
> I like how clean Mumi looks, compared to most forge issue trackers.  I'm
> not convinced by its search results (perhaps I'd need to get to know
> what Xapian is).

Xapian is a search engine for documents.  It lets us create search
indices over keywords extracted from documents and retrieve matching
documents.  It’s what “mu” uses for its database; that’s the origin of
“mu” in “mumi” as we used to just leave all the search business to “mu”
in early versions.

All the things related to search are here:

    https://git.savannah.gnu.org/cgit/guix/mumi.git/tree/mumi/xapian.scm

“index-files” opens all emails, extracts fields such as author, subject,
status, body (for full text search), etc, and builds the search
index/database.

“search” converts the query string into a query object and requests
matching documents from the database.

We’re constantly updating the index to match the growing collection of
Debbugs emails.

We are testing the basic search interface here:

    https://git.savannah.gnu.org/cgit/guix/mumi.git/tree/tests/xapian.scm

If there are bad results (and mumi should be used for a while longer to
justify changing it) we should create test cases for them, so we get a
chance to update the way we index the documents and create a query.

Going forward we could also think about augmenting the search with text
embeddings, e.g. by computing word vectors over the whole collection of
emails, turning the search query into a word vector, and then search for
the most similar vectors in the collection.  This would give us very
fuzzy matching of synonyms and related terms.  fasttext and faiss can be
used for these purposes.

-- 
Ricardo

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

[Ricardo Wurmus]

Maxim Cournoyer <maxim.cournoyer@gmail.com> writes:

> Hi,
>
> Ricardo Wurmus <rekado@elephly.net> writes:
>
>> "Danny Milosavljevic" <dannym@scratchpost.org> writes:
>>
>>> I agree that automating the technical steps of contributing to Guix
>>> would be nice.
>>
>> We could provide a VM.  Guix can create systems well enough to make this
>> feasible, I think.
>
> I'm not convinced.  I typically uses VM for testing quick hacks on
> foreign systems, not as my main development environment.  I doubt the
> experience would be helped much.  We have 'guix shell' :-).

Or “guix system container” if we want to meet in the middle :)

-- 
Ricardo

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

[Simon Tournier]

Hi,

On Tue, 29 Aug 2023 at 12:53, MSavoritias <email@msavoritias.me> 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

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

[Simon Tournier]

Hi Ricardo, all,

On Sun, 03 Sep 2023 at 12:31, Ricardo Wurmus <rekado@elephly.net> wrote:

> As the original author of Mumi I want it to become obsolete as it
> clearly has outlived its usefulness and better alternatives exist.  The
> way to get there is to add the replacement to Guix so we can host it.

I am seeing the gap that Mumi fills with a tiny larger angle.  For sure,
the initial aim of Mumi is to improve the situation with the default
web-interface of the Debbugs instance of the project GNU.

In addition, the collateral effect is an improvement for *all* the GNU
projects using this Debbugs instance.  Currently, Mumi displays all
issues, e.g., an old one about the Emacs project:

    https://issues.guix.gnu.org/12345

The fact that the GNU project is not currently exploiting the Mumi
front-end is another story but I have always considered Mumi as a way to
improve first the Guix experience and then also the whole GNU project.


> I won’t contribute to Mumi any more.  Giving it up doesn’t hurt my
> feelings.  I’d be glad to see it gone.

For what my opinion is worth, I think that Mumi is very valuable.  Yes
it has many annoyances and even considering these, it highly improves
the situation.

As far as I know, the GNU project is not planning to move from their
Debbugs instance.  The Guix project is free to move to something else.
And although this thread is now large, it only collects ideas – that’s
good! – however we have nothing concrete for making a decision to switch
from the GNU Debbugs instance.  Well, I do not want to cut people’s
motivation, I roughly estimate to several months (maybe more than one
year) between the start of evaluations of alternatives and the effective
switch.  Waiting that, it appears to me worth to still fix the Mumi
annoyances

Maybe SourceHut is one alternative.  However, from my experience,

        PS: First time I am sending something to SourceHut... and I am a
        bit confused by the interface. Or how to send patches.

        https://todo.sr.ht/~whereiseveryone/toys/18

and after the hour I have spent this morning, it is not clear how to
fetch messages, or how to read message without the web-interface, and
how to send messages without the web-frontend, etc.  all that are not
straightforward neither.  Well, I do not also speak about the lack of
Message-ID – it does not jump to my eyes – and building a tool around
emails without Message-ID is just a bad decision.

Yes, Debbugs is not prefect.  Mumi neither.  SourceHut will not
magically fix our annoyances and this tool also brings many drawbacks.

Therefore, I still need to be convinced by concrete examples that
SourceHut provides a better experience.  For now, my feelings are mixed…
Well, I just strongly hope SourceHut fits our bill – «I hope» is not «I
know» nor «I am convinced».


Thank you contributors to Mumi!

    Ricardo Wurmus <rekado@elephly.net>
    Arun Isaac <arunisaac@systemreboot.net>
    Ludovic Courtès <ludo@gnu.org>
    Tobias Geerinckx-Rice <me@tobias.gr>
    jgart <jgart@dismail.de>

I hope you will continue to improve our annoyances. :-)


Cheers,
simon

Debbugs CLI client (was Re: Mumi CLI client (was: How can we decrease the cognitive overhead for contributors?)))

[Simon Tournier]

Hi,

On Mon, 04 Sep 2023 at 23:06, Arun Isaac <arunisaac@systemreboot.net> wrote:

> But, meanwhile, I wish to remind everyone that we already have a mumi
> CLI client that takes away some of the pain of dealing with Debbugs. It
> operates fully on the command-line and does not require Emacs at
> all. This CLI client has so far been undocumented. So, I thought it
> helpful to document it and put it into the manual. I have sent a patch
> to https://issues.guix.gnu.org/65746

Please also note that Debbugs has a CLI client.  It’s Perl scripts
targeting the Debbugs instance of the Debian project therefore they need
some tweaks as replacement of URLs, IIRC.

    https://salsa.debian.org/debian/devscripts

For instance, the help message reads:

--8<---------------cut here---------------start------------->8---
$ bts -h
Usage: bts [options] command [args] [#comment] [.|, command ... ]
Valid options are:
   -o, --offline          Do not attempt to connect to BTS for show/bug
                          commands: use cached copy
   --online, --no-offline Attempt to connect (default)
   -n, --no-action        Do not send emails but print them to standard output.
   --no-cache             Do not attempt to cache new versions of BTS
                          pages when performing show/bug commands
   --cache                Do attempt to cache new versions of BTS
                          pages when performing show/bug commands (default)
   --cache-mode={min|mbox|full}
                          How much to cache when we are caching: the sensible
                          bare minimum (default), the mbox as well, or
                          everything?
   --cache-delay=seconds  Time to sleep between each download when caching.
   -m, --mbox             With show or bugs, open a mailreader to read the mbox
                          version instead
   --mailreader=CMD       Run CMD to read an mbox; default is 'mutt -f %s'
                          (must contain %s, which is replaced by mbox name)
   --cc-addr=CC_EMAIL_ADDRESS
                          Send carbon copies to a list of users.
                          CC_EMAIL_ADDRESS should be a comma-separated list of
                          e-mail addresses.
   --use-default-cc       Send carbon copies to any addresses specified in the
                          configuration file BTS_DEFAULT_CC (default)
   --no-use-default-cc    Do not do so
   --sendmail=cmd         Sendmail command to use (default /usr/sbin/sendmail)
   --mutt                 Use mutt for sending of mails.
   --no-mutt              Do not do so (default)
   --smtp-host=host       SMTP host to use
   --smtp-username=user   } Credentials to use when connecting to an SMTP
   --smtp-password=pass   } server which requires authentication
   --smtp-helo=helo       HELO to use when connecting to the SMTP server;
                            (defaults to the content of /etc/mailname)
   --bts-server           The name of the debbugs server to use
                            (default https://bugs.debian.org)
   -f, --force-refresh    Reload all bug reports being cached, even unchanged
                          ones
   --no-force-refresh     Do not do so (default)
   --only-new             Download only new bugs when caching.  Do not check
                          for updates in bugs we already have.
   --include-resolved     Cache bugs marked as resolved (default)
   --no-include-resolved  Do not cache bugs marked as resolved
   --no-ack               Suppress BTS acknowledgment mails
   --ack                  Do not do so (default)
   -i, --interactive      Prompt for confirmation before sending e-mail
   --force-interactive    Same as --interactive, with the exception that an
                          editor is spawned before confirmation is requested
   --no-interactive       Do not do so (default)
   -q, --quiet            Only display information about newly cached pages.
                          If given twice, only display error messages.
   --no-conf, --noconf    Do not read devscripts config files;
                          must be the first option given
   -h, --help             Display this message
   -v, --version          Display version and copyright info

Default settings modified by devscripts configuration files:
  (none)

Valid commands are:
    show [<options>] [<bug number> | <package> | <maintainer> | : ] [<opt>=<val> ...]
    show [<options>] [src:<package> | from:<submitter>] [<opt>=<val> ...]
    show [<options>] [tag:<tag> | usertag:<tag> ] [<opt>=<val> ...]
    show [release-critical | release-critical/... | RC]
    bugs [<options>] [<bug_number> | <package> | <maintainer> | : ] [<opt>=<val> ...]
    bugs [<options>] [src:<package> | from:<submitter>] [<opt>=<val> ...]
    bugs [<options>] [tag:<tag> | usertag:<tag> ] [<opt>=<val> ...]
    bugs [release-critical | release-critical/... | RC]
    select [<key>:<value> ...]
    status [<bug> | file:<file> | fields:<field>[,<field> ...] | verbose] ...
    clone <bug> <new_ID> [<new_ID> ...]
    done <bug> [<version>]
    reopen <bug> [<submitter>]
    archive <bug>
    unarchive <bug>
    retitle <bug> <title>
    summary <bug> [<messagenum>]
    submitter <bug> [<bug> ...] <submitter-email>
    reassign <bug> [<bug> ...] <package> [<version>]
    found <bug> [<version>]
    notfound <bug> <version>
    fixed <bug> <version>
    notfixed <bug> <version>
    block <bug> by|with <bug> [<bug> ...]
    unblock <bug> by|with <bug> [<bug> ...]
    merge <bug> <bug> [<bug> ...]
    forcemerge <bug> <bug> [<bug> ...]
    unmerge <bug>
    tag <bug> [+|-|=] <tag> [<tag> ...]
    tags <bug> [+|-|=] <tag> [<tag> ...]
    affects <bug> [+|-|=] <package> [<package> ...]
    user <email>
    usertag <bug> [+|-|=] <tag> [<tag> ...]
    usertags <bug> [+|-|=] <tag> [<tag> ...]
    claim <bug> [<claim>]
    unclaim <bug> [<claim>]
    severity <bug> <severity>
    forwarded <bug> <address>
    notforwarded <bug>
    package [<package> ...]
    limit [<key>[:<value>]] ...
    owner <bug> <owner-email>
    noowner <bug>
    subscribe <bug> [<email>]
    unsubscribe <bug> [<email>]
    reportspam <bug> ...
    spamreport <bug> ...
    cache [<options>] [<maint_email> | <pkg> | src:<pkg> | from:<submitter>]
    cache [<options>] [release-critical | release-critical/... | RC]
    cleancache <package> | src:<package> | <maintainer>
    cleancache from:<submitter> | tag:<tag> | usertag:<tag> | <number> | ALL
    listcachedbugs [<number>]
    version
--8<---------------cut here---------------end--------------->8---


Cheers,
simon

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

[pinoaffe]

Andreas Enge <andreas@enge.fr> writes:
> Am Mon, Sep 04, 2023 at 08:44:18AM -0400 schrieb brian via Development of GNU Guix and the GNU System distribution.:
>> Regarding the GNU changelog commits, I really dislike them. They're
>> redundant busy-work as far as I'm concerned. And while I'd like to say
>> they're no longer necessary, because we have better tooling
>
> As said before, I use them all the time through
>    git log | grep "whatever I am looking for"
> or the interactive
>    git log
> then "/" for searching inside the less command; I find it useful to a point
> that I have moved to this style for all my coding projects.
>
> So as far as I am concerned, they are tremendously useful. Well, that may
> be due to a lack of git knowledge, of course! But while in other projects
> I often find I need to look at the content of commits, in Guix it is often
> enough to just look at the changelog.

I also quite like the commit messages, they've allowed me to find things
that I couldn't have found using `git blame`

Re: Mumi CLI client (was: How can we decrease the cognitive overhead for contributors?)

[Giovanni Biscuolo]

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

Hi all

Arun Isaac <arunisaac@systemreboot.net> writes:

[...]

> I have been following the conversation with much interest. There seems
> to be a developing consensus that we should switch to sourcehut.

I fear that the switch would _not_ solve many of the problems tagged as
"cognitive overhead"; the problem is "the workflow", not the tool.

«All forges suck, _no one_ sucks less» :-D (it's a joke!)

Please forgive me if I insist and/or repeat myself (and others) but:

1. sourcehut is a suite of (alpha) applications: what set of
applications we should switch to?

2. given that all *.sr.ht applications are alpha [1], would the Guix
packages for applications listed in 1. be maintainable in the _near_
future?  Also we need to package them as Guix _services_ to be useful.

3. given current resources, where do we plan to host the new services?
Are current Guix sysadmins human resources enough to give _support_ to
the new services?  Please consider that «Currently, the only officially
supported method for installing sr.ht software is through packages on
Alpine Linux hosts. [...] the installation and deployment process can
become a bit more involving. In particular, many sr.ht services have
their own, unique requirements that necessitate extra installation
steps», unless we package them for Guix (point 2.)

4. git.sr.ht (the "forge"?) implements an email based patch workflow
management and _not_ a web based pull-request workflow, it's documented
here: https://man.sr.ht/git.sr.ht/#sending-patches-upstream; so
git.sr.ht will _not_ help Guix adding a web based PR workflow, for that
we need _other_ forges, for example GitLab, Gitea/Forgejo (other?)

5. what about "git request-pull" [2] to enable a PR workflow for Guix?
It seems completely ignored by all the "forges" or am I wrong?
Unfortunately AFAIU it runs only as CLI, there is no web or GUI
interface for that

6. in what aspect todo.sr.ht (the issue tracker) is better than Debbugs
(via multiple interfaces)?  AFAIU nothing in that application is so much
better than what Guix actually use; actually Debbugs or Mumi web
interfaces are read-only: you cannot open a bug report or comment it,
you have to send an email; this is a _feature_, not a bug since we don't
need a _complex_ web based authentication+authorization system for bug
reporters/commenters.  Please also consider that the emacs Debbugs
interface is very useful, I'd miss a similar interface for todo.sr.ht
(but there is a CLI for sourcehut web services)

7. last, but not least: a public-inbox instance (https://yhetil.org/)
helps a lot people who is not subscribed to a mailing list with email
replies (e.g https://yhetil.org/guix-bugs/87il8qrm53.fsf@gmail.com/#R)
**and** patch downloading; IMHO it should be officially provided by Guix

> I am all in favour of any decision the community comes to on this.

I just hope the decision comes after an analysis of each single problem,
otherwise there is a chance that different tools will not solve the
problems

[...]

> So, I thought it helpful to document it and put it into the manual. I
> have sent a patch to https://issues.guix.gnu.org/65746

Very good work, thanks Arun!

Happy hacking, Gio'


[1] https://man.sr.ht/packages.md

[2] https://www.git-scm.com/docs/git-request-pull

-- 
Giovanni Biscuolo

Xelera IT Infrastructures

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

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

[Csepp]

Maxim Cournoyer <maxim.cournoyer@gmail.com> writes:

> Hi Ricardo,
>
> Ricardo Wurmus <rekado@elephly.net> writes:
>
>> Vagrant Cascadian <vagrant@debian.org> writes:
>>
>>> The only thing clunky about this particular aspect of the workflow
>>> described is the fact that the guix community (maintainers?) have
>>> decided on a one patch per mail policy with a cover letter, rather than
>>> submitting the patches as attachments in the initial mail.
>>
>> You are right.  When I started contributing I actually did attach all
>> patches in one email.  I wonder why we stopped doing that.
>
> It's still allowed as far as I know.  But due to missing out on
> notifying team members automatically (handled by 'git send-email') and
> sometimes causing issues for reviewers to apply patches, it's
> understandable that 'git send-email' is the most recommended option.
>
>> I’ll say that many of my gripes with (the GNU instance of) Debbugs are
>> due to the fact that we can’t customize it to better suit our needs — it
>> is a shared resource with a complicated maintenance story.  So all
>> changes went into Mumi as crude workarounds.  I think this is a dead end
>> and we’d be better off leaving the shared GNU instance of Debbugs
>> behind.
>
> I'd be sad to loose at least two good things from Debbugs:
>
> 1. It's hosted by the GNU/FSF for us.  It always work, and the rare
> times it doesn't, the folks in #savannah are hard at work resolving the
> problems. While hosting sourcehut is probably not too difficult, keeping
> it up to date (Go...) and running would be yet another weigh on our
> meager sysadmin team.
>
> 2. Integration with Emacs.  emacs-debbugs is useful.  I think it's the
> only successful thing we have at keeping track of old tickets and
> resuming discussion or acting on these.

Doesn't Magit have a generic forge integration?

> I like how clean Mumi looks, compared to most forge issue trackers.  I'm
> not convinced by its search results (perhaps I'd need to get to know
> what Xapian is).

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

[Csepp]

Andreas Enge <andreas@enge.fr> writes:

> Am Mon, Sep 04, 2023 at 08:44:18AM -0400 schrieb brian via Development of GNU Guix and the GNU System distribution.:
>> >  - strict adherence to changelog style commit messages without a
>> >    clearly worded and documented argument about why it's worth the
>> >    effort in 2023. whenever 'C' fails to add an entry to the commit
>> >    message in Emacs, i groan out loud.
>> Regarding the GNU changelog commits, I really dislike them. They're
>> redundant busy-work as far as I'm concerned. And while I'd like to say
>> they're no longer necessary, because we have better tooling
>
> As said before, I use them all the time through
>    git log | grep "whatever I am looking for"
> or the interactive
>    git log
> then "/" for searching inside the less command; I find it useful to a point
> that I have moved to this style for all my coding projects.
>
> So as far as I am concerned, they are tremendously useful. Well, that may
> be due to a lack of git knowledge, of course! But while in other projects
> I often find I need to look at the content of commits, in Guix it is often
> enough to just look at the changelog.
>
> Andreas

What's wrong with grepping the contents as well?

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

[Simon Tournier]

Hi Katherine,

Thank you for your extensive analysis.  I concur.

On Wed, 30 Aug 2023 at 10:11, Katherine Cox-Buday <cox.katherine.e@gmail.com> wrote:

> 3. We should reify a way for Guix, the project, to measure, and track 
> progress,
>     against long-term goals. Particularly when they're social and not 
> strictly
>     technical.

That is the most difficult part, IMHO.  Well, what are the long-term
goals? :-)

I am almost sure we will get various answers depending on people.  Let
say the long-term goals of the Guix project are: Liberating, Dependable
and Hackable.  Then how do you give concrete quantities that we can
measure or track?

And it is always difficult, if not impossible, to measure or track some
goals that are not technical but social.  For example, how do you
measure being welcoming or being a safe place for all?

Do not take me wrong, I strongly think we must think again and again on
that point for improving.  It’s just easier to tackle technical bug. :-)


>    11. Try and get each commit message close to correct and commit.

> I view steps 1-10 as pretty standard "development" steps common to most
> projects, although 11 compounds the effort in 10.

Maybe I am doing incorrectly but I have never thought much about that.

For that point #11, from my point of view, it is as with any other
project.  I start by running “git log --grep=” for getting inspiration.

Well, as a rule of thumb, I am doing something like:

--8<---------------cut here---------------start------------->8---
top-module: submodule: one line summary.

Fixes <https://issues.guix.gnu.org/12345>.
Reported by Jane Doe <jane@doe.org>

* path/to/file.scm (variable):[sub-part]: Description of the change.
[otherpart]: Other description.
* path/to/other/file.scm (other-variable): Description.
--8<---------------cut here---------------end--------------->8---

In case of doubt, I am just running “git log --grep=” looking for
similar thing, as said. :-)


>    12. Run `guix lint`
>    13. Run `guix style` (this is still in the manual although I have since
>        learned this is not actually advisable).
>    14. Review the changes these tools have made, and fix things.
>    15. Run `guix build --rounds=2 <package>` to check for idempotency.
>    16. Run `make` to ensure you didn't break anything elsewhere in Guix.
>    17. Run `guix size` to ensure the closure isn't becoming bloated.
>    18. Build all the packages that depend on this package.
>    19. Run `guix pull --url=/path/to/your/checkout 
> --profile=/tmp/guix.master` to
>        ensure you didn't break Guix in a different way.

> 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 not feasible due to asymmetric resources. But having the
> option to let CI manage this process is very nice.

For instance, I am not seeing “make check”. ;-)  And that omission makes
very clear the cognitive overhead we are speaking about!

Here I see two annoyances:

 1. The number of subcommands and steps.
 2. Each subcommand has a list of options to digest.

Well, CI is helpful here, for sure.  However, it would be helpful to
have a script similar as etc/teams.scm or etc/committer.scm that would
help to run all these steps.

It does not mean that all these steps need to be run before each
submission.  However having a tool would help irregular contributors or
newcomers; it would decrease the cognitive overhead i.e., that overhead
would be pushed to some script and it would reinforce confidence.

Now someone™ needs to implement this script. ;-)


>    20. Run `git format-patch -1 --cover-letter [--reroll-count]`
>    21. Run `./pre-inst-env ./etc/teams.scm cc-members <patch>` to get 
> the CC flags for Git
>    22. Remember that if you're sending multiple patches, an email first 
> has to be
>        sent to `guix-patches@gnu.org` to get an ID, and then...
>    23. Run `git send-email --to guix-patches <patches> <CC flags>`

Well, my grey hair are biasing my opinion. ;-)  From my point of view,
the most annoying is #22.

Vagrant suggested [1] to send patches as attachment.  I am not convinced
it will be better.  Well, it will for submitting but will not for
following series.  For instance, let consider:

    [bug#65010] [PATCH 0/8] Misc Python build system improvements
    Lars-Dominik Braun <lars@6xq.net>
    Wed, 02 Aug 2023 12:37:57 +0200
    id:cover.1690972374.git.lars@6xq.net
    https://issues.guix.gnu.org//65010
    https://issues.guix.gnu.org/msgid/cover.1690972374.git.lars@6xq.net
    https://yhetil.org/guix/cover.1690972374.git.lars@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-contributions@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 <vagrant@debian.org>
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,

--8<---------------cut here---------------start------------->8---
$ 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.
--8<---------------cut here---------------end--------------->8---

And because there is some variation with the commit message format,
these are not all the updates of VLC,

--8<---------------cut here---------------start------------->8---
$ 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].
--8<---------------cut here---------------end--------------->8---

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.


> 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?

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

pinoaffe <pinoaffe@gmail.com> writes:

> Andreas Enge <andreas@enge.fr> writes:
>> So as far as I am concerned, they are tremendously useful. Well, that may
>> be due to a lack of git knowledge, of course! But while in other projects
>> I often find I need to look at the content of commits, in Guix it is often
>> enough to just look at the changelog.
>
> I also quite like the commit messages, they've allowed me to find things
> that I couldn't have found using `git blame`

There's a trade-off, though. They seem to have their uses for some
people, though it doesn't appear to me to be majority of people, on some
occasions (the relative number of which I can't guess, since I don't use
them at all). However, there's a cost, too. The very existence of them
as a requirement puts at least some people off from submission at all,
it adds to the work of people who still put in the effort to submit
(especially so for people not using Emacs!), it's an extra check for
committers to go through. If the check fails, the patch can get bounced
back for (to me) trivial reasons, or, best case, the committer fixes the
error themselves. But even in the best case, since the commit hash has
now changed, it causes ‘git branch -d’ to issue a warning about unmerged
commits.

I, clearly, do not think the trade-off is worth it.

-bjc

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

[Maxim Cournoyer]

Hi,

brian via "Development of GNU Guix and the GNU System distribution."
<guix-devel@gnu.org> writes:

> pinoaffe <pinoaffe@gmail.com> writes:
>
>> Andreas Enge <andreas@enge.fr> writes:
>>> So as far as I am concerned, they are tremendously useful. Well, that may
>>> be due to a lack of git knowledge, of course! But while in other projects
>>> I often find I need to look at the content of commits, in Guix it is often
>>> enough to just look at the changelog.
>>
>> I also quite like the commit messages, they've allowed me to find things
>> that I couldn't have found using `git blame`
>
> There's a trade-off, though. They seem to have their uses for some
> people, though it doesn't appear to me to be majority of people, on some
> occasions (the relative number of which I can't guess, since I don't use
> them at all). However, there's a cost, too. The very existence of them
> as a requirement puts at least some people off from submission at all,
> it adds to the work of people who still put in the effort to submit
> (especially so for people not using Emacs!), it's an extra check for
> committers to go through. If the check fails, the patch can get bounced
> back for (to me) trivial reasons, or, best case, the committer fixes the
> error themselves. But even in the best case, since the commit hash has
> now changed, it causes ‘git branch -d’ to issue a warning about unmerged
> commits.
>
> I, clearly, do not think the trade-off is worth it.

While experimenting with package builds, it's frequent to add inputs
while testing.  It can be easy to forget about them later when preparing
the commit message.  Typing them out in your commit message forces you
to sign on these changes as 'intended'.

I find them useful for that purpose and frequently catch problems in my
commits while writing the associated changelog (in other words, it
forces me to review my own code).

While 'git log -G' can be useful, it doesn't replace changelog commit
messages, which are much faster (cheaper) to go through with 'git log
--grep='.

-- 
Thanks,
Maxim

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

[Maxim Cournoyer]

Hi,

Csepp <raingloom@riseup.net> writes:

[...]

>>> Regarding the GNU changelog commits, I really dislike them. They're
>>> redundant busy-work as far as I'm concerned. And while I'd like to say
>>> they're no longer necessary, because we have better tooling
>>
>> As said before, I use them all the time through
>>    git log | grep "whatever I am looking for"
>> or the interactive
>>    git log
>> then "/" for searching inside the less command; I find it useful to a point
>> that I have moved to this style for all my coding projects.
>>
>> So as far as I am concerned, they are tremendously useful. Well, that may
>> be due to a lack of git knowledge, of course! But while in other projects
>> I often find I need to look at the content of commits, in Guix it is often
>> enough to just look at the changelog.
>>
>> Andreas
>
> What's wrong with grepping the contents as well?

It's like a 100 times slower, at least on my low spec machine.  It's
also not as obvious (you search for lines added or removed or changed,
not easy language such as 'gnu: package-name: Add').

-- 
Thanks,
Maxim

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

[Simon Tournier]

Hi,

On Tue, 29 Aug 2023 at 13:05, Giovanni Biscuolo <g@xelera.eu> wrote:

> In other words: you can contribute to a SourceHut hosted project with
> patches (or just with comments to patches) because everyone can send an
> email to an email address provided by the project maintainer(s).

Just to point that what to put in the field To: or Cc: is not
straightforward when contributing to a project hosted on a Sourcehut
instance, from my experience.

And it does not also appear to me straightforward to fetch past
discussions.

Cheers,
simon

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

[Simon Tournier]

Hi,

On Mon, 28 Aug 2023 at 23:00, Maxim Cournoyer <maxim.cournoyer@gmail.com> wrote:

>> If someone has use cases for the ChangeLog commits, I'd like to hear
>> them. Maybe there is something that can't be achieved with git history
>> without ChangeLogs, but I can't think of anything. Someone mentioned
>> grepping the git log with them, but I think the same thing can be done
>> with git log and git blame regardless of the commit message format.
>
> 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.
>
> 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).

I agree with Maxim. :-)

At first, I found weird the ChangeLog commit format and now it forces
some discipline on me that I find that beneficial.

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?

Even, it is that format (discipline) which makes “git log” efficient,
IMHO.

As an exercise, try to find the last 5 commits modifying the procedure
’haskell-build’,

        $ git log --format="%h %s" --grep=haskell-build -5
        2c0537d374 gnu: idris: Adapt to changed haskell-build-system.
        dc3e22f4d5 build: haskell-build-system: Build static executables by default.
        4bb40b098d build-system: haskell: Drop default "static" output.
        9262c14d73 build: haskell-build-system: Remove unused linker flags.
        39c97cf3d0 build: haskell-build-system: Process all transitive dependencies.

Cheers,
simon

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

[Katherine Cox-Buday]

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".

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

[Katherine Cox-Buday]

On 9/4/23 7:32 PM, Maxim Cournoyer wrote:

>>    13. Run `guix style` (this is still in the manual although I have since
>>        learned this is not actually advisable).
> 
> The intent is for it to be advisable -- when it's not, a bug should
> be/have been reported against it to track its resolution.

Thanks, Simon. I only became aware that it has quirks and should not be 
blindly trusted by reading through this thread. In the future, I'll 
modify my workflow to still run it, but treat it as untrustworthy, check 
its results, and report bugs against it.

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

[Katherine Cox-Buday]

On 9/5/23 8:01 AM, Simon Tournier wrote:
> Hi Katherine,
> 
> Thank you for your extensive analysis.  I concur.
> 
> On Wed, 30 Aug 2023 at 10:11, Katherine Cox-Buday <cox.katherine.e@gmail.com> wrote:
> 
>> 3. We should reify a way for Guix, the project, to measure, and track
>> progress,
>>      against long-term goals. Particularly when they're social and not
>> strictly
>>      technical.
> 
> That is the most difficult part, IMHO.  Well, what are the long-term
> goals? :-)
> 
> I am almost sure we will get various answers depending on people.  Let
> say the long-term goals of the Guix project are: Liberating, Dependable
> and Hackable.  Then how do you give concrete quantities that we can
> measure or track?

I think starting at the top and trying to derive concrete quantities 
from values is a healthy exercise. I agree that it's difficult, but 
without doing that it's easy to be left in an echo-chamber where your 
project isn't actually accomplishing any of the things you'd like it to.

However, my point (3) above is a little different and easier. Here we 
have a lower-level goal that is a closer to a concrete quantity: "The 
overhead of contributing to Guix should be low." There are various ways 
to reduce this further, but they are tightly coupled to the method of 
measurement. In other words, what you measure will be what you manage, 
so choose what you measure carefully.

> And it is always difficult, if not impossible, to measure or track some
> goals that are not technical but social.  For example, how do you
> measure being welcoming or being a safe place for all?

I think the easiest way to start, and something that's actually pretty 
effective, is to start doing annual surveys, e.g.:

- https://discourse.nixos.org/t/2022-nix-survey-results/18983
- https://survey.stackoverflow.co/2023/
- https://tip.golang.org/blog/survey2023-q1-results

This thread turned out to be an informal survey, and I think it's easy 
to see that some people are happy with how things are, and some people 
would like to see change.

With a survey you can quantify these opinions and say things like "X% of 
people would like the current contribution process to remain the same. 
Y% of those are committers."

This can help reveal larger patterns, and over time, trends.

> Do not take me wrong, I strongly think we must think again and again on
> that point for improving.  It’s just easier to tackle technical bug. :-)

It's definitely not as easy as tackling a technical bug. I think as 
engineers we often have a difficult time admitting to ourselves that 
efficacy is much more than the perfect algorithm or the mechanical 
shuffling of things around. Do we want Guix to be a fun technical 
exercise? Or do we want it to fulfill its stated goals? Why not both! :)

> Here I see two annoyances:
> 
>   1. The number of subcommands and steps.
>   2. Each subcommand has a list of options to digest.
> 
> Well, CI is helpful here, for sure.  However, it would be helpful to
> have a script similar as etc/teams.scm or etc/committer.scm that would
> help to run all these steps.

Yes, and commonly whatever you would use for CI is the same thing you 
would run locally. This is intentional so that you can have some 
confidence that CI will pass.

> It does not mean that all these steps need to be run before each
> submission.  However having a tool would help irregular contributors or
> newcomers; it would decrease the cognitive overhead i.e., that overhead
> would be pushed to some script and it would reinforce confidence.

And then although we've reduced the cognitive overhead globally, we've 
increased it locally by introducing another conditional: "do I need to 
run the CI script? how do i know?" The script could probably decide this 
too.

> Now someone™ needs to implement this script. ;-)

Collectively, I don't think we've arrived at a consensus on

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.

> 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.

You're correct, you usually have to have an account on some forge 
website. Think of how various solutions scale: do you have to create an 
account on a forge website every time you make a commit?

And the point of that section was trying to think about what the forge 
website's button does for the committer, and less about stating that its 
superior or that we should definitely adopt it.

A lot of this thread has turned into a debate on specific tools instead 
of thinking about what the underlying problems are, and the various ways 
to address those. Tooling is an implementation detail.

> 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.

My intention was for it to be about the complexity/overhead in 
aggregate. Collected, I think all the steps, and their flags, and the 
decisions that go into which steps, and which flags, and what values, 
should be considered as "complex".

> Well, it is a well-known issue about task switching [1]. :-)
> 
> 1: https://en.wikipedia.org/wiki/Task_switching_(psychology)

That it is! And what's the first line in that article? "Task switching, 
or set-shifting, is an executive function[...]".

So are we unintentionally filtering out contributions from people with 
compromised executive functioning?

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

[Katherine Cox-Buday]

On 9/3/23 1:36 AM, Ricardo Wurmus wrote:

>> Why are we trying to compete with Sourcehut?  What's the end goal?
> 
> I can’t make myself even clearer about this, but I’ll repeat myself
> again: we are not.
> 
> “Competition” is a foreign concept to me.  Mumi exists only because I
> found the Debbugs web interface kinda ugly and alienating.  It’s a hack
> that obviously outlived its welcome.  I have to admit that messages like
> this make me regret scratching this itch that gave rise to Mumi in 2016.
> (Sourcehut started in 2018.)

I think you've already addressed this, but I wanted to plainly state 
that I appreciate your work on Mumi. Even if we decide to move on, it 
fulfilled a need for this period of time in Guix's life, and I thank you 
for it.

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

[Liliana Marie Prikler]

Am Dienstag, dem 05.09.2023 um 11:01 -0600 schrieb Katherine Cox-Buday:
> 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".
Uhm, we have snippets?

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

[(]

Liliana Marie Prikler <liliana.prikler@gmail.com> 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.

  -- (

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

[Csepp]

Maxim Cournoyer <maxim.cournoyer@gmail.com> writes:

> Hi,
>
> Csepp <raingloom@riseup.net> writes:
>
> [...]
>
>>>> Regarding the GNU changelog commits, I really dislike them. They're
>>>> redundant busy-work as far as I'm concerned. And while I'd like to say
>>>> they're no longer necessary, because we have better tooling
>>>
>>> As said before, I use them all the time through
>>>    git log | grep "whatever I am looking for"
>>> or the interactive
>>>    git log
>>> then "/" for searching inside the less command; I find it useful to a point
>>> that I have moved to this style for all my coding projects.
>>>
>>> So as far as I am concerned, they are tremendously useful. Well, that may
>>> be due to a lack of git knowledge, of course! But while in other projects
>>> I often find I need to look at the content of commits, in Guix it is often
>>> enough to just look at the changelog.
>>>
>>> Andreas
>>
>> What's wrong with grepping the contents as well?
>
> It's like a 100 times slower, at least on my low spec machine.  It's
> also not as obvious (you search for lines added or removed or changed,
> not easy language such as 'gnu: package-name: Add').

Hmm, that's a quite valid criticism.  I haven't tried grepping commit
contents on my netbook yet, but this suggests that it would be pretty
slow.
But some info is still redundant, like file names.  Git already supports
getting the history of a file, so file names might not be necessary in
the log.
I agree that important identifiers should still be mentioned, but I'm
not sure if the current format is the best way to do that.

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

[Katherine Cox-Buday]

Thank you for your thoughtful comments, Giovanni!

On 9/2/23 5:16 AM, Giovanni Biscuolo wrote:

>> 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.

I enumerated the underlying issues that both my suggestions would address:

    - QA status should be visible from a patch's page
    - It should be possible to interact with the issue through the page

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.

Please notice that under my first suggestion, I was calling out points 
about how QA status shows up, and switching between tools to interact 
with issues, not specifically how to prepare/apply patches.

> 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.

Defaults matter, and I don't view it as a valid starting-point to state 
that contributors can manage intrinsic complexity on their own. I think 
that's where we're at right now, and it's why I created this thread.

>>      - 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!

Agreed! I called out Mumi as helpful but also highlighted some areas for 
improvement:

In a web-forge, I generally have a URL I can go to and see everything 
about my patch. I think we have that with https://issues.guix.gnu.org 
with two exceptions: (1) QA is a click away, or if you're using email, 
you're not even aware that there's a QA process failing (2) If you're 
not using email, context-switching between this page and email to respond.

>> - It should be possible to interact with the issue through the page
> 
> I don't exactly understand: what do you mean with "interact"?

It should be possible to perform almost all meta-activities against an 
issue through its page:

- Manage status (close, re-open)
- Manage tags
- Request reviewers
- See CI status including high-level reason(s) for failure
- Apply to parent branch
- Respond to comments

> ...and what page?  https://issues.guix.gnu.org/ or
> https://qa.guix.gnu.org/issue/65694 (or any other issue)

Right now I'd hold up https://issues.guix.gnu.org/ as our best example.

>> 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?

It's not a stand-alone script that I can share unfortunately. It's 
functions integrated into a more complicated system. However, it's 
pretty straightforward to recreate: anywhere there's a decision-point, 
infer the correct decision (e.g. check dependencies on a package to 
determine which branch a commit should go in), execute the list of 
steps, give a human-friendly description of anything that went wrong, 
and offer suggestions on how to correct it.

>> For me, steps 20-23 are bothersome. There's a lot of "if" statements
>> that lead
>> to branching operations, and a lot of commands and flags to get
>> right.
> 
> oh yes, CLI is a cognitive overhead sometimes, so we need better
> interfaces, some have found them

I loathe working with workflows that don't have integration points, and 
so I *love* CLI tools. But I don't like having to be the computer and 
walking through a workflow while filling all the blanks in.

> actually, point 21 "Run `./pre-inst-env ./etc/teams.scm cc-members
> <patch>` to get the CC flags for Git" is bothersome and we should find a
> way to better integrate that in "git format-patch" (so that will be
> automatically used in all the git interfaces we use)
> 
>> The extra step to get a debbugs ID is annoying.
> 
> have you tried mumi CLI with the new feature?

No, I've never used the mumi CLI.

> Forgive me if I insist: that forge site is _not_ SourceHut
> 
> Second: each forge web site have a custom (not standard) way to manage
> pull-requests.

OK. I am not particularly attached to any one tool. I only care about 
reducing the complexity. I was responding to a message requesting 
specific suggestions, and Sourcehut has been brought up.

> Third: git have a pull-request mechanism [1] that could _easily_ be
> integrated in each and every forge, allowing projects to use
> /interoperable/ email based pull-request workflows if they want to.

Great! Let's talk about all the solutions so we find one that meets our 
defined criteria.

> IMO the
> core and most cognitive challenging steps of all "CI steps" are not if
> builds are done locally or not but (in order of importance):
> 
> 1. having patches reviewed by humans, the "not automatable" part because
> Someone™ have to understand the _meaning_ of the patch and verify it
> conforms to the coding standards of the project, including "changelog
> style" commit messages;

I think the complexity required to contribute and having patches 
reviewed by humans are causally and cyclically linked. I would like to 
contribute much more to Guix, and others have said the same in this 
thread. Some of these issues we're discussing are preventing people from 
doing so.

I.e., would you rather have:

1. 10 very efficient contributors
2. 1,000 moderately efficient contributors

Wouldn't it be great if we had both?

> 2. understanding why build derivation fail when it fails.
> 
> This is real cognitive overhead and this cannot be automated.

I disagree with this, but that's another conversation.

>> - Steps 19-23, or the "manage patch" steps.
>>
>>     I think an insight here is that the big button on forges is actually
>> a program
>>     removing the mental overhead for you.
> 
> On the "web forges" vs "email based" patch workflow management I've said
> enough in other messages in this thread, here I just want to add
> (repeat) this: please do not only consider the mental overhead of
> potential contributors for "managing patches", also consider the mental
> overhead for patch reviewers; I've read many articles from professional
> patch reviewers that perfectly explains the great advanteges of using an
> email based workflow

It's a good point. We should remain focused on the overall complexity of 
the complete workflow of getting working code into Guix.

>>     I also don't usually have to worry nearly as much about crafting a commit
>>     message. So long as the title is under a character limit, and the body is
>>     helpful, it's OK. I think what bothers me most about the GNU changelog
>>     messages is that it's the worst of both spoken language and programming
>>     languages: there's an expectation of structure, but no grammar I can
>> parse
>>     against, and it's free-form.
> 
> I'm sorry that the GNU policy about commit messages bothers you (on the
> contrary it makes me happy); please consider that thai is /just/ one of
> the policies of the Guix project: code of conduct, coding standards,
> others?

I recently responded to a similar question/point in another message from 
Simon about this being similar to style standard:

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".

> it's "just" an _interface_ issue

I think I would agree with this! I don't know that there's an inherent 
complexity in the individual steps. It's the aggregate of managing the 
workflow and tools that I think makes things complicated.

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

[Csepp]

Simon Tournier <zimon.toutoune@gmail.com> writes:

> Hi,
>
> On Tue, 29 Aug 2023 at 13:05, Giovanni Biscuolo <g@xelera.eu> wrote:
>
>> In other words: you can contribute to a SourceHut hosted project with
>> patches (or just with comments to patches) because everyone can send an
>> email to an email address provided by the project maintainer(s).
>
> Just to point that what to put in the field To: or Cc: is not
> straightforward when contributing to a project hosted on a Sourcehut
> instance, from my experience.
>
> And it does not also appear to me straightforward to fetch past
> discussions.
>
> Cheers,
> simon

There are mbox downloads on lists.sr.ht.
Random example from my browser history:
https://lists.sr.ht/~lioploum/forevercomputer
There is an mbox download for the entire archive and another for the
last 30 days.
Then for a thread there is a "forward this thread to me" and again an
mbox download.
https://lists.sr.ht/~lioploum/forevercomputer/%3CCAGSYXA5kbt9Y3i%3D8UjQp0VNmczCRvcY89ZYyaCyc9VGpsPgyXg%40mail.gmail.com%3E

I think the UI is pretty clear.
I quite like that it makes offline work really easy.

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

[Wilko Meyer]

Csepp <raingloom@riseup.net> writes:
>
> Doesn't Magit have a generic forge integration?
>

There's forge.el[1] which is part of the magit project. It's not too
generic though, as it only supports Gitlab (which applies to self-hosted
instances/hosted instances such as e.g. salsa.debian.org) and
Github[2]. Magit itself doesn't come with forge support iirc.

[1]: https://github.com/magit/forge
[2]: https://magit.vc/manual/forge/Supported-Forges.html

-- 
Kind regards,
Wilko Meyer
w@wmeyer.eu

Guix User Survey?

[Wilko Meyer]

Hi Guix,

Katherine Cox-Buday <cox.katherine.e@gmail.com> writes:
>
> I think the easiest way to start, and something that's actually pretty
> effective, is to start doing annual surveys, e.g.:
>
> - https://discourse.nixos.org/t/2022-nix-survey-results/18983
> - https://survey.stackoverflow.co/2023/
> - https://tip.golang.org/blog/survey2023-q1-results
>

I think this is an excellent idea to have a means of mapping out guixes
community and values. This years curl user survey[1] asked specifically
what prevents curl users from contributing (p.20) as well as asked to
rank the "best/worst" areas (p.24-26) of the project. I think that
asking the broader guix community these specific questions could be
beneficial in answering the initial question of this thread on how to
decrease the cognitive overhead for contributors/lowering the barrier to
contribute to Guix.

Furthermore, it could also be beneficial to collect informations on what
hardware the guix community uses (running a hardware survey was at least
mentioned once on this list[2]) and what people are actually doing with
Guix (the "Guix and the developer ecosystem" discussion[3] could be
related to that).

> With a survey you can quantify these opinions and say things like "X%
> of people would like the current contribution process to remain the
> same. Y% of those are committers."

Right now we only do have the opinions of folks reading and actively
posting to the mailing list; which may be a way smaller group than
guixes actual userbase. At least I'd say it's safe to assume that there
may be guix users who do not read guix-devel, as well as those who read
this list but don't actively post to it. A survey could lead to more
representative results in that regards, as it may enable more folks to
participate.

As far as I know NixOS uses a hosted LimeSurvey for their surveys, which
should be free software; even though it doesn't seem to be packaged for
Guix yet. If there's a consensus that such a survey may be a good idea,
I'd be happy to contribute to it; even though I'm not familiar enough
with the governance part of guix as a project to get things started (I
suspect discussing this on this mailing list is a good start?).

[1]: https://daniel.haxx.se/media/curl-user-survey-2023-analysis.pdf
[2]: https://lists.gnu.org/archive/html/guix-devel/2022-10/msg00297.html
[3]: https://lists.gnu.org/archive/html/guix-devel/2023-07/msg00152.html

-- 
Kind regards,
Wilko Meyer
w@wmeyer.eu

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

[Liliana Marie Prikler]

Am Dienstag, dem 05.09.2023 um 19:40 +0100 schrieb (:
> Liliana Marie Prikler <liliana.prikler@gmail.com> 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)?

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

[Simon Tournier]

Hi,

Thanks for these pointers.  Therefore I am asking more naive questions. :-)

On Tue, 5 Sept 2023 at 21:19, Csepp <raingloom@riseup.net> wrote:

> There are mbox downloads on lists.sr.ht.
> Random example from my browser history:
> https://lists.sr.ht/~lioploum/forevercomputer

If I understand correctly, this
<https://lists.sr.ht/~whereiseveryone/guixrus/patches> is the
equivalent to Debbugs (guix-patches) with a front-end as Mumi.
However, it adds CI feedback.  What is confusing is the lack of clear
links between all these: https://lists.sr.ht/~whereiseveryone/guixrus
and https://git.sr.ht/~whereiseveryone/guixrus and
https://todo.sr.ht/~whereiseveryone/guixrus and
https://builds.sr.ht/~whereiseveryone/guixrus.

How do you know that the patch had already been applied?  There is the
term APPLIED appearing in the web front-end.  How can I fetch this
information without opening my web-browser?

What is the equivalent of
<https://lists.gnu.org/archive/html/bug-guix/>?  How can I download
the messages of e.g., https://todo.sr.ht/~whereiseveryone/guixrus ?

Well, I am probably asking too much at this step of the discussion,
but let ask. :-)  I have a bridge from the Emacs front-end of Debbugs
that downloads all the messages from a thread corresponding to one
specific issue; all from Emacs and without opening any webbrowser.
Would it be possible to do the same with Sourcehut?  When I read my
emails from my email client, I would like to be able to  download the
complete thread of the email I am reading; for instance, that matters
when someone replies to an old bug that I do not have yet locally.  I
mean, I am sure all will be possible. :-)  Instead, I am asking: is it
already possible?

As Maxim said elsewhere [1], one good thing from Debbugs is the
integration with Emacs. Yeah, I know that some of us are maybe too
much Emacs-centric. :-)  Even if the Debbugs SOAP interface is clunky,
the package emacs-debbugs provides enough procedures for writing
custom helpers.  For example, when I process my emails using
emacs-notmuch, I can quickly mark some bugs, say tagging moreinfo, the
sequence is I hit is: b C moreinfo RET.  Or I can check the status of
the bug I read from my email, I just press: C.

My question is not about will it be possible?  It will, because
Sourcehut exposes an API. :-)  My question is: is it already possible?
 For instance, emacs-srht seems able to only interact with the Git and
Paste services.

People not using Emacs and using Sourcehut for other projects, how do
you interact with the Sourcehut lists patch submission from your email
client without using your web-browser?  Or with the Sourcehut todo bug
tracker from your email client without using your web-browser?


1: Re: How can we decrease the cognitive overhead for contributors?
Maxim Cournoyer <maxim.cournoyer@gmail.com>
Mon, 04 Sep 2023 22:18:22 -0400
id:87edjdqs5t.fsf@gmail.com
https://lists.gnu.org/archive/html/guix-devel/2023-09
https://yhetil.org/guix/87edjdqs5t.fsf@gmail.com

Cheers,
simon

PS:

> I think the UI is pretty clear.

Well, I am probably not the only one confused by the UI of Sourcehut. :-)

https://lists.gnu.org/archive/html/emacs-devel/2021-12/msg02159.html

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

[wolf]

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

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 <liliana.prikler@gmail.com> 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?

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 ...').

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?

> 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)?
>

W.

-- 
There are only two hard things in Computer Science:
cache invalidation, naming things and off-by-one errors.

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

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

[wolf]

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

On 2023-09-05 16:01:17 +0200, Simon Tournier wrote:
> Hi Katherine,
> 
> Thank you for your extensive analysis.  I concur.
> 
> On Wed, 30 Aug 2023 at 10:11, Katherine Cox-Buday <cox.katherine.e@gmail.com> wrote:
> 
> > 3. We should reify a way for Guix, the project, to measure, and track 
> > progress,
> >     against long-term goals. Particularly when they're social and not 
> > strictly
> >     technical.
> 
> That is the most difficult part, IMHO.  Well, what are the long-term
> goals? :-)
> 
> I am almost sure we will get various answers depending on people.  Let
> say the long-term goals of the Guix project are: Liberating, Dependable
> and Hackable.  Then how do you give concrete quantities that we can
> measure or track?
> 
> And it is always difficult, if not impossible, to measure or track some
> goals that are not technical but social.  For example, how do you
> measure being welcoming or being a safe place for all?
> 
> Do not take me wrong, I strongly think we must think again and again on
> that point for improving.  It’s just easier to tackle technical bug. :-)
> 
> 
> >    11. Try and get each commit message close to correct and commit.
> 
> > I view steps 1-10 as pretty standard "development" steps common to most
> > projects, although 11 compounds the effort in 10.
> 
> Maybe I am doing incorrectly but I have never thought much about that.
> 
> For that point #11, from my point of view, it is as with any other
> project.  I start by running “git log --grep=” for getting inspiration.
> 
> Well, as a rule of thumb, I am doing something like:
> 
> --8<---------------cut here---------------start------------->8---
> top-module: submodule: one line summary.
> 
> Fixes <https://issues.guix.gnu.org/12345>.
> Reported by Jane Doe <jane@doe.org>
> 
> * path/to/file.scm (variable):[sub-part]: Description of the change.
> [otherpart]: Other description.
> * path/to/other/file.scm (other-variable): Description.
> --8<---------------cut here---------------end--------------->8---
> 
> In case of doubt, I am just running “git log --grep=” looking for
> similar thing, as said. :-)
> 
> 
> >    12. Run `guix lint`
> >    13. Run `guix style` (this is still in the manual although I have since
> >        learned this is not actually advisable).
> >    14. Review the changes these tools have made, and fix things.
> >    15. Run `guix build --rounds=2 <package>` to check for idempotency.
> >    16. Run `make` to ensure you didn't break anything elsewhere in Guix.
> >    17. Run `guix size` to ensure the closure isn't becoming bloated.
> >    18. Build all the packages that depend on this package.
> >    19. Run `guix pull --url=/path/to/your/checkout 
> > --profile=/tmp/guix.master` to
> >        ensure you didn't break Guix in a different way.
> 
> > 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 not feasible due to asymmetric resources. But having the
> > option to let CI manage this process is very nice.
> 
> For instance, I am not seeing “make check”. ;-)  And that omission makes
> very clear the cognitive overhead we are speaking about!

I personally am glad it is not there, since I never (in ~9 months toying with
Guix) had all the checks pass on the clear master.  There are always one or two
failing tests.

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?

> 
> Here I see two annoyances:
> 
>  1. The number of subcommands and steps.
>  2. Each subcommand has a list of options to digest.
> 
> Well, CI is helpful here, for sure.  However, it would be helpful to
> have a script similar as etc/teams.scm or etc/committer.scm that would
> help to run all these steps.
> 
> It does not mean that all these steps need to be run before each
> submission.  However having a tool would help irregular contributors or
> newcomers; it would decrease the cognitive overhead i.e., that overhead
> would be pushed to some script and it would reinforce confidence.
> 
> Now someone™ needs to implement this script. ;-)
> 
> 
> >    20. Run `git format-patch -1 --cover-letter [--reroll-count]`
> >    21. Run `./pre-inst-env ./etc/teams.scm cc-members <patch>` to get 
> > the CC flags for Git
> >    22. Remember that if you're sending multiple patches, an email first 
> > has to be
> >        sent to `guix-patches@gnu.org` to get an ID, and then...
> >    23. Run `git send-email --to guix-patches <patches> <CC flags>`
> 
> Well, my grey hair are biasing my opinion. ;-)  From my point of view,
> the most annoying is #22.
> 
> Vagrant suggested [1] to send patches as attachment.  I am not convinced
> it will be better.  Well, it will for submitting but will not for
> following series.  For instance, let consider:
> 
>     [bug#65010] [PATCH 0/8] Misc Python build system improvements
>     Lars-Dominik Braun <lars@6xq.net>
>     Wed, 02 Aug 2023 12:37:57 +0200
>     id:cover.1690972374.git.lars@6xq.net
>     https://issues.guix.gnu.org//65010
>     https://issues.guix.gnu.org/msgid/cover.1690972374.git.lars@6xq.net
>     https://yhetil.org/guix/cover.1690972374.git.lars@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-contributions@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 <vagrant@debian.org>
> 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,
> 
> --8<---------------cut here---------------start------------->8---
> $ 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.
> --8<---------------cut here---------------end--------------->8---
> 
> And because there is some variation with the commit message format,
> these are not all the updates of VLC,
> 
> --8<---------------cut here---------------start------------->8---
> $ 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].
> --8<---------------cut here---------------end--------------->8---
> 
> 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.
> 
> 
> > 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
> 

-- 
There are only two hard things in Computer Science:
cache invalidation, naming things and off-by-one errors.

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

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

[Simon Tournier]

Hi,

On Tue, 05 Sep 2023 at 11:01, Katherine Cox-Buday <cox.katherine.e@gmail.com> 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 <zimon.toutoune@gmail.com>

gnu: ocaml-mdx: Fix tests.

* gnu/packages/ocaml.scm (ocaml-mdx)[arguments]: Substitue obsolete 'egrep' by
'grep -E'.

Signed-off-by: Julien Lepiller <julien@lepiller.eu>
--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 image that is already present in memory (#51121)

I've written this code probably three times at this point, but for some
reason it never made it into a PR. This allows loading a system image
that has already been loaded into memory. This happen when wanting to
distribute a static or mostly-static binary of julia code where the
system image (and optionally other libraries like libjulia, etc.) are
linked directly into the main executable. It is also useful for
deployment to environments that do not have (or have incomplete) support
--8<---------------cut here---------------end--------------->8---

where the diff looks like:

        6 files changed, 45 insertions(+), 10 deletions(-)
        src/Makefile         |  2 +-
        src/init.c           |  7 +++++--
        src/julia.h          |  2 +-
        src/julia_internal.h | 11 +++++++++++
        src/processor.cpp    | 10 +++++++++-
        src/staticdata.c     | 23 ++++++++++++++++++-----

<https://github.com/JuliaLang/julia/commit/70000ac7c3d5d5f21e42555cdf99e699a246f8ec>


Well, there is no comparison about the quality between the two commits,
IMHO.  On one hand, we have an clear idea about the change and what
exactly had been modified.  On the other hand, bah one needs to be
comfortable with the code and directly jumps to the diff hunks.  Which
commit message is helping irregular contributor or newcomer?  The one
which requires to internalize some rules?  Or the one easier to type?


Well, I share various points that had been raised in this thread about
smoothing the contribution requirements.  However, I am still puzzled by
the comments about the commit message format.  Again, my inability to
understand the issue does not mean I am not hearing.


All the rules are not explicitly written, IIRC, so the most reliable way
to adhere about the standard is probably to internalize these questions:

    What changes affected a particular source file?
    Was a particular source file renamed or moved, and if so, as part of what change?
    What changes affected a given function or macro or definition of a data structure?
    Was a function (or a macro or the definition of a data structure) renamed or moved from another file, and if so, as part of which change?
    What changes deleted a function (or macro or data structure)?
    What was the rationale for a given change, and what were its main ideas?
    Is there any additional information regarding the change, and if so, where can it be found? 

    https://www.gnu.org/prep/standards/html_node/Change-Logs.html#Change-Logs

All in all, my only proposal would to have a Git pre-commit hook or some
template pasting these questions and recalling the generic ChangeLog
format, when writing the commit message.  Maybe it would help…


Cheers,
simon

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

[Simon Tournier]

Hi,

On Wed, 06 Sep 2023 at 00:11, wolf <wolf@wolfsden.cz> 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?

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

"(" <paren@disroot.org> writes:

> Liliana Marie Prikler <liliana.prikler@gmail.com> 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 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 <cox.katherine.e@gmail.com> 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?

[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 <cox.katherine.e@gmail.com> 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 plain statements about them. So I'll try and do that again here:

For me at least, the overhead isn't remembering what the commit message 
should contain, it's remembering what the format should be. It's another 
step in a very long list of steps in which I need to open the GNU 
Changelog page side-by-side and try and meet its requirements.

A common argument I'm seeing is: "The committers will fix it for you." 
Well, at some point I want to be a committer, so what then? I'd be happy 
to get second reviews from other committers to make sure the commit 
messages are correct, but it seems like addressing the fact that capable 
people struggle to get this correct is more sensible.

> Yeah, commit messages are boring to write.

At no point have I made this argument. I will use whatever the standard 
is. I'm trying to frame the conversation around how to make it easier to 
follow the standard, not how to get out of following the standard.

> Well, I share various points that had been raised in this thread about
> smoothing the contribution requirements.  However, I am still puzzled by
> the comments about the commit message format.  Again, my inability to
> understand the issue does not mean I am not hearing.

Communication is so hard. My only advice is to remain aware that 
everyone in the world is different, and that even when we don't 
understand something, or don't experience it ourselves, that doesn't 
make it less real, especially if there's a plurality of people agreeing 
with one another. And to always choose kindness.

Here is a great talk by Rich Hickey called "Simple Made Easy". Although 
I recommend watching the entire thing, I'd like to draw your attention 
to a few points:

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

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

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?

> All the rules are not explicitly written, IIRC, so the most reliable way
> to adhere about the standard is probably to internalize these questions:
>
>      What changes affected a particular source file?
>      Was a particular source file renamed or moved, and if so, as part of what change?
>      What changes affected a given function or macro or definition of a data structure?
>      Was a function (or a macro or the definition of a data structure) renamed or moved from another file, and if so, as part of which change?
>      What changes deleted a function (or macro or data structure)?
>      What was the rationale for a given change, and what were its main ideas?
>      Is there any additional information regarding the change, and if so, where can it be found?
>
>      https://www.gnu.org/prep/standards/html_node/Change-Logs.html#Change-Logs
>
> All in all, my only proposal would to have a Git pre-commit hook or some
> template pasting these questions and recalling the generic ChangeLog
> format, when writing the commit message.  Maybe it would help…

A kind of wizard? I'm not sure if that addresses the overhead or not. 
Maybe that combined with a templating system that everyone can use? I 
don't have a lot of useful suggestions here other than to repeat 
something "(" said:

     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.

I think it's complex because it's trying to replicate the kinds of things a SCM tool can now track, but in free-form text blocks. I'm sorry I don't have suggestions for this specific thing, other than to drop it.

Above all, thanks for the dialogue.

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

[Maxim Cournoyer]

Hi Katherine,

Katherine Cox-Buday <cox.katherine.e@gmail.com> 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 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 <cox.katherine.e@gmail.com> 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?

[Simon Tournier]

Hi Katherine,

    ( I feel we are not able to communicate on commit message format and
it seems we are on a road that leads to unfruitful output.  Well, I
appreciate the discussion and I have carefully read the messages. )


On Tue, 05 Sep 2023 at 20:34, Katherine Cox-Buday <cox.katherine.e@gmail.com> wrote:

> 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?

I agree with this, even if maybe I am misread.

For me, the reduction of the friction for making contributions means the
identification of such friction.  Once the friction area are identified,
it leads to an estimation about the order of magnitude of such friction
compared to all the other frictions.

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?

Well, I am stretching a bit to make my point. :-)

I am trying to say that not all frictions are equal.  We collectively
must do our best to the reach equity, sure.  That’s said, we are hackers
and so we are improving what we are considering the most annoying.  You
find that running many commands for contributing is annoying so you are
trying to fix it.  I find some behaviour of “guix time-machine” annoying
so I am trying to fix it.  Etc.  The path for improving starts by making
apparent to all the annoyance, then optionally propose something – best
if one hopes the annoyance will be fixed :-) – and last the annoyance is
reduced for all when some proposal convinces folks.

My points are:

 1. thanks to all people for sharing their feedback
 2. the discussion is pointing many ideas that are actionable
 3. the discussion is also pointing friction that does not appear to me
    being actionable


> 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.


>> Well, I share various points that had been raised in this thread about
>> smoothing the contribution requirements.  However, I am still puzzled by
>> the comments about the commit message format.  Again, my inability to
>> understand the issue does not mean I am not hearing.
>
> Communication is so hard. My only advice is to remain aware that 
> everyone in the world is different, and that even when we don't 
> understand something, or don't experience it ourselves, that doesn't 
> make it less real, especially if there's a plurality of people agreeing 
> with one another. And to always choose kindness.

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. )


> Here is a great talk by Rich Hickey called "Simple Made Easy". Although 
> I recommend watching the entire thing, I'd like 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 <liliana.prikler@gmail.com>
Tue, 05 Sep 2023 22:43:04 +0200
id:3b274703acaf446ec678e96c9d875c5d6b1a3e17.camel@gmail.com
https://lists.gnu.org/archive/html/guix-devel/2023-09
https://yhetil.org/guix/3b274703acaf446ec678e96c9d875c5d6b1a3e17.camel@gmail.com

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

Next action, survey?

[Simon Tournier]

Hi Katherine,

On Tue, 05 Sep 2023 at 20:58, Katherine Cox-Buday <cox.katherine.e@gmail.com> wrote:

> OK, great! What are next steps, and how can I help?

Well, from my point of view, the next steps are:

 + Propose a survey (questions), open a new thread (or a bug report) for
   iterating.
 + Review how to distribute the survey.
 + Prepare the skeleton for generating a report about the stats from the
   survey.

Maybe the person or group of people in charge of this survey could be in
touch with Emacs folks.  They did a survey on 2022 [1].

1: https://lists.gnu.org/archive/html/emacs-devel/2022-10/msg01824.html


> 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?

Having a survey will not be wasted, IMHO.  As you said, although there
are bias – the first one is the way to distribute it ;-) – it will help
to inform about the status.  Having some stats about Guix users and
contributors will explicitly spot what we probably already know but
having that will help, for sure.

Well, something unrelated.  For instance, I spent some time to run an
experiment for checking a real-world worst-case scenario when
fallbacking to Software Heritage [2].  This lists all the frictions.
All these frictions were more or less already known but having
explicitly collected them makes easier the path for improving.  That’s
somehow the measure you were talking about.

A survey and the associated report will act similarly: list what we more
or less already know, and then make easier the path for improving.

2: https://simon.tournier.info/posts/2023-06-23-hackathon-repro.html


Cheers,
simon

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

[Josselin Poiret]

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

Hi Lily,

Liliana Marie Prikler <liliana.prikler@gmail.com> 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

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

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?

[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?

[Maxim Cournoyer]

Hi,

Attila Lendvai <attila@lendvai.name> 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?

[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]<even closer selector>{do you need 4 levels?}

HTH

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

[Vagrant Cascadian]

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

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]<even closer selector>{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

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

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

[Maxim Cournoyer]

Hi Vagrant,

Vagrant Cascadian <vagrant@debian.org> 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]<even closer selector>{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
<package> 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?

[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 <liliana.prikler@gmail.com> 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?

[Christopher Baines]

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


Maxim Cournoyer <maxim.cournoyer@gmail.com> writes:

> Hi Vagrant,
>
> Vagrant Cascadian <vagrant@debian.org> 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]<even closer selector>{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
> <package> 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.

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

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 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?

[Wojtek Kosior via Development of GNU Guix and the GNU System distribution.]

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

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 soooo 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 <liliana.prikler@gmail.com> wrote:

> Am Dienstag, dem 05.09.2023 um 19:40 +0100 schrieb (:
> > Liliana Marie Prikler <liliana.prikler@gmail.com> 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)?
> 

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

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 <cox.katherine.e@gmail.com> 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?

[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 <liliana.prikler@gmail.com> 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?

[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]. :-)
> 
>          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.

This is crucial, so please forgive me if I belabor this point.

You are correct that there are a range of ways to contribute, and some 
of them are intrinsically more difficult. But irrespective of that range 
of difficulty, *improving the accessibility and experience helps everyone*.

This is a well studied phenomenon, but to highlight some of the common 
reasons:

- Ability waxes and wanes throughout our lives. Most often it is a temporary
   state of affairs. Everyone's ability declines in the end, and the 
work you do
   today to mitigate this will help you tomorrow.

- Solutions designed to help in a specific way often surprise us by 
helping in
   other ways.

- There is a negative feedback loop of not designing for X, which keeps 
people
   affected by X away, which gives the illusion that there's no people 
affected
   by X who are interested, which means we don't design for X. 
Proactively addressing this breaks that cycle.

In my original message I stated:

     I've written a script for myself that tries to perform all the steps
     including running the git command to submit the patch, and this has 
helped
     me, but that this is necessary for me to do might be something that, if
     addressed, could help others.

Aside from the commit message, I've largely solved my problems. I'm 
trying to advocate for others, and not just pull the ladder up behind me.

If Guix is for everyone, then we should do our best to ensure everyone 
can contribute with the things they're skilled at.

> 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].

On the contrary, throughout this thread, I've thought that you 
understood the larger picture. I'm just responding to points where I 
thought I could contribute something, or where the points I've made have 
been challenged or questions have been asked.

Re: Next action, survey?

[Katherine Cox-Buday]

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

> Well, from my point of view, the next steps are:
> 
>   + Propose a survey (questions), open a new thread (or a bug report) for
>     iterating.

I'll open a bug report and start logging notes/suggestions against it. 
In it, I'll include your points:

>   + Review how to distribute the survey >   + Prepare the skeleton for generating a report about the stats from the
>     survey.
> 
> Maybe the person or group of people in charge of this survey could be in
> touch with Emacs folks.  They did a survey on 2022 [1].
> 
> 1: https://lists.gnu.org/archive/html/emacs-devel/2022-10/msg01824.html

I'll start reaching out to people, specifically people who have done 
surveys for projects similar to Guix.

I'm not an expert in how to design surveys, and I assume there are some 
out there who could help us design one to do things like avoid skewed 
data (e.g. your point about how the survey is distributed), and not 
frame questions in a way that elicits a certain response.

> A survey and the associated report will act similarly: list what we more
> or less already know, and then make easier the path for improving.

Agreed! I think the trend-analysis of survey responses over time will be 
most interesting.

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

[Felix Lechner via 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
<cox.katherine.e@gmail.com> 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?

[(]

Simon Tournier <zimon.toutoune@gmail.com> 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?

[Giovanni Biscuolo]

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

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".

<end of point 4.>

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

WDYT?

Maxim Cournoyer <maxim.cournoyer@gmail.com> writes:

[...]

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

[...]

>>> It's 
>>>
>>> * file (variable)[field]<even closer selector>{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] <selector>: 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

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

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

[Giovanni Biscuolo]

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

Hello Katherine,

Katherine Cox-Buday <cox.katherine.e@gmail.com> 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

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

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

[Giovanni Biscuolo]

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

Hi!

Simon Tournier <zimon.toutoune@gmail.com> 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

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

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?

[Efraim Flashner]

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

On Fri, Sep 08, 2023 at 11:53:43AM +0200, Giovanni Biscuolo wrote:
> Hello Katherine,
> 
> Katherine Cox-Buday <cox.katherine.e@gmail.com> 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   <efraim@flashner.co.il>   רנשלפ םירפא
GPG key = A28B F40C 3E55 1372 662D  14F7 41AA E7DC CA3D 8351
Confidentiality cannot be guaranteed on emails sent or received unencrypted

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

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

[Giovanni Biscuolo]

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

Ricardo,

Ricardo Wurmus <rekado@elephly.net> 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

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

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

[Ricardo Wurmus]

Josselin Poiret <dev@jpoiret.xyz> 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?

[Ricardo Wurmus]

Liliana Marie Prikler <liliana.prikler@gmail.com> 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]

Maxim Cournoyer <maxim.cournoyer@gmail.com> 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 <liliana.prikler@gmail.com> 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: Mumi CLI client (was: How can we decrease the cognitive overhead for contributors?)

[Ricardo Wurmus]

Giovanni Biscuolo <g@xelera.eu> writes:

> […] actually Debbugs or Mumi web
> interfaces are read-only: you cannot open a bug report or comment it,
> you have to send an email; this is a _feature_, not a bug since we don't
> need a _complex_ web based authentication+authorization system for bug
> reporters/commenters. […]

Mumi actually does support commenting on the web:

   https://git.savannah.gnu.org/cgit/guix/mumi.git/tree/mumi/web/controller.scm#n145

It’s just been disabled because messages ended up being stuck in the
queue and nobody could make enough time to debug this.

-- 
Ricardo

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

[Giovanni Biscuolo]

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

Hello Efraim,

Efraim Flashner <efraim@flashner.co.il> 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.fsf@xelera.eu today I tried to make some
actionable proposals considering the contant of this thread: WDYT?

Thanks, Gio'

[...]

-- 
Giovanni Biscuolo

Xelera IT Infrastructures

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

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]<even closer selector>{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] <selector>:
> 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?

[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 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?

[Ricardo Wurmus]

Liliana Marie Prikler <liliana.prikler@gmail.com> 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?

[Ricardo Wurmus]

Liliana Marie Prikler <liliana.prikler@gmail.com> 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?

[Liliana Marie Prikler]

Am Freitag, dem 08.09.2023 um 17:39 +0200 schrieb Ricardo Wurmus:
> 
> Liliana Marie Prikler <liliana.prikler@gmail.com> 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?

[Liliana Marie Prikler]

Am Freitag, dem 08.09.2023 um 22:24 +0200 schrieb Ricardo Wurmus:
> 
> Liliana Marie Prikler <liliana.prikler@gmail.com> 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?

[Simon Tournier]

Hi Ricardo, all,

On Fri, 08 Sep 2023 at 17:27, Ricardo Wurmus <rekado@elephly.net> 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 <vagrant@debian.org>
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/70000ac7c3d5d5f21e42555cdf99e699a246f8ec

3: Re: How can we decrease the cognitive overhead for contributors?
Maxim Cournoyer <maxim.cournoyer@gmail.com>
Mon, 28 Aug 2023 23:00:00 -0400
id:874jkift8v.fsf@gmail.com
https://lists.gnu.org/archive/html/guix-devel/2023-08
https://yhetil.org/guix/874jkift8v.fsf@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 <cox.katherine.e@gmail.com> 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
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.  Somehow, the new
web interface makes me “incompetent” for translating.  It is about
finding the right balance.  Hum, we are far from the initial
discussion. ;-)

Again, I think we are expressing the same thing and we are on the same
wavelength, I guess. :-)


> This is classic gatekeeping.

Sorry, I do not see any gatekeeping.  Because all seems open and many
people are doing their best for helping.  Maybe that does not work,
maybe that’s not enough, yeah maybe but 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. :-)


>>> - 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.
>
> This is crucial, so please forgive me if I belabor this point.
>
> You are correct that there are a range of ways to contribute, and some 
> of them are intrinsically more difficult. But irrespective of that range 
> of difficulty, *improving the accessibility and experience helps everyone*.

Are we on a wrong road?  Because we speak about the same thing, I guess:
a skilled programmer (you!) who wants to contribute to some packages and
does not find it “easy” by pointing several apparent frictions.  So it
means we have a problem!  Period. :-)

The question is how to improve?  Now, after discussing it – thank you
for opening this can of worms, it was necessary and this discussion is
very helpful!  – we have some items to act on, no?

Just to point, the root of the discussion about the commit message
format is about complexity, not about easiness.  Is the current format
too complex than no one finds it easy?

The various steps for checking and submitting patches are simple but
they are not easy.  Therefore, we must remove that because making hard
as not value.

About the commit message format, we could make it simpler, which would
lead to probably have something easier, but would we keep the value we
have with the current complexity?

> On the contrary, throughout this thread, I've thought that you 
> understood the larger picture. I'm just responding to points where I 
> thought I could contribute something, or where the points I've made have 
> been challenged or questions have been asked.

Thank you very much for all the efforts and time you are putting in this
topic.  They are worth and very fruitful.  I totally agree with your
words:

        If Guix is for everyone, then we should do our best to ensure
        everyone can contribute with the things they're skilled at.

And my point of view is that is a very big task so we need to start
somewhere and incrementally improve in order to reach this goal.

Cheers,
simon

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 that when you're
thinking about the tradeoffs you're making.

> 
> Aside from the commit message, I've largely solved my problems. I'm 
> trying to advocate for others, and not just pull the ladder up behind
> me.
In the context of free software, sharing your ladders is typically a
good idea.  When you have a tool that helps you automate some task, you
should at least put that tool somewhere.  Even if we find that we can't
automate the process in the general case (because there's a case your
script doesn't consider), it will at least help some to see that you've
already thought about X, Y and Z.

> If Guix is for everyone, then we should do our best to ensure
> everyone can contribute with the things they're skilled at.
Sure.

Now, about easy vs. simple

> 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.
In my eyes, you have fallen victim to the easy vs. simple trap
yourself, but again, it's easy to fall into and as Rich pointed out in
fact a common misconception.  So, rather than discussing these terms,
please tell us what about the contributor experience is more complex
than it needs to be and where applicable, how you would like to
simplify it.  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.

Cheers

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

[Ricardo Wurmus]

Liliana Marie Prikler <liliana.prikler@gmail.com> 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?

[Ricardo Wurmus]

Simon Tournier <zimon.toutoune@gmail.com> writes:

> On Fri, 08 Sep 2023 at 17:27, Ricardo Wurmus <rekado@elephly.net> 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?

[Liliana Marie Prikler]

Am Samstag, dem 09.09.2023 um 21:40 +0200 schrieb Ricardo Wurmus:
> 
> Liliana Marie Prikler <liliana.prikler@gmail.com> 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?

[Efraim Flashner]

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

On Fri, Sep 08, 2023 at 04:20:30PM +0200, Ricardo Wurmus wrote:
> 
> Josselin Poiret <dev@jpoiret.xyz> 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   <efraim@flashner.co.il>   רנשלפ םירפא
GPG key = A28B F40C 3E55 1372 662D  14F7 41AA E7DC CA3D 8351
Confidentiality cannot be guaranteed on emails sent or received unencrypted

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

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

[Giovanni Biscuolo]

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

Hi Efraim,

Efraim Flashner <efraim@flashner.co.il> 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.fsf@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

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

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 <liliana.prikler@gmail.com> 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]

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

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 <zimon.toutoune@gmail.com> 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

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

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

[Giovanni Biscuolo]

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

Hi Liliana,

Liliana Marie Prikler <liliana.prikler@gmail.com> 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

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

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?

[Simon Tournier]

Hi Liliana,

On Mon, 11 Sep 2023 at 19:53, Liliana Marie Prikler <liliana.prikler@gmail.com> 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.fsf@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 <rekado@elephly.net>
Fri, 08 Sep 2023 22:24:06 +0200
id:87tts44d2y.fsf@elephly.net
https://yhetil.org/guix/87tts44d2y.fsf@elephly.net
https://lists.gnu.org/archive/html/guix-devel/2023-09

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

[Csepp]

Giovanni Biscuolo <g@xelera.eu> writes:

> [[PGP Signed Part:Undecided]]
> Hi Liliana,
>
> Liliana Marie Prikler <liliana.prikler@gmail.com> 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?

[Giovanni Biscuolo]

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

Hello Csepp, 

Csepp <raingloom@riseup.net> 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

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

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

[Csepp]

Giovanni Biscuolo <g@xelera.eu> writes:

> [[PGP Signed Part:Undecided]]
> Hello Csepp, 
>
> Csepp <raingloom@riseup.net> 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?

[Maxim Cournoyer]

Hi Simon,

Simon Tournier <zimon.toutoune@gmail.com> writes:

> Hi Liliana,
>
> On Mon, 11 Sep 2023 at 19:53, Liliana Marie Prikler <liliana.prikler@gmail.com> 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.fsf@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
<https://notabug.org/apteryx/guix-api-examples/src/master/command-line-hacks.sh>
until this is automated in a 'guix review' command or similar.

-- 
Thanks,
Maxim

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

[Maxim Cournoyer]

Hi,

Csepp <raingloom@riseup.net> writes:

> Giovanni Biscuolo <g@xelera.eu> writes:
>
>> [[PGP Signed Part:Undecided]]
>> Hello Csepp, 
>>
>> Csepp <raingloom@riseup.net> 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: Mumi CLI client (was: How can we decrease the cognitive overhead for contributors?)

[Giovanni Biscuolo]

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

Hello Ricardo,

Ricardo Wurmus <rekado@elephly.net> writes:

> Giovanni Biscuolo <g@xelera.eu> writes:
>
>> […] actually Debbugs or Mumi web interfaces are read-only: you cannot
>> open a bug report or comment it, you have to send an email; this is a
>> _feature_, not a bug since we don't need a _complex_ web based
>> authentication+authorization system for bug reporters/commenters. […]
>
> Mumi actually does support commenting on the web:
>
>    https://git.savannah.gnu.org/cgit/guix/mumi.git/tree/mumi/web/controller.scm#n145
>
> It’s just been disabled because messages ended up being stuck in the
> queue and nobody could make enough time to debug this.

Uh, I didn't know mumi have that feature

AFAIU mumi does not (still?) have ad authentication/authorization,
right?

If so how do you plan to deal with users posting SPAM or similar
unappropriate content?

Thanks! Gio'

-- 
Giovanni Biscuolo

Xelera IT Infrastructures

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

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?

[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?

[Katherine Cox-Buday]

On 9/8/23 6:40 AM, Giovanni Biscuolo wrote:
> Ricardo,
> 
> Ricardo Wurmus <rekado@elephly.net> 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/8/23 6:40 AM, Giovanni Biscuolo wrote:
> Ricardo,
> 
> Ricardo Wurmus <rekado@elephly.net> 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/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 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 2:37 PM, Ricardo Wurmus wrote:
> 
> Liliana Marie Prikler <liliana.prikler@gmail.com> 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 2:37 PM, Ricardo Wurmus wrote:
> 
> Liliana Marie Prikler <liliana.prikler@gmail.com> 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?

[Simon Tournier]

Hi Maxim,

On Tue, 12 Sep 2023 at 10:42, Maxim Cournoyer <maxim.cournoyer@gmail.com> 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 <attila@lendvai.name>
        Fri, 25 Aug 2023 08:07:53 +0000
        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 <rekado@elephly.net>
        Fri, 08 Sep 2023 16:44:41 +0200
        id:87sf7o67ia.fsf@elephly.net
        https://yhetil.org/guix/87sf7o67ia.fsf@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 commits.

Ricardo used the term “superior” and Liliana asked a definition.  That’s
the origin of my email.  Instead of a definition, I was pointing (and
again here :-)) an example where “our” workflow just fails when the PR
model could not by design.

Last, do not take me wrong.

 1. I am happy with “our” workflow.
 2. I recognize that “our” workflow leads to frictions – and I consider
    that I know enough Emacs lisp or Bash for writing small helpers.
 3. The submission I am using as example is a gift, I am happy that the
    project receives such gift.  The failure is on my side or on “our”
    workflow.
 4. Things are improving, hopefully. :-)  However, it remains very
    annoying corner-cases in our workflow that will be very hard to
    tackle.  For sure, Mumi subcommand could help.
 5. I would be happy if someone could send some v2 version providing
    enough information to be able to just apply.

About #4, as I said elsewhere, I think the most promising is to wrap
something like:

    guix time-machine \
      --url=https://git.guix-patches.cbaines.net/git/guix-patches \
      --branch=issue-123456 --disable-authentication \
      -- build <foo>

and probably via Mumi.

My 2 cents on the reviewing process.

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 <cox.katherine.e@gmail.com> 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: Mumi CLI client (was: How can we decrease the cognitive overhead for contributors?)

[Ricardo Wurmus]

Giovanni Biscuolo <g@xelera.eu> writes:

> AFAIU mumi does not (still?) have ad authentication/authorization,
> right?
>
> If so how do you plan to deal with users posting SPAM or similar
> unappropriate content?

It only sends email on behalf of commenters, so we’re using the same
email mechanism to deal with spam.

-- 
Ricardo

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

[Simon Tournier]

Re,

On Wed, 13 Sep 2023 at 09:57, Simon Tournier <zimon.toutoune@gmail.com> 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

Commenting bug reports via mumi web interface (was: How can we decrease the cognitive overhead for contributors?)

[Giovanni Biscuolo]

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

Hi Ricardo,

Ricardo Wurmus <rekado@elephly.net> writes:

> Giovanni Biscuolo <g@xelera.eu> writes:
>
>> AFAIU mumi does not (still?) have ad authentication/authorization,
>> right?
>>
>> If so how do you plan to deal with users posting SPAM or similar
>> unappropriate content?
>
> It only sends email on behalf of commenters, so we’re using the same
> email mechanism to deal with spam.

Please forgive me if I'm not reading the source code for the relevant
mumi function, it would be easier for me to see it in action to
understand how the comment feature works.

I mean: I guess commenters are anonymous (?) and the mumi server will
send the email via authenticated SMTP (I hope) as user "mumi server" (or
something similar) on behalf of the commenter, right?

If so, the email is sent with the SPF and DKIM headers of the mumi
server configured mail server and that information is not useful to
eventually catch commenter email spoofing.

If I'm not missing something, then, anyone could send a comment as
"g@xelera.eu" containing unappropriate content, right?

I know that the GNU mailing lists mail server surely have an antispam
service, but it cannot use DMARC (SPF and/or DKIM) to filter email
spoofing attempts and all it can do is to assign a "spamminess" score to
messages, that seldom is able to effectively spot "unappropriate"
content, right?

Given all this, does this mean that anyone could send an offensive
comment as "g@xelera.eu" using the mumi commentig form?

...or are all the mailing lists moderated?

I feel I really miss something important in this picture, sorry for not
understanding what!

As an /antipattern/ example of a bug reporting system using a web
interface also for comments, I point out the one used by git-annex
(ikiwiki): https://git-annex.branchable.com/bugs/

When you try to "Add a comment", e.g. in:
https://git-annex.branchable.com/bugs/fsck_does_not_detect_corruption_on_yt_vids/

You are presented an authentication form supporting 3 auth methods:
registered user, email [1] and OpenID.

I still think that they sould just allow me to send an email to report
and comment bugs.


Thanks! Gio'


[1] The server sends you an unique URL you can use to log in and expires
in one day... why not just send me (forward) the complete message I want
to comment with the right Reply-to field pre-compiled, so I can edit my
comment with my lovely MUA instead of that /awful/ web interface?!?

-- 
Giovanni Biscuolo

Xelera IT Infrastructures

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

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

[Fannys]

Ekaitz Zarraga <ekaitz@elenq.tech> 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?

[MSavoritias]

Ekaitz Zarraga <ekaitz@elenq.tech> 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?

[MSavoritias]

Simon Tournier <zimon.toutoune@gmail.com> writes:

> Hi,
>
> On Tue, 29 Aug 2023 at 12:53, MSavoritias <email@msavoritias.me> 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]

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 <g@xelera.eu> 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 <cox.katherine.e@gmail.com> 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 not feasible due to asymmetric resources. But having the
>> option to let CI manage this process is very nice.
>
> AFAIU this is where https://qa.guix.gnu.org/ is intended to help, but
> now is not working as intended AFAIU
>
>> For me, steps 20-23 are bothersome. There's a lot of "if" statements 
>> that lead
>> to branching operations, and a lot of commands and flags to get
>> right.
>
> oh yes, CLI is a cognitive overhead sometimes, so we need better
> interfaces, some have found them
>
> actually, point 21 "Run `./pre-inst-env ./etc/teams.scm cc-members
> <patch>` to get the CC flags for Git" is bothersome and we should find a
> way to better integrate that in "git format-patch" (so that will be
> automatically used in all the git interfaces we use)
>
>> The extra step to get a debbugs ID is annoying.
>
> have you tried mumi CLI with the new feature?
>
>> 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.
>>    12. Run `git push` (subsequent changes are still just `git push`).
>>    13. Go to forge website, click button to open a pull-request.
>
> Forgive me if I insist: that forge site is _not_ SourceHut
>
> Second: each forge web site have a custom (not standard) way to manage
> pull-requests.
>
> Third: git have a pull-request mechanism [1] that could _easily_ be
> integrated in each and every forge, allowing projects to use
> /interoperable/ email based pull-request workflows if they want to.
>
> [...]
>
>> I don't find difficult, and reflected on the difference for awhile, I 
>> think, at
>> least for me, the highest friction comes from:
>>
>> - Steps 11-19, or (to assign it a name for easier reference) the "CI
>> steps".
>
> OK: AFAIU https://qa.guix.gnu.org/ is _the_ answer, so we need more
> contributors to that project
>
> ...and this means more cognitive overhead for Someone™ :-)
>
> [...]
>
>> If we wanted to encourage contributors to run "CI steps" 
>> locally before
>>    submitting, maybe this should be another `guix` sub-command? `guix 
>> pre-check`
>>    or something? I know there is a potential contributor who had this 
>> idea first
>>    who would want to hack on this.
>
> Having such a sub-command maybe could help, maybe not, because IMO the
> core and most cognitive challenging steps of all "CI steps" are not if
> builds are done locally or not but (in order of importance):
>
> 1. having patches reviewed by humans, the "not automatable" part because
> Someone™ have to understand the _meaning_ of the patch and verify it
> conforms to the coding standards of the project, including "changelog
> style" commit messages;
>
> 2. understanding why build derivation fail when it fails.
>
> This is real cognitive overhead and this cannot be automated.
>
>> - Steps 19-23, or the "manage patch" steps.
>>
>>    I think an insight here is that the big button on forges is actually 
>> a program
>>    removing the mental overhead for you.
>
> On the "web forges" vs "email based" patch workflow management I've said
> enough in other messages in this thread, here I just want to add
> (repeat) this: please do not only consider the mental overhead of
> potential contributors for "managing patches", also consider the mental
> overhead for patch reviewers; I've read many articles from professional
> patch reviewers that perfectly explains the great advanteges of using an
> email based workflow
>
> [...]
>
>>    I also don't usually have to worry nearly as much about crafting a commit
>>    message. So long as the title is under a character limit, and the body is
>>    helpful, it's OK. I think what bothers me most about the GNU changelog
>>    messages is that it's the worst of both spoken language and programming
>>    languages: there's an expectation of structure, but no grammar I can 
>> parse
>>    against, and it's free-form.
>
> I'm sorry that the GNU policy about commit messages bothers you (on the
> contrary it makes me happy); please consider that thai is /just/ one of
> the policies of the Guix project: code of conduct, coding standards,
> others?
>
> [...]
>
>> - Having multiple places to manage aspects of my patch
>>
>>    In a web-forge, I generally have a URL I can go to and see everything 
>> about my
>>    patch. I think we have that with https://issues.guix.gnu.org with two
>>    exceptions: (1) QA is a click away, or if you're using email, you're 
>> not even
>>    aware that there's a QA process failing (2) If you're not using email,
>>    context-switching between this page and email to respond.
>
> it's "just" an _interface_ issue
>
> [...]
>
> Happy hacking! Gio'
>
>
> [1] https://www.git-scm.com/docs/git-request-pull

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

[MSavoritias]

Simon Tournier <zimon.toutoune@gmail.com> writes:

> Hi Katherine,
>
> Thank you for your extensive analysis.  I concur.
>
> On Wed, 30 Aug 2023 at 10:11, Katherine Cox-Buday <cox.katherine.e@gmail.com> wrote:
>
>> 3. We should reify a way for Guix, the project, to measure, and track 
>> progress,
>>     against long-term goals. Particularly when they're social and not 
>> strictly
>>     technical.
>
> That is the most difficult part, IMHO.  Well, what are the long-term
> goals? :-)
>
> I am almost sure we will get various answers depending on people.  Let
> say the long-term goals of the Guix project are: Liberating, Dependable
> and Hackable.  Then how do you give concrete quantities that we can
> measure or track?
>
> And it is always difficult, if not impossible, to measure or track some
> goals that are not technical but social.  For example, how do you
> measure being welcoming or being a safe place for all?
>
> Do not take me wrong, I strongly think we must think again and again on
> that point for improving.  It’s just easier to tackle technical bug. :-)
>
>
>>    11. Try and get each commit message close to correct and commit.
>
>> I view steps 1-10 as pretty standard "development" steps common to most
>> projects, although 11 compounds the effort in 10.
>
> Maybe I am doing incorrectly but I have never thought much about that.
>
> For that point #11, from my point of view, it is as with any other
> project.  I start by running “git log --grep=” for getting inspiration.
>
> Well, as a rule of thumb, I am doing something like:
>
> top-module: submodule: one line summary.
>
> Fixes <https://issues.guix.gnu.org/12345>.
> Reported by Jane Doe <jane@doe.org>
>
> * path/to/file.scm (variable):[sub-part]: Description of the change.
> [otherpart]: Other description.
> * path/to/other/file.scm (other-variable): Description.
>
>
> In case of doubt, I am just running “git log --grep=” looking for
> similar thing, as said. :-)
>
>
>>    12. Run `guix lint`
>>    13. Run `guix style` (this is still in the manual although I have since
>>        learned this is not actually advisable).
>>    14. Review the changes these tools have made, and fix things.
>>    15. Run `guix build --rounds=2 <package>` to check for idempotency.
>>    16. Run `make` to ensure you didn't break anything elsewhere in Guix.
>>    17. Run `guix size` to ensure the closure isn't becoming bloated.
>>    18. Build all the packages that depend on this package.
>>    19. Run `guix pull --url=/path/to/your/checkout 
>> --profile=/tmp/guix.master` to
>>        ensure you didn't break Guix in a different way.
>
>> 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 not feasible due to asymmetric resources. But having the
>> option to let CI manage this process is very nice.
>
> For instance, I am not seeing “make check”. ;-)  And that omission makes
> very clear the cognitive overhead we are speaking about!
>
> Here I see two annoyances:
>
>  1. The number of subcommands and steps.
>  2. Each subcommand has a list of options to digest.
>
> Well, CI is helpful here, for sure.  However, it would be helpful to
> have a script similar as etc/teams.scm or etc/committer.scm that would
> help to run all these steps.
>
> It does not mean that all these steps need to be run before each
> submission.  However having a tool would help irregular contributors or
> newcomers; it would decrease the cognitive overhead i.e., that overhead
> would be pushed to some script and it would reinforce confidence.
>
> Now someone™ needs to implement this script. ;-)
>
>
>>    20. Run `git format-patch -1 --cover-letter [--reroll-count]`
>>    21. Run `./pre-inst-env ./etc/teams.scm cc-members <patch>` to get 
>> the CC flags for Git
>>    22. Remember that if you're sending multiple patches, an email first 
>> has to be
>>        sent to `guix-patches@gnu.org` to get an ID, and then...
>>    23. Run `git send-email --to guix-patches <patches> <CC flags>`
>
> Well, my grey hair are biasing my opinion. ;-)  From my point of view,
> the most annoying is #22.
>
> Vagrant suggested [1] to send patches as attachment.  I am not convinced
> it will be better.  Well, it will for submitting but will not for
> following series.  For instance, let consider:
>
>     [bug#65010] [PATCH 0/8] Misc Python build system improvements
>     Lars-Dominik Braun <lars@6xq.net>
>     Wed, 02 Aug 2023 12:37:57 +0200
>     id:cover.1690972374.git.lars@6xq.net
>     https://issues.guix.gnu.org//65010
>     https://issues.guix.gnu.org/msgid/cover.1690972374.git.lars@6xq.net
>     https://yhetil.org/guix/cover.1690972374.git.lars@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-contributions@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 <vagrant@debian.org>
> 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

to PR or not to PR, is /that/ the question?

[Giovanni Biscuolo]

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

Hi Simon,

please forgive me if I continue drifting in this beautiful sea...

This message is /very/ long but it's just because I'm trying to do my
best to provide a deep analisys of the **big** problems with eventually
adopting a «web based PR model» (please see below for a definition) for
contributions to Guix.

Please skip this if you don't have enough time to drift like I'm doing!

Also, please consider I don't have much experience on how a «web based
PR model» works and /doesn't work/ in practice... but I'm studying :-)

Simon Tournier <zimon.toutoune@gmail.com> writes:

[...]

> This branch of the looooong thread starts with:
>
>         Re: How can we decrease the cognitive overhead for contributors?
>         Attila Lendvai <attila@lendvai.name>
>         Fri, 25 Aug 2023 08:07:53 +0000
>         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.

Actually he is speaking about «the web based PR model».

I don't want to sound pedantic, but [1]:

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

It's worth noting that the term pull request is not universally used:
GitLab calls them merge requests for example. Furthermore I regard the
terms pull request and merge request to be poorly named, as the terms
can be conflated with terminology used by your version control tool
(e.g. git pull or git merge).  And the implementations of a pull or
merge request may not even perform a pull or a merge (you can also
rebase a pull/merge request, but nobody is calling them rebase
requests). A modern day pull request is so much more than a version
control tool operation or even a simple request to pull or merge a
branch: it is a nexus to track the integration of a proposed change
before during and after that change is integrated.

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

Please let me underline: PR it's *a* nexus, one of the different one
available with a DVCS.  With git, for example, we also have "git
request-pull", with it's email based workflow.

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

But alas. Because GitHub coined the term and is the most popular
collaboration platform implementing this functionality, I'll refer to
this general workflow as implemented on GitHub, GitLab, Bitbucket, and
others as pull requests for the remainder of this post.

[...] At its core, the pull request is fundamentally a nice UI and
feature layer built around the common Git feature branch workflow.

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

As I tried to tell elsewhere, all so called "pull request" features
incorporated in various "web based forges" are just /user interfaces/
built around the Git feature branch workflow.

...and guess what: Guix _is_ implementing a Git feature branch workflow
[2]!  Guix is also starting to use a clever "request merging" workflow,
integrated with qa.guix.gnu.org [3], see
https://issues.guix.gnu.org/65846 as an example.

Guix is just not implementing a feature branch workflow to incorporate
_commits_ coming from the contributors, and I still think this is wise.

Furthermore:

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

[...] I think it is time for industry to scrutinize the pull request
model and to evolve it into something better.

I know what you are thinking: you are thinking that pull requests work
great and that they are popular because they are a superior model
compared to what came before. These statements - aside from some nuance
- are true. But if you live in the version control space (like I do) or
are paid to deliver tools and workflows to developers to improve
productivity and code/product quality (which I am), the deficiencies in
the pull request workflow and implementation of that workflow among
vendors like GitHub, GitLab, Bitbucket, etc are obvious and begging to
be overhauled if not replaced wholesale.

[...] In other words, the way I see the world is that a specific
vendor's pull request implementation is just that: an implementation
detail. And like all implementation details, they should be frequently
scrutinized and changed, if necessary.

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

The rest of the article is worth reading since it is a professional
analisys of the problems with "Pull Requests" /implementations/ and
workflow, backed by some (sort of?) research:

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

[...] the current implementation of pull requests actively discourages
the many smaller changes workflow. And since smaller changes result in
higher quality and faster reviews, today's implementations of pull
requests are undermining quality and velocity.

[...] I posit that in order for us to author more, smaller changes, we
must either a) create more, smaller pull requests or b) have pull
request reviews put emphasis on the individual commits (as opposed to
the overall merge diff).

If we were to author more, smaller pull requests, this would seemingly
necessitate the need for dependencies between pull requests in order to
maintain velocity. And dependencies between pull requests adds a
potentially prohibitive amount of overhead.

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

Ouch! :-D

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

In other words, I don't think you can implement the multiple pull
request model reliably and without causing excessive burden on people
without fundamentally changing the requirement that a pull request be a
Git branch. (I'd love to be proven wrong.)

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

Can we consider this a thoughtful argument _not_ to use "GitHub-like
pull requests" when contributing to Guix?

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

Therefore, I don't think the more, smaller changes workflow can be
easily practiced with multiple pull requests using the common GitHub
model without effectively moving the definition of a pull request away
from equivalence with a Git branch

[...] Unfortunately, a trivial change of the default to show individual
commits instead of the merge diff is not so simple, as many authors and
projects don't practice clean commit authorship practices, where
individual commits are authored such that they can be reviewed in
isolation.

[...] A handful of mature projects - like the Linux kernel, Firefox,
Chrome, Git, and Mercurial - practice the series of individually-good
commits model, which I'll call a commit-centric workflow.

[...] I'm a strong proponent of a clean commit history where each commit
in the final repository history stands as good in isolation. But I tend
to favor more grown-up software development practices and am a version
control guru. That being said, the subject/debate is fodder for another
post.

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

Guix is also practicing a "individually-good commits model", right?

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

If GitHub (or someone else) switched the pull request default to a
per-commit review without otherwise changing the relationship between a
pull request and a Git branch, that would force a lot of less
experienced users to familiarize themselves with history rewriting in
Git. This would impose considerable pain and suffering on pull request
authors, which would in turn upset users, hurt engagement, etc.

[...] But even if these services did emphasize individual commits by
default in pull request reviews, there's still a handful of significant
deficiencies that would undermine the more, smaller changes workflow
that we desire.

While it is possible to review individual commits, all the review
comments are still funneled into a single per pull request timeline view
of activity. If submitter and reviewer make the effort to craft and
subsequently review individual commits, your reward is that all the
feedback for the discrete units of change gets lumped together into one
massive pile of feedback for the pull request as a whole.

[...] Even if GitHub (or someone else) implements robust per-commit
review for pull requests, there's still a problem with velocity. And
that problem is that if the pull request is your unit of integration
(read: merging), then you have to wait until every commit is reviewed
before integration can occur. [...] I argue this is less optimal than a
world where a change integrates as soon as it is ready to, without
having to wait for the changes after it. As an author and maintainer, if
I see a change that is ready to integrate, I prefer to integrate it as
soon as possible, without delay.

The longer a ready-to-integrate change lingers, the longer it is
susceptible to bit rot (when the change is no longer valid/good due to
other changes in the system).

[...] What happens when some commits in a pull request are integrated
and the author rebases or merges their local branch against their new
changes? This may or may not just work. And when it doesn't just work,
the author can easily find themselves in merge conflict hell, where one
commit after the other fails to apply cleanly and their carefully
curated stack of commits quickly becomes a liability and impediment to
forward progress.

[...] While it is certainly possible to integrate changes as soon as
they are ready with a pull request workflow, I think that it is awkward
and that by the time you've made enough changes to accommodate the
workflow, very little is left of the pull request workflow as we know it
and it is effectively a different workflow altogether.

[...] But even if you don't buy into the change size arguments, there's
still a very valid reason why we should think beyond pull requests as
they are implemented today: tool scalability.

[...] Unfortunately, the tight coupling of pull requests to Git
branches/refs introduces unbound growth and a myriad of problems
associated with it. Most projects may not grow to a size that
experiences these problems. But as someone who has experience with this
problem space at multiple companies, I can tell you the problem is very
real and the performance and scalability issues it creates undermines
the viability of using today's implementation of pull requests once
you've reached a certain scale. Since we can likely fix the underlying
scaling issues with Git, I don't think the explosion of Git refs is a
long-term deal breaker for scaling pull requests. But it is today and
will remain so until Git and the tools built on top of it improve.

* Exploring Alternative Models

A pull request is merely an implementation pattern for the general
problem space of integrating a proposed change. There are other patterns
used by other tools. Before I describe them, I want to coin the term
integration request to refer to the generic concept of requesting some
change being integrated elsewhere.  GitHub pull requests and GitLab
merge requests are implementations of integration requests, for example.

[...] Before Git and GitHub came along, you were probably running a
centralized version control tool which didn't support offline commits or
feature branches (e.g. CVS or Subversion). In this world, the common
mechanism for integration requests was exchanging diffs or patches
through various media - email, post to a web service of a code review
tool, etc. Your version control tool didn't speak directly to a VCS
server to initiate an integration request. Instead, you would run a
command which would export a text-based representation of the change and
then send it somewhere.

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

Please let me say this in other words: email exchange of integration
requests is VCS agnostic: right?

I'm not proposing to replace git with another VCS :-D... but who knows
in 5 years what tool will fit better? :-O

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

Today, we can classify integration requests by whether or not they speak
the version control tool's native protocol for exchanging data or
whether they exchange patches through some other mechanism. Pull
requests speak the VCS native protocol. Tools like Review Board and
Phabricator exchange patches via custom HTTP web services. Typically,
tools using non-native exchange will require additional client-side
configuration, including potentially the installation of a custom tool
(e.g. RBTools for Review Board or Arcanist for Phabricator). Although
modern version control tools sometimes have this functionality built-in.

[...] An interesting outlier is Gerrit, which ingests its integration
requests via git push. [...] The wizard behind the curtain here is that
Gerrit runs a special Git server that implements non-standard behavior
[...]. When you push to refs/for/master, Gerrit receives your Git push
like a normal Git server would. But instead of writing a ref named
refs/for/master, it takes the incoming commits and ingests them into a
code review request!

[...] On the surface, it may seem like using the version control tool's
native data exchange is a superior workflow because it is more native
and more modern. (Emailing patches is so old school.) [...] Instead, you
run git push and your changes can be turned into an integration request
automatically or with a few mouse clicks. And from a technical level,
this exchange methodology is likely safer, as round-tripping a
text-based representation of a change without data loss is surprisingly
finicky.

[...] But despite being more native, modern, and arguably robust,
exchange via the version control tool may not be better.

[...] When your integration request requires the use of a version
control tool's wire protocol, the client likely needs to be running that
version control tool. With other approaches like exchange of text based
patches, the client could be running any software it wanted: as long as
it could spit out a patch or API request in the format the server
needed, an integration request could be created! This meant there was
less potential for lock-in, as people could use their own tools on their
machines if they wanted and they (hopefully) wouldn't be inflicting
their choice on others.

[...] Because Firefox is using Phabricator (Review Board and Bugzilla
before that) for code review and because Phabricator ingests text-based
patches, the choice of the VCS on the client doesn't matter that much
and the choice of the server VCS can be made without inciting a holy war
among developers who would be forced to use a tool they don't
prefer. Yes, there are good reasons for using a consistent tool
(including organizational overhead) and sometimes mandates for tool use
are justified. But in many cases (such as random open source
contributions), it probably doesn't or shouldn't matter. And in cases
like Git and Mercurial, where tools like the fantastic git-cinnabar make
it possible to easily convert between the repositories without data loss
and acceptable overhead, adoption of the version control tool's native
wire protocol can exclude or inhibit the productivity of contributors
since it can mandate use of specific, undesired tooling.

[...] With Gerrit, I don't have to create a local Git branch to initiate
an integration request. With pull requests, I'm compelled to. And this
can undermine my productivity by compelling me to practice
less-efficient workflows!

[...] Our final point of comparison involves scalability. When you use
the version control tool wire protocol as part of integration requests,
you have introduced the problem of scaling your version control
server. Take it from someone who has had multiple jobs involving scaling
version control servers and who is intimately aware of the low-level
details of both the Git and Mercurial wire protocols: you don't want to
be in the business of scaling a version control server.

[...] Can your version control server handle ingesting a push every
second or two with reasonable performance?  Unless you are Google,
Facebook, or a handful of other companies I'm aware of, it can't. And
before you cry that I'm talking about problems that only plague the
0.01% of companies out there, I can name a handful of companies under
10% the size of these behemoths where this is a problem for them. And I
also guarantee that many people don't have client-side metrics for their
git push P99 times or reliability and don't even realize there is a
problem! Scaling version control is probably not a core part of your
company's business. Unfortunately, it all too often becomes something
companies have to allocate resources for because of poorly designed or
utilized tools.

Contrast the challenges of scaling integration requests with a native
version control server versus just exchanging patches. With the more
primitive approach, [...]

[...] Unfortunately, solutions like GitHub pull requests and Gerrit's
use of Git refs for storing everything exert a lot of pressure on
scaling the version control server and make this a very real problem
once you reach a certain scale. [...]

* Commit Tracking

[...] For example, if you submit a commit then amend it, how does the
system know that the commit evolved from commit X to X'.

Pull requests don't track commits directly. Instead, a commit is part of
a Git branch and that branch is tracked as the entity the pull request
is built around. The review interface presents the merge diff front and
center. It is possible to view individual commits. But as far as I know,
none of these tools have smarts to explicitly track or map commits
across new submissions.

[...] If all you are familiar with is pull requests, you may not realize
there are alternatives to commit tracking! In fact, the most common
alternative (which isn't do nothing) predates pull requests entirely and
is still practiced by various tools today.

The way that Gerrit, Phabricator, and Review Board work is the commit
message contains a unique token identifying the integration request for
that commit. e.g. a commit message for a Phabricator review will contain
the line Differential Revision:
https://phab.mercurial-scm.org/D7543. Gerrit will have something like
Change-Id: Id9bfca21f7697ebf85d6a6fa7bac7de4358d7a43.

[...] This Git hook will ensure that any newly-created commit has a
Change-ID: XXX line containing a randomly generated, hopefully unique
identifier.

[...] This approach of inserting a tracking identifier into commit
messages works surprisingly well for tracking the evolution of commits!
Even if you amend, reorder, insert, or remove commits, the tool can
often figure out what matches up to previous submissions and reconcile
state accordingly. Although support for this varies by tool.

[...] The tracking of commits is another one of those areas where the
simpler and more modern features of pull requests often don't work as
well as the solutions that came before. Yes, inserting an identifier
into commit messages feels hacky and can be brittle at times (some tools
don't implement commit rewriting very well and this can lead to a poor
user experience). But you can't argue with the results: using explicit,
stable identifiers to track commits is far more robust than the
heuristics that pull requests rely on.  The false negative/positive rate
is so much lower.

[...] The use of explicit commit tracking identifiers may not seem like
it makes a meaningful difference. But it's impact is profound.

The obvious benefit of tracking identifiers is that they allow rewriting
commits without confusing the integration request tool. This means that
people can perform advanced history rewriting with near impunity as to
how it would affect the integration request.

[...] I am a heavy history rewriter. I like curating a series of
individually high-quality commits that can each stand in isolation. When
I submit a series like this to a GitHub pull request and receive
feedback on something I need to change, when I enact those changes I
have to think will my rewriting history here make re-review harder? (I
try to be empathetic with the reviewer and make their life easier
whenever possible. I ask what I would appreciate someone doing if I were
reviewing their change and tend to do that.) With GitHub pull requests,
if I reorder commits or add or remove a commit in the middle of a
series, I realize that this may make review comments left on those
commits hard to find since GitHub won't be able to sort out the history
rewriting. And this may mean those review comments get lost and are
ultimately not acted upon, leading to bugs or otherwise deficient
changes. This is a textbook example of tooling deficiencies dictating a
sub-optimal workflow and outcome: because pull requests don't track
commits explicitly, I'm forced to adopt a non-ideal workflow or
sacrifice something like commit quality in order to minimize risks that
the review tool won't get confused. In general, tools should not
externalize these kinds of costs or trade-offs onto users: they should
just work and optimize for generally agreed-upon ideal outcomes.

[...] Another benefit to tracking identifiers is that they enable
per-commit review to be viable. Once you can track the logical evolution
of a single commit, you can start to associate things like review
comments with individual commits with a high degree of confidence.

[...] A secondary benefit of per-commit review is that this model
enables incremental integration workflows, where some commits in a
series or set can integrate before others, without having to wait for
the entire batch.

[...] But actually deploying this workflow can be tricky. One problem is
that your version control tool may get confused when you rebase or merge
partially landed state. Another problem is it can increase the overall
change rate of the repository, which may strain systems from version
control to CI to deployment mechanisms. Another potential problem
involves communicating review sign-off from integration sign-off. Many
tools/workflows conflate I sign off on this change and I sign off on
landing this change. While they are effectively identical in many cases,
there are some valid cases where you want to track these distinctly. And
adopting a workflow where commits can integrate incrementally will
expose these corner cases. So before you go down this path, you want to
be thinking about who integrates commits and when they are
integrated. (You should probably be thinking about this anyway because
it is important.)

[...] [Forks] existence forces the user to manage an additional Git
remote and branches. It forces people to remember to keep their branches
in sync on their fork. As if remembering to keep your local repository
in sync wasn't hard enough!

[...] Forks are essentially a veneer on top of a server-side git
clone. And the reason why a separate Git repository is used at all is
probably because the earliest versions of GitHub were just a pile of
abstractions over git commands. The service took off in popularity,
people copied its features almost verbatim, and nobody ever looked back
and thought why are we doing things like this in the first place.

[...] Could Git grow features to make the user experience much better so
users don't need to be burdened with complexity or magic and could
simply run commands like git submit --for review?  Definitely!

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

...meanwhile, I don't think thay adopting a «web based PR model» for
the Guix project is a good idea.


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

My ideal integration request revolves around individual commits, not
branches.

[...] In this world, the branch would not matter. Instead, commits are
king. Because we would be abandoning the branch name as a tracker for
the integration request, we would need something to replace it,
otherwise we have no way of knowing how to update an existing
integration request!

[...] commit-centric integration requests aren't forcing you to change
your local workflow! If you are the type of person who doesn't want to
curate a ton of small, good-in-isolation commits (it does take a bit
more work after all), nobody would be forcing you to do so. Instead, if
this is your commit authorship pattern, the submission of the proposed
change could squash these commits together as part of the submission,
optionally rewriting your local history in the process. If you want to
keep dozens of fixup commits around in your local history, that's fine:
just have the tooling collapse them all together on submission.

[...] Making integration requests commit-centric doesn't force people to
adopt a different commit authorship workflow. But it does enable
projects that wish to adopt more mature commit hygiene to do so. That
being said, hows tools are implemented can impose restrictions. But
that's nothing about commit-centric review that fundamentally prohibits
the use of fixup commits in local workflows.

[...] I also largely ignored some general topics like the value that an
integration request can serve on the overall development lifecycle:
integration requests are more than just code review - they serve as a
nexus to track the evolution of a change throughout time.

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

In the Guix project (and many other) the evolution of changes throughout
time - made possible by the use of the "integration request" model
instead of the "pull request" model - is tracked by the guix-commit
mailing list, that is auto populated by a server side git hook:
https://lists.gnu.org/archive/html/guix-commits/

> 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 <rekado@elephly.net>
>         Fri, 08 Sep 2023 16:44:41 +0200
>         id:87sf7o67ia.fsf@elephly.net
>         https://yhetil.org/guix/87sf7o67ia.fsf@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 don't know if really "reviewer apply the first patch" friction does
not exist by design in a PR model (especially a web based one), but
AFAIU many other frictions /do/ exist... by design!

[...]

(I'm studying for a reply to the rest of the message, stay tuned! :-D )

Happy hacking! Gio'



[1]
https://gregoryszorc.com/blog/2020/01/07/problems-with-pull-requests-and-how-to-fix-them/ (2020-01-07)

[2] look at the Branches listed here: https://qa.guix.gnu.org/

[3] https://guix.gnu.org/en/manual/devel/en/html_node/Managing-Patches-and-Branches.html

-- 
Giovanni Biscuolo

Xelera IT Infrastructures

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

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

[Maxim Cournoyer]

Hi Fannys,

Fannys <email@fannys.me> writes:

> Ekaitz Zarraga <ekaitz@elenq.tech> 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: to PR or not to PR, is /that/ the question?

[Simon Tournier]

Hi Giovanni,

Thank you for your detailed message.  Sorry, I have not read all the
details because I have been lost.  What do you want to explain?

Well, let me explain my understanding using my own words. :-)

When one reduces to the core of the workflows, the main difference
between “email workflow” and “PR workflow” is the way the submitter
sends the code to the reviewer.

 1. email workflow: the diff are sent by email.
 2. PR workflow: the diff are sent by the VCS itself.

Then, we can put a lot of glue around these workflows.  It is possible
to work in a centralized fashion or in a distributed fashion.  It is
possible to use a proprietary service for delegating some parts using a
button via a web-interface.  It is possible to have a service based on
free software that automatize some parts of the workflow.  Etc

By glue, it reads a range from mailing list to Github, or from Gitlab to
Sourcehut, or from personal custom scripts to tools as B4, public-inbox,
Gerrit, patchwork, etc.

Obviously, the PR workflow also depends on the features of the
underlining VCS when the email workflow not.  Bitbucket provided a PR
workflow for Mercurial.  And a PR workflow would be hard to implement
using Subversion or worse using CVS.

Note that the email workflow #1 might be centralized.  That’s what we
are doing when using one mailing list; there is only one unique location
for exchanging all pieces of code.  Or it might be decentralized, that’s
how the contributors send their contribution to some linux kernel
maintainers.

Note that the PR workflow #2 might be decentralized.  That’s more or
less how Linus Torvald’s “lieutenants” are doing for asking a merge in
the Linus’s mainline linux kernel.  Or it might centralized and
web-forges provide many examples. :-)

The requirement for #1 is just being able to send emails.  The
requirement for #2 is to have a public Git repository.

Both workflows have pros and cons.  And then these pros and cons also
depend on how the workflow is implemented.  And none is not much better
than the other.

The slight difference between the two is the state of the contribution
from the reviewer perspective:

    . About the email workflow #1, the patches might not apply for many
reasons but because they are sent by email, the notification “hey give a
look to thing” and the “diff for thing“ are synchronized.

    . About the PR workflow #2, the patches belong to a Git repository
so they are already applied.  However, between the notification “hey
give a look to thing” and the moment when the reviewer pulls the thing,
the Git repository might disappear, be replaced, history rewritten, etc.

Well, that’s my understanding of the difference between #1 and #2.  A
bit simplified but it captures my understanding of the main, I
guess. :-)

Cheers,
simon

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

[Ekaitz Zarraga]

Hi,

On Wednesday, September 13th, 2023 at 3:42 PM, Maxim Cournoyer <maxim.cournoyer@gmail.com> 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 issues that
are ages old, and new issues are opened every single day... This *must* be
superfrustrating for maintainers. Currently I use https://issues.guix.gnu.org/
to track some of them, but it's not easy to follow at all.

You have been talking about mumi a lot in this thread. To be honest with you, I
had a hard time trying to learn what it actually is and how to start using it
and I even gave up with it. That's not a good contribution experience. I just
felt like just sending a couple of patches from time to time is enough for me
and I can manually use email for that.

Also as I already said, there are many patches that are forgotten forever, I
contributed with a build-system more than half a year ago and I got no answer
from anyone. It's a change that doesn't affect the core of guix at all, and
it's better merged than not. It could just be merged and keep an eye on how
does it work in the wild and wait for other contributions. It's a little bit
frustrating, and as I already mentioned it also has to be frustrating for that
maintainer that would love to review what I sent and has no time for it because
of all the patches that should be corrected because stupid problems people
commited because the process is not really clear.

I don't know.

I'd also love to be a commiter, help a little bit more, but I think there's a
knowledge barrier I feel I will never cross. I'm quite comfortable doing many
things, but I think I can't learn anything else. The only ray of hope I have is
the article series Unmatched Paren is sharing in the Guix blog (thanks).

It's also discouraging to have questions and never get answers for them. For
things that should work and are broken. It gives you the feeling that
everything is fragile, and there's no way to fix. The only computer I work on
is Guix, I am invested on this, but sometimes for work reasons I feel I would
need to abandon it, as many things that should just work are basically useless
and I can't fix, even if I'd love to. Example:

> I just want to build a program for arm-none-eabi, for gods sake! Every
> variable is set up properly... What am I missing? What could I possibly be
> missing???

Probably, if we had an easier contribution process, these secondary problems
would just become slight inconveniences, which is what they often are, but some
days they hit really hard.

This is what it feels like. Sometimes.

Most of the times, though, it feels Guix is really awesome, that you people are
amazing and I'm really happy to be part of this.

I can only be thankful of being a tiny part of this amazing piece of software
and all I've learned in the process.

We can do better, but that's no reason to forget all the good things we have.

Cheers,
Ekaitz

Re: to PR or not to PR, is /that/ the question?

[Giovanni Biscuolo]

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

Hi Simon

Simon Tournier <zimon.toutoune@gmail.com> writes:

> Thank you for your detailed message.  Sorry, I have not read all the
> details because I have been lost.

Sorry!  Forgive me since I am not able to summarize the details without
losing content.

> What do you want to explain?

In the context of this increasing cognitive overheading thread...

As I wrote: «I don't think thay adopting a «web based PR model»
(whatever the term "pull request" means, editor note) for the Guix
project is a good idea.»

To remain /in topic/: I think that adopting a «web based PR model» will
definitely _not_ decrease the cognitive overhead for contributors.

Also, replacing (or adding to) the current "integration request" email
based workflow with a "web based PR model" (that _imply_ a web based
patch review strictly connected with the choosen "forge"?) would be an
/overwelming/ cognitive overhead for all.

Last but not least, I also think that adding a patch review system like
Gerrit or Gerrit, Phabricator, and Review Board would not only
_increase_ the overall cognitive overhead but is also /technically/
_broken_.

Why I think all this things?  Well, I'm sorry but it's a _very_ long
story and is all written down in the /details/.
(id:87y1ha9jj6.fsf@xelera.eu aka https://yhetil.org/guix/87y1ha9jj6.fsf@xelera.eu/)

[...]

I'm done with this thread, sorry; I'll drift alone :-) 

Happy hacking, Gio'

-- 
Giovanni Biscuolo

Xelera IT Infrastructures

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

Re: to PR or not to PR, is /that/ the question?

[Simon Tournier]

Hi,

On Thu, 14 Sept 2023 at 08:53, Giovanni Biscuolo <g@xelera.eu> wrote:

> To remain /in topic/: I think that adopting a «web based PR model» will
> definitely _not_ decrease the cognitive overhead for contributors.

What could potentially decrease the cognitive overhead for
contributors when using a "web based PR model" is all the usual glue
(services) around this very same "web based PR model".  Somehow, the
discussion is about these services behind the web-button.  I agree
with Katherine, quoting [1]:

        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.

IMHO, I think we have identified some of these causes of complexity.

Last, let me say it again: I am perfectly happy with the email workflow. :-)

Cheers,
simon


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

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

[Ricardo Wurmus]

MSavoritias <email@msavoritias.me> writes:

> Simon Tournier <zimon.toutoune@gmail.com> writes:
>
>> Hi,
>>
>> On Tue, 29 Aug 2023 at 12:53, MSavoritias <email@msavoritias.me> 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?

[Ricardo Wurmus]

Fannys <email@fannys.me> 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?

[Sarthak Shah]

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

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, <email@fannys.me> wrote:

>
> Ekaitz Zarraga <ekaitz@elenq.tech> 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.
>
>

[-- Attachment #2: Type: text/html, Size: 2958 bytes --]

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

[Simon Tournier]

Hi,

On Thu, 14 Sep 2023 at 23:19, Sarthak Shah <shahsarthakw@gmail.com> 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?

[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 soooo 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 <liliana.prikler@gmail.com> wrote:
>
>> Am Dienstag, dem 05.09.2023 um 19:40 +0100 schrieb (:
>>> Liliana Marie Prikler <liliana.prikler@gmail.com> 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)?
>>

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 <liliana.prikler@gmail.com> 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/13/23 18:42, Maxim Cournoyer wrote:
> Hi Fannys,
>
> Fannys <email@fannys.me> writes:
>
>> Ekaitz Zarraga <ekaitz@elenq.tech> 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 contributors. 
Same with email, debbugs. What can solve this is effort to actually 
include people.

Visual Code as you mentioned or any other editor, or mumi, these are all 
efforts to get contributors in the first place. The contributors will 
never come and create the infra and tooling they want by themselves. It 
takes some initial effort on our part to lower the barrier and 
"cognitive overhead" as in the title to actually encourage people to 
contribute. Same way that women or other minorities dont just "show up" 
to change the culture to make the welcome. they would rather go where 
they are already welcome.


Not to make this too long i strongly disagree that "Create your own 
toolbox" is a barrier we should have for new users. And recommendations 
carry weight because its what people see the community putting effort 
into and using.


Some proposals/good directions that we already have not to leave this 
with just complaining is:

- Improve guile studio and add it as a recommendation. With an improve 
UI and keybindings for it.

- Improve the docs of course.

- add more editors maybe(?) by ourselves.

This is for the starting to change guix/guile code that is. For people 
wanting to use code there is others. As there is for actually committing 
being discussed elsewhere for improvements.


Yes I want to help on all of them at some point :)


MSavoritias

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

[MSavoritias]

On 9/12/23 17:51, Maxim Cournoyer wrote:
> Hi,
>
> Csepp <raingloom@riseup.net> writes:
>
>> Giovanni Biscuolo <g@xelera.eu> writes:
>>
>>> [[PGP Signed Part:Undecided]]
>>> Hello Csepp,
>>>
>>> Csepp <raingloom@riseup.net> 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/ <https://sourcehut.gnu.org/>

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/10/23 01:20, Liliana Marie Prikler wrote:
> Am Samstag, dem 09.09.2023 um 21:40 +0200 schrieb Ricardo Wurmus:
>> Liliana Marie Prikler <liliana.prikler@gmail.com> 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?

[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?

[Simon Tournier]

Hi,

On Sun, 17 Sep 2023 at 19:20, MSavoritias <email@msavoritias.me> 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 <zimon.toutoune@gmail.com>
Thu, 24 Aug 2023 20:53:14 +0200
id:871qfsuvad.fsf@gmail.com
https://lists.gnu.org/archive/html/guix-devel/2023-08
https://yhetil.org/guix/871qfsuvad.fsf@gmail.com

2: Re: How can we decrease the cognitive overhead for contributors?
Vagrant Cascadian <vagrant@debian.org>
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 <cox.katherine.e@gmail.com>
Tue, 05 Sep 2023 13:15:48 -0600
id:13416fee-8c7d-b145-48b9-0fbec22517b1@gmail.com
https://lists.gnu.org/archive/html/guix-devel/2023-09
https://yhetil.org/guix/13416fee-8c7d-b145-48b9-0fbec22517b1@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 <email@msavoritias.me> 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?

[MSavoritias]

On 9/18/23 12:37, Simon Tournier wrote:
> Hi,
>
> On Sun, 17 Sep 2023 at 19:20, MSavoritias <email@msavoritias.me> 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 <zimon.toutoune@gmail.com>
> Thu, 24 Aug 2023 20:53:14 +0200
> id:871qfsuvad.fsf@gmail.com
> https://lists.gnu.org/archive/html/guix-devel/2023-08
> https://yhetil.org/guix/871qfsuvad.fsf@gmail.com
>
> 2: Re: How can we decrease the cognitive overhead for contributors?
> Vagrant Cascadian <vagrant@debian.org>
> 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 <cox.katherine.e@gmail.com>
> Tue, 05 Sep 2023 13:15:48 -0600
> id:13416fee-8c7d-b145-48b9-0fbec22517b1@gmail.com
> https://lists.gnu.org/archive/html/guix-devel/2023-09
> https://yhetil.org/guix/13416fee-8c7d-b145-48b9-0fbec22517b1@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?

[MSavoritias]

On 9/14/23 11:24, Ricardo Wurmus wrote:
> Fannys <email@fannys.me> 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?

[Simon Tournier]

On Mon, 18 Sept 2023 at 18:35, MSavoritias <email@msavoritias.me> 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/18/23 20:13, Simon Tournier wrote:
> On Mon, 18 Sept 2023 at 18:35, MSavoritias <email@msavoritias.me> 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]

Hi,

On Mon, 18 Sept 2023 at 19:40, MSavoritias <email@msavoritias.me> 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 <email@msavoritias.me>
Sun, 17 Sep 2023 19:20:48 +0300
id:f199249e-b30a-adf5-224f-1aed74a563fe@fannys.me
https://lists.gnu.org/archive/html/guix-devel/2023-09
https://yhetil.org/guix/f199249e-b30a-adf5-224f-1aed74a563fe@fannys.me

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 <email@msavoritias.me>
> > 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?

[Felix Lechner via 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

contribute with content in our official help pages?

[Giovanni Biscuolo]

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

Hi Simon and all readers,

I have some comments I cannot keep, just to try helping making this
thread harder to follow, if possible :-D.

Simon Tournier <zimon.toutoune@gmail.com> writes:

[...]

> 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/

Thank you for the pointers, Simon, I already knew [1] since I have a
look to 10years Guix from time to time but I missed [2].  Although I
don't personally use that tools, I find that information useful when
Someone™ asks me how do Something™ using tool XYZ with Guix... but I'm
sure in 5 minutes I'll forget almost all, since I don't usualy use all
XYZ tools.

How can we decrease the effort needed by Someone™ like me to find useful
informations on "how to do X with/in Guix"?

1. The "quick and dirty" solution is to use a "smart" query in a web
search engine:

Example query "guix write packages using vim":
https://duckduckgo.com/?q=guix+write+packages+using+vim

It's not very efficient since the searcher have to do some _hard_ work
first to find a "smart" query and then to filter out what he really
needs; last but not least to understand if that information is still
relevant or someway outdated or not working for his use-case.

I'd call this quite a high cognitive overhead.

2. Search one of our _official_ "Guix - Help" resources:
https://guix.gnu.org/en/help/

As you can see, We™ have plenty of them, in (my personal) reverse order
of information discoverability efficacy (cognitive overhead?):

  - IRC (logs): http://logs.guix.gnu.org/guix/
  - mailing lists, see: https://guix.gnu.org/en/contact/
  - videos: https://guix.gnu.org/en/videos/
  - wiki: https://libreplanet.org/wiki/Group:Guix
  - GNU manuals: https://gnu.org/manual
  - Cookbook: https://guix.gnu.org/cookbook/
  - GNU Guix Manual 1.4.0: https://guix.gnu.org/manual/en
  - GNU Guix Manual (Latest): https://guix.gnu.org/manual/devel/

Someone™ could help integrating useful information in one of the above
listed resources, for example informations like [1] and [2] should go to
"videos".

Each of the above listed help channels have very different contribution
workflows, ranging from chatting on IRC to sending a patch to include
Something™ in the cookbook or in the manual; this means that the more
Someone™ would like that information to traverse that list "upward", the
more will be the effort for Someone™ (Else™?) to add it...

It's a path and it's /also/ fractally recursive! :-D

For example, I have a feeling that many useful informations discussed in
this thread have been shared in previous messages on this mailing list
or IRC, wiki, videos... probably Someone™ shoud find a way to integrate
them /at least/ as a blog post in https://guix.gnu.org/en/blog/, if
Someone™ (Else™?) find it would be helpful in reducing the overhead to
do XYZ with/for Guix due to hard discoverability of that piece of useful
information; sometimes that piece of information is also /very/ useful
in reducing the cognitive overhead for contributors, that's recursivity
(© Simon Tournier).

To be cristal clear: I find that also "externally managed assets" - a
blog post, a video, a tool specifically designed for "Guix integration"
of tool XYZ, a Guix channel - **are** useful _contributions_, but that
kind of contributions are even harder to find and/or use if not properly
"integrated in Guix".

Happy hacking! Gio'

-- 
Giovanni Biscuolo

Xelera IT Infrastructures

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

The elephant in the room and the Guix Bang.

[Giovanni Biscuolo]

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

Hello,

...I'm talking about Emacs.

In <87bkdzssgm.fsf@gmail.com> [1] Simon Tournier <zimon.toutoune@gmail.com> writes:

[1] https://yhetil.org/guix/87bkdzssgm.fsf@gmail.com/

[...]

> people are already engaging for improving the accessibility of editors
> other than Emacs

Simon gave me the opportunity to realize (once again) that IMO there is
a foundamental misconception regarding Emacs.

What is Emacs, exacly: is it an editor?

I feel that a great deal of friction on the matter is due to the fact
that Emacs is usually defined as an /editor/ (OK text editor, but it
makes no difference)... **also** in its official page:

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

 An extensible, customizable, free/libre text editor — and more.
 
 At its core is an interpreter for Emacs Lisp, a dialect of the Lisp
 programming language with extensions to support text editing.

--8<---------------cut here---------------end--------------->8---
(https://www.gnu.org/software/emacs/)

IMO to define Emacs as a sort of «text editor on steroids with batteries
included (Emacs Lisp)» does not represent the real nature of the
program; an /effective/ definition would be:

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

 An extensible, customizable, free/libre user interface.
 
 At its core is an interpreter for Emacs Lisp, a dialect of the Lisp
 programming language, with extensions to use it as an interface to text
 editing functions and many, many more: MUA, web browser, task
 organizer...

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

To define Emacs as a /user interface/ it's not just a cool way to
"market it", it means to classify its /unique/ (?) user interface design
as one among all the historical instances of user interfaces:

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

1. batch interface
2. command line interface
3. SAA User Interface or Text-Based User Interface
4. graphical user interface
5. (editor note) web user interface

--8<---------------cut here---------------end--------------->8---
(https://en.wikipedia.org/wiki/User_interface#History)

Someone may consider Emacs "just" a "text-based user interface (UI)"
(point 3. of the above mentioned list) like the ones using curses and
alike (e.g. vim, mutt, ranger, Norton Commander and so on) but IMO Emacs
implements a very different design, centered around a specific UI
element called "emacs buffer".

I consider Emacs as a 6th class of user interface :-D

Just to bring my limited personal experience: I was a mutt+vim user for
email management, ranger for file management... and so on, and since I
was was **very** happy with my vim user experience when editing text,
for a very long time I looked at Emacs as "just" another text editor I
didn't need, because **as text editors** both vim, Emacs and alike are
/very/ powerful and I was never ever interested for just a sec to the
funny "editor war" (and similar "wars").

Then, one day, moved by curiosity and the fact that the Emacs interface
is /integrated/ in the notmuch mail indexer I was already using, I
started using Emacs as my preferred /user interface/ for notmuch... and
some year later here I am, trying to use the Emacs interface for as much
computing activities I can.

Now I see Emacs in a very different way.

Incidentally (?), AFAIU Emacs was the Guile IDE (integrated development
environment, not text editor) used by Ludovic when he started
programming Guix; he and probably some (many?) of the contributors was
so happy with their tool that they started sharing their configuration
snippets, as usual amoung a community of enthusiastic users... after
many refinements and maybe some Emacs extentions progamming, they was so
proud that they decided to recommend the same (set of) tool /and/
configuration to other _collegues_, the famous "perfect setup" described
in the Guix manual.

I'm also suspecting that the spark that started the "Guix Bang" in
Ludovic's mind, the very moment he realized nix could be better
_extended_ using Guile in place of it's DSL, was /caused/ by the fact he
was a Lisp programmer, the specific /dialect/ probably did not matter.
But I'm just guessing.

Now I see Guix in a different way. :-)

In this context: is the Guix project biased in recommending using Emacs
(a Lisp interpreter and compiler for Emacs Lisp) to contributors?  I
don't think so.

I'd rather say that - as in many other organizations and all similar
projects - Guix adopts a "BYOT" (bring your own tool) organizational
policy... and the first contributors brought theirs. :-D

For sure vim/neovim - and other tools - can also be extended and *used*
to provide /user interface/s for various external tools (e.g. see
fugitive.vim/nvim-fugitive) that are useful when using and/or developing
Guix, everyone is free to use and extend them, and also to share with
the whole Guix community how their beloved BYOT are working well.

Please see a recent message of mine (id:87pm2e4flj.fsf@xelera.eu [2])
for some of my comments (nothing really new, I just reused concept
already expressed by others) about the process needed to integrate
useful informations (configuration _is_ information) in Guix
official _recommandations_.

Happy hacking! Gio'

[2] https://yhetil.org/guix/87pm2e4flj.fsf@xelera.eu/

-- 
Giovanni Biscuolo

Xelera IT Infrastructures

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

Re: The elephant in the room and the Guix Bang.

[Simon Tournier]

Hi,

On Tue, 19 Sep 2023 at 18:35, Giovanni Biscuolo <g@xelera.eu> wrote:

> I'm also suspecting that the spark that started the "Guix Bang" in
> Ludovic's mind, the very moment he realized nix could be better
> _extended_ using Guile in place of it's DSL, was /caused/ by the fact he
> was a Lisp programmer, the specific /dialect/ probably did not matter.
> But I'm just guessing.

Reading your paragraph, it remembers me this reference:

    https://archive.fosdem.org/2015/schedule/event/the_emacs_of_distros/

(that I forgot when I wrote [1]).

Cheers,
simon

1: Re: How can we decrease the cognitive overhead for contributors?
Simon Tournier <zimon.toutoune@gmail.com>
Mon, 18 Sep 2023 12:09:45 +0200
id:87bkdzssgm.fsf@gmail.com
https://lists.gnu.org/archive/html/guix-devel/2023-09
https://yhetil.org/guix/87bkdzssgm.fsf@gmail.com

Re: The elephant in the room and the Guix Bang.

[Csepp]

Giovanni Biscuolo <g@xelera.eu> writes:

> [[PGP Signed Part:Undecided]]
> Hello,
>
> ...I'm talking about Emacs.
>
> In <87bkdzssgm.fsf@gmail.com> [1] Simon Tournier <zimon.toutoune@gmail.com> writes:
>
> [1] https://yhetil.org/guix/87bkdzssgm.fsf@gmail.com/
>
> [...]
>
>> people are already engaging for improving the accessibility of editors
>> other than Emacs
>
> Simon gave me the opportunity to realize (once again) that IMO there is
> a foundamental misconception regarding Emacs.
>
> What is Emacs, exacly: is it an editor?
>
> I feel that a great deal of friction on the matter is due to the fact
> that Emacs is usually defined as an /editor/ (OK text editor, but it
> makes no difference)... **also** in its official page:
>
>
>  An extensible, customizable, free/libre text editor — and more.
>  
>  At its core is an interpreter for Emacs Lisp, a dialect of the Lisp
>  programming language with extensions to support text editing.
>
> (https://www.gnu.org/software/emacs/)
>
> IMO to define Emacs as a sort of «text editor on steroids with batteries
> included (Emacs Lisp)» does not represent the real nature of the
> program; an /effective/ definition would be:
>
>
>  An extensible, customizable, free/libre user interface.
>  
>  At its core is an interpreter for Emacs Lisp, a dialect of the Lisp
>  programming language, with extensions to use it as an interface to text
>  editing functions and many, many more: MUA, web browser, task
>  organizer...
>
>
> To define Emacs as a /user interface/ it's not just a cool way to
> "market it", it means to classify its /unique/ (?) user interface design
> as one among all the historical instances of user interfaces:
>
>
> 1. batch interface
> 2. command line interface
> 3. SAA User Interface or Text-Based User Interface
> 4. graphical user interface
> 5. (editor note) web user interface
>
> (https://en.wikipedia.org/wiki/User_interface#History)
>
> Someone may consider Emacs "just" a "text-based user interface (UI)"
> (point 3. of the above mentioned list) like the ones using curses and
> alike (e.g. vim, mutt, ranger, Norton Commander and so on) but IMO Emacs
> implements a very different design, centered around a specific UI
> element called "emacs buffer".
>
> I consider Emacs as a 6th class of user interface :-D
>
> Just to bring my limited personal experience: I was a mutt+vim user for
> email management, ranger for file management... and so on, and since I
> was was **very** happy with my vim user experience when editing text,
> for a very long time I looked at Emacs as "just" another text editor I
> didn't need, because **as text editors** both vim, Emacs and alike are
> /very/ powerful and I was never ever interested for just a sec to the
> funny "editor war" (and similar "wars").
>
> Then, one day, moved by curiosity and the fact that the Emacs interface
> is /integrated/ in the notmuch mail indexer I was already using, I
> started using Emacs as my preferred /user interface/ for notmuch... and
> some year later here I am, trying to use the Emacs interface for as much
> computing activities I can.
>
> Now I see Emacs in a very different way.
>
> Incidentally (?), AFAIU Emacs was the Guile IDE (integrated development
> environment, not text editor) used by Ludovic when he started
> programming Guix; he and probably some (many?) of the contributors was
> so happy with their tool that they started sharing their configuration
> snippets, as usual amoung a community of enthusiastic users... after
> many refinements and maybe some Emacs extentions progamming, they was so
> proud that they decided to recommend the same (set of) tool /and/
> configuration to other _collegues_, the famous "perfect setup" described
> in the Guix manual.
>
> I'm also suspecting that the spark that started the "Guix Bang" in
> Ludovic's mind, the very moment he realized nix could be better
> _extended_ using Guile in place of it's DSL, was /caused/ by the fact he
> was a Lisp programmer, the specific /dialect/ probably did not matter.
> But I'm just guessing.
>
> Now I see Guix in a different way. :-)
>
> In this context: is the Guix project biased in recommending using Emacs
> (a Lisp interpreter and compiler for Emacs Lisp) to contributors?  I
> don't think so.
>
> I'd rather say that - as in many other organizations and all similar
> projects - Guix adopts a "BYOT" (bring your own tool) organizational
> policy... and the first contributors brought theirs. :-D
>
> For sure vim/neovim - and other tools - can also be extended and *used*
> to provide /user interface/s for various external tools (e.g. see
> fugitive.vim/nvim-fugitive) that are useful when using and/or developing
> Guix, everyone is free to use and extend them, and also to share with
> the whole Guix community how their beloved BYOT are working well.
>
> Please see a recent message of mine (id:87pm2e4flj.fsf@xelera.eu [2])
> for some of my comments (nothing really new, I just reused concept
> already expressed by others) about the process needed to integrate
> useful informations (configuration _is_ information) in Guix
> official _recommandations_.
>
> Happy hacking! Gio'
>
> [2] https://yhetil.org/guix/87pm2e4flj.fsf@xelera.eu/

Recommending Emacs would IMHO be fine, iff the UX wasn't so bad.  It's
better if we have at least one *well documented* developer setup, than
if we have a bunch of (sometimes conflicting) partial docs for setting
up certain subsystems.
Emacs can be pretty good, once you do (setq make-defaults-not-suck 1) a
bunch of times.

Re: The e(macs)lephant in the room and the Guix Bang

[Nguyễn Gia Phong via Development of GNU Guix and the GNU System distribution.]

On 2023-09-20 at 10:21+02:00, Csepp wrote:
> It's better if we have at least one *well documented* developer setup,
> than if we have a bunch of (sometimes conflicting) partial docs
> for setting up certain subsystems.
>
> Emacs can be pretty good, once you do (setq make-defaults-not-suck 1)
> a bunch of times.

Or even more outrageous, an overriden Emacs package
with all the good stuff for Guix development.
We already have guix shell that spawns a shell
and guix edit that spawns an editor, why no guix boot
that spawns an OS^W^W Emacs with appropriate defaults?

Disclaimer: I use the devil editor that goes by the number
of VI VI VI, so take this suggestion with a grain of salt.

Re: The e(macs)lephant in the room and the Guix Bang

[MSavoritias]

On 9/20/23 11:45, Nguyễn Gia Phong via Development of GNU Guix and the 
GNU System distribution. wrote:
> On 2023-09-20 at 10:21+02:00, Csepp wrote:
>> It's better if we have at least one *well documented* developer setup,
>> than if we have a bunch of (sometimes conflicting) partial docs
>> for setting up certain subsystems.
>>
>> Emacs can be pretty good, once you do (setq make-defaults-not-suck 1)
>> a bunch of times.
> Or even more outrageous, an overriden Emacs package
> with all the good stuff for Guix development.
> We already have guix shell that spawns a shell
> and guix edit that spawns an editor, why no guix boot
> that spawns an OS^W^W Emacs with appropriate defaults?
>
> Disclaimer: I use the devil editor that goes by the number
> of VI VI VI, so take this suggestion with a grain of salt.
>

Can't the guile editor be that?

It kind of tries to be already. We just need to promote it and dogfood 
it more.


MSavoritias

Re: The e(macs)lephant in the room and the Guix Bang

[Ricardo Wurmus]

MSavoritias <email@msavoritias.me> writes:

> On 9/20/23 11:45, Nguyễn Gia Phong via Development of GNU Guix and the
> GNU System distribution. wrote:
>> On 2023-09-20 at 10:21+02:00, Csepp wrote:
>>> It's better if we have at least one *well documented* developer setup,
>>> than if we have a bunch of (sometimes conflicting) partial docs
>>> for setting up certain subsystems.
>>>
>>> Emacs can be pretty good, once you do (setq make-defaults-not-suck 1)
>>> a bunch of times.
>> Or even more outrageous, an overriden Emacs package
>> with all the good stuff for Guix development.
>> We already have guix shell that spawns a shell
>> and guix edit that spawns an editor, why no guix boot
>> that spawns an OS^W^W Emacs with appropriate defaults?
>>
>> Disclaimer: I use the devil editor that goes by the number
>> of VI VI VI, so take this suggestion with a grain of salt.
>>
>
> Can't the guile editor be that?
>
> It kind of tries to be already. We just need to promote it and dogfood
> it more.

Do you mean Guile Studio?[1]

It was really only intended to be a pre-configured editor for new
Guilers, which is why it includes the picture language and Geiser with
picture display.

But as I wrote there

   There are many more things that can be done to make Emacs less
   confusing for people who use it just as a Guile IDE. I would be happy
   to hear your suggestions or apply patches to improve Guile Studio!

This is still true today.

[1]: https://elephly.net/guile-studio/

-- 
Ricardo

Re: The e(macs)lephant in the room and the Guix Bang

[MSavoritias]

On 9/20/23 17:03, Ricardo Wurmus wrote:
> MSavoritias <email@msavoritias.me> writes:
>
>> On 9/20/23 11:45, Nguyễn Gia Phong via Development of GNU Guix and the
>> GNU System distribution. wrote:
>>> On 2023-09-20 at 10:21+02:00, Csepp wrote:
>>>> It's better if we have at least one *well documented* developer setup,
>>>> than if we have a bunch of (sometimes conflicting) partial docs
>>>> for setting up certain subsystems.
>>>>
>>>> Emacs can be pretty good, once you do (setq make-defaults-not-suck 1)
>>>> a bunch of times.
>>> Or even more outrageous, an overriden Emacs package
>>> with all the good stuff for Guix development.
>>> We already have guix shell that spawns a shell
>>> and guix edit that spawns an editor, why no guix boot
>>> that spawns an OS^W^W Emacs with appropriate defaults?
>>>
>>> Disclaimer: I use the devil editor that goes by the number
>>> of VI VI VI, so take this suggestion with a grain of salt.
>>>
>> Can't the guile editor be that?
>>
>> It kind of tries to be already. We just need to promote it and dogfood
>> it more.
> Do you mean Guile Studio?[1]
>
> It was really only intended to be a pre-configured editor for new
> Guilers, which is why it includes the picture language and Geiser with
> picture display.
>
> But as I wrote there
>
>     There are many more things that can be done to make Emacs less
>     confusing for people who use it just as a Guile IDE. I would be happy
>     to hear your suggestions or apply patches to improve Guile Studio!
>
> This is still true today.
>
> [1]: https://elephly.net/guile-studio/
>
I did yeah. That's why i said we should promote it more to newcomers 
instead of plain Emacs.

I think guile and guix are close that it could easily be a guix-IDE too.


MSavoritias

Re: The e(macs)lephant in the room and the Guix Bang

[Andy Tai]

Hi, for some reason emacs has become the elephant in the room of the
discussion on contributing to guix.

Regardless of one's opinion of emacs, I just want to add that this is
itself strange.  I have contributed some (package definition) patches
to guix, all without using emacs.

I am not an emacs user, so emacs is not necessary for contributing to guix.
For what it's worth, the emacs-motif package in Guix was my addition.
I don't use it myself.

Re: The elephant in the room and the Guix Bang.

[Giovanni Biscuolo]

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

Hi,

Simon Tournier <zimon.toutoune@gmail.com> writes:

> Hi,
>
> On Tue, 19 Sep 2023 at 18:35, Giovanni Biscuolo <g@xelera.eu> wrote:
>
>> I'm also suspecting that the spark that started the "Guix Bang" in
>> Ludovic's mind, the very moment he realized nix could be better
>> _extended_ using Guile in place of it's DSL, was /caused/ by the fact he
>> was a Lisp programmer, the specific /dialect/ probably did not matter.
>> But I'm just guessing.
>
> Reading your paragraph, it remembers me this reference:
>
>     https://archive.fosdem.org/2015/schedule/event/the_emacs_of_distros/
>
> (that I forgot when I wrote [1]).

Oh thanks!  I also forgot it.

With this search restricted to guix.gnu.org :
https://duckduckgo.com/?q=%22emacs+of+distros%22+site%3Ahttps%3A%2F%2Fguix.gnu.org%2F&ia=web

I foud the relevant blog post:
https://guix.gnu.org/en/blog/2015/gnu-guix-at-fosdem/

I found a copy of the slides on the Guix site, also:
https://guix.gnu.org/guix-fosdem-20150131.pdf

Maybe a search box in the menu of https://guix.gnu.org/ would be
helpful...

...but a good search query is all we need, sometimes! :-D

Last but _not_ least, I find this is a very inspiring  Emacs talk:
«EmacsConf 2021: How Emacs made me appreciate software freedom»
https://protesilaos.com/codelog/2021-12-21-emacsconf2021-freedom/

The concepts presented there are valid also for Guix, IMO

Thanks! Gio'

-- 
Giovanni Biscuolo

Xelera IT Infrastructures

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

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

[Imran Iqbal]

On Sun, Sep 03, 2023 at 05:45:41PM +0000, 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?

[Katherine Cox-Buday]

Imran Iqbal <imran@imraniqbal.org> 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?

[Ekaitz Zarraga]

Hi,


> On Sun, Sep 03, 2023 at 05:45:41PM +0000, 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 of people in guix
think it's a good idea to move to a web based approach, I think, the fairest
thing for guix to do is to acknowledge that, at least.
That's probably not the case in this email thread, but if people like it in
the future, maybe we should do it.

Now, my opinion, in a different perspective. Just in case I didn't express
it properly.

I really like the email approach but it is true it can be hard to follow for
new people. That doesn't really bother me a lot. The focus should be on
contributors. I am a contributor, Katherine, who started this, is a contributor
that has potential to contribute way more and we don't have the pleasure to
get commits from because of this overhead.
Using a web based approach is probably not going to fix it, but listening to
people's needs and find a way to make the process smoother probably will.

It's a job that involves all of us. From my side, instead of blaming people
for their choices, I'll try to take part in the survey (which is a really
good consequence of this thread) and from it probably take the responsibility
to write some docs or help people from my perspective as a person that doesn't
use emacs and loves lisp, guile and guix anyway. 


Best regards,
Ekaitz

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 +0000, 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]

 
> 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: The e(macs)lephant in the room and the Guix Bang

[Nathan Dehnel]

________________________________

>Hi, for some reason emacs has become the elephant in the room of the
discussion on contributing to guix.

>Regardless of one's opinion of emacs, I just want to add that this is
itself strange.  I have contributed some (package definition) patches
to guix, all without using emacs.

>I am not an emacs user, so emacs is not necessary for contributing to guix.
For what it's worth, the emacs-motif package in Guix was my addition.
I don't use it myself.

I don't use emacs either (because it's so impenetrable), so I just use
kate instead, which isn't a great environment for me either. It has
rainbow parens, but it doesn't balance them, which is a hassle. I keep
using it though due to lack of time to browse through alternatives. I
heard about guile-studio, but it doesn't appear to have a dark mode,
and I imagine trying to add one would require a bunch of emacs-style
screwing around with it.

https://archive.fosdem.org/2022/schedule/event/lispforeveryone/
This is the only setup for coding in lisp that has actually looked
attractive to me. (Coding in wisp with colored blocks that transpiles
to s-expressions) Though I haven't had the time (and probably
expertise) to set it up for myself.

Re: The e(macs)lephant in the room and the Guix Bang

[Janneke Nieuwenhuizen]

Nathan Dehnel writes:

> I don't use emacs either (because it's so impenetrable)

Emacs might be somewhat different from what you know, but this is utter
bollocks.

Switching to Emacs (from vi) took me three summers.  I kept trying
because I had seen how helpful it was, and well the statement that "the
GNU project will use it as its editor".

That was some 25y ago and it was time very well spent.  After I
switched, I taught it to my dad for his latex editing, who went on to
create patches for the Dutch tutorial because he wanted to give back
something..  If he could learn, most anyone should be able to pick it
up.

People are still indenting their code manually today, etc... it's
ridiculous.  Also, magit.

Greetings,
Janneke

-- 
Janneke Nieuwenhuizen <janneke@gnu.org>  | GNU LilyPond https://LilyPond.org
Freelance IT https://www.JoyOfSource.com | Avatar® https://AvatarAcademy.com

Re: The e(macs)lephant in the room and the Guix Bang

[paul]

Dear Janneke,

On 9/23/23 09:37, Janneke Nieuwenhuizen wrote:
> Nathan Dehnel writes:
>
>> I don't use emacs either (because it's so impenetrable)
> Emacs might be somewhat different from what you know, but this is utter
> bollocks.

Thank you for your opinion but it's just that: a subjective judgement 
based on your own episodic experience. Which is definitely valid but 
unrealistically shared by so many to be able to define Nathan's 
experience "utter bollocks".

I think this attitude (in my experience typical of GNU maintainers) 
where their way of doing computation is more blessed or holier or better 
sometimes really ruins the social interactions happening around Guix 
(which is the safest  community in the GNU project imho, probably also 
due to the distance they rightfully posed during the whole stallman drama).

It's especially problematic when people in power such as maintainers do 
not realize their role in the community. You have more power, probably 
due to your investment you have a clearer vision of where the project is 
going as well. You are supposed to be a role model for new users and 
contributors.

> If he could learn, most anyone should be able to pick it
> up.
> People are still indenting their code manually today, etc... it's
> ridiculous.
This behavior is not ok. Again, please, stop throwing your judgement on 
people. Potential users or contributors even.
> Also, magit.

I use Emacs, love magit, I used to use it daily also at $day_job on 
Windows because it's just so good, but I can assure you most of Git 
users never heard of it and live their life pretty happily.

giacomo

Re: The e(macs)lephant in the room and the Guix Bang

[Ricardo Wurmus]

Nathan Dehnel <ncdehnel@gmail.com> writes:

> heard about guile-studio, but it doesn't appear to have a dark mode,
> and I imagine trying to add one would require a bunch of emacs-style
> screwing around with it.

M-x modus-themes-toggle RET

i.e. hold Alt, press x, then type “modus-themes-toggle” and hit the
return key.

We can add a little toggle button to Guile Studio that does this.

-- 
Ricardo

Re: The e(macs)lephant in the room and the Guix Bang

[Janneke Nieuwenhuizen]

paul writes:

Dear Paul,

> On 9/23/23 09:37, Janneke Nieuwenhuizen wrote:
>> Nathan Dehnel writes:
>>
>>> I don't use emacs either (because it's so impenetrable)
>> Emacs might be somewhat different from what you know, but this is utter
>> bollocks.
>
> Thank you for your opinion but it's just that: a subjective judgement
> based on your own episodic experience.

I'm sorry if my tone was too harsh, I now realise this is still
triggering old pain.

Why is it still OK to for people to keep spreading negative anecdotes
about Emacs, and problematic to refute them or counter them with
positive anecdotes?

It's been me believing exactly such lies that scared me away from
starting with Emacs for years, lost years in a way; something I deeply
regret: this has to stop.

Greetings,
Janneke

-- 
Janneke Nieuwenhuizen <janneke@gnu.org>  | GNU LilyPond https://LilyPond.org
Freelance IT https://www.JoyOfSource.com | Avatar® https://AvatarAcademy.com

Re: The e(macs)lephant in the room and the Guix Bang

[Ricardo Wurmus]

Ricardo Wurmus <rekado@elephly.net> writes:

> Nathan Dehnel <ncdehnel@gmail.com> writes:
>
>> heard about guile-studio, but it doesn't appear to have a dark mode,
>> and I imagine trying to add one would require a bunch of emacs-style
>> screwing around with it.
>
> M-x modus-themes-toggle RET
>
> i.e. hold Alt, press x, then type “modus-themes-toggle” and hit the
> return key.
>
> We can add a little toggle button to Guile Studio that does this.

To affect the context menu and menu bar you’d also need to do set the
GTK_THEME variable when starting Guile Studio, e.g.

    GTK_THEME=Adwaita:dark guile-studio

I’ll try to change Guile Studio so that it will automatically pick the
dark or light variant of the theme dependent on system preferences, but
for now this is the workaround that should get you most of the way to a
dark theme.

-- 
Ricardo

Re: The e(macs)lephant in the room and the Guix Bang

[Ricardo Wurmus]

Ricardo Wurmus <rekado@elephly.net> writes:

> Nathan Dehnel <ncdehnel@gmail.com> writes:
>
>> heard about guile-studio, but it doesn't appear to have a dark mode,
>> and I imagine trying to add one would require a bunch of emacs-style
>> screwing around with it.
>
> M-x modus-themes-toggle RET
>
> i.e. hold Alt, press x, then type “modus-themes-toggle” and hit the
> return key.
>
> We can add a little toggle button to Guile Studio that does this.

Actually, I just noticed that Guile Studio already tells you how to do
this in the help pane that is displayed on startup:

    Toggle between dark and light mode with F5.

-- 
Ricardo

Re: The e(macs)lephant in the room and the Guix Bang

[Nathan Dehnel]

Oh, thank you, that's lovely.

On Sat, Sep 23, 2023 at 4:59 AM Ricardo Wurmus <rekado@elephly.net> wrote:
>
>
> Nathan Dehnel <ncdehnel@gmail.com> writes:
>
> > heard about guile-studio, but it doesn't appear to have a dark mode,
> > and I imagine trying to add one would require a bunch of emacs-style
> > screwing around with it.
>
> M-x modus-themes-toggle RET
>
> i.e. hold Alt, press x, then type “modus-themes-toggle” and hit the
> return key.
>
> We can add a little toggle button to Guile Studio that does this.
>
> --
> Ricardo

Re: The e(macs)lephant in the room and the Guix Bang

[Nathan Dehnel]

>I'm sorry if my tone was too harsh, I now realise this is still
triggering old pain.

>Why is it still OK to for people to keep spreading negative anecdotes
about Emacs, and problematic to refute them or counter them with
positive anecdotes?

It was a mistake to say that. I felt the reflexive need to justify why
I don't use emacs, or else people would just tell me to use it anyways
as a result of talking about not knowing of a decent (alternative)
lisp editor.

>It's been me believing exactly such lies that scared me away from
starting with Emacs for years, lost years in a way; something I deeply
regret: this has to stop.

I want to clarify that I'm not just repeating rumors and I actually
have tried to use emacs.

On Sat, Sep 23, 2023 at 5:00 AM Janneke Nieuwenhuizen <janneke@gnu.org> wrote:
>
> paul writes:
>
> Dear Paul,
>
> > On 9/23/23 09:37, Janneke Nieuwenhuizen wrote:
> >> Nathan Dehnel writes:
> >>
> >>> I don't use emacs either (because it's so impenetrable)
> >> Emacs might be somewhat different from what you know, but this is utter
> >> bollocks.
> >
> > Thank you for your opinion but it's just that: a subjective judgement
> > based on your own episodic experience.
>
> I'm sorry if my tone was too harsh, I now realise this is still
> triggering old pain.
>
> Why is it still OK to for people to keep spreading negative anecdotes
> about Emacs, and problematic to refute them or counter them with
> positive anecdotes?
>
> It's been me believing exactly such lies that scared me away from
> starting with Emacs for years, lost years in a way; something I deeply
> regret: this has to stop.
>
> Greetings,
> Janneke
>
> --
> Janneke Nieuwenhuizen <janneke@gnu.org>  | GNU LilyPond https://LilyPond.org
> Freelance IT https://www.JoyOfSource.com | Avatar® https://AvatarAcademy.com

Re: The e(macs)lephant in the room and the Guix Bang

[Liliana Marie Prikler]

Am Sonntag, dem 24.09.2023 um 02:37 -0500 schrieb Nathan Dehnel:
> > I'm sorry if my tone was too harsh, I now realise this is still
> > triggering old pain.
> 
> > Why is it still OK to for people to keep spreading negative
> > anecdotes about Emacs, and problematic to refute them or counter
> > them with positive anecdotes?
> 
> It was a mistake to say that. I felt the reflexive need to justify
> why I don't use emacs, or else people would just tell me to use it
> anyways as a result of talking about not knowing of a decent
> (alternative) lisp editor.
I mean, you could try using it anyways, whether it's vanilla emacs,
customized emacs, guile studio, or the heavily popularized spacemacs,
doom, etc. variants.  On the Guix side, it doesn't really matter, our
configuration works with packages based on Emacs.

It's fine if you prefer another editor, but don't count on us to write
documentation for every editor out there, especially when it almost
always turns out to be invoking "guix edit" followed by "git commit …"
or perhaps using that editor's built-in VC integration to do so.  I'm
also not convinced you need to bring the big guns of lisp editing to
the table.  From personal experience, an editor that autocompletes the
closing bracket and has parentheses matching capabilities suffices. 
The latter is even implemented by crude tools such as gnome-text-
editor.

> > It's been me believing exactly such lies that scared me away from
> > starting with Emacs for years, lost years in a way; something I
> > deeply regret: this has to stop.
> 
> I want to clarify that I'm not just repeating rumors and I actually
> have tried to use emacs.
There is a wide span of "tried emacs".  I personally wouldn't say I've
"tried" vi after hitting ESC :q once and being done or even that I've
tried using ed after vaguely figuring out how you can make it actually
change the contents of a file.

Now whether you want to qualify your experience further or not is up to
you, and even if you do, your personal choice of a suitable editor
remains personal.  However, I don't think that repeating the age old
jokes of "herp derp, me no likes defaults" as has happened in other
branches of this topic is helpful.  *The defaults in Emacs do not
matter.*  You don't need to be happy with the editor you get out of the
box.  You can change it into the editor you want and there's ample
documentation on how to do so.  Coming full circle, this is why we
reference Emacs in the manual, enough people collaborated to suggest a
workflow that works for them or at least goes in the right direction. 
However, I think it's fair to say that most folks' setup will differ
ever so slightly from what is presented there.

Cheers

Re: The e(macs)lephant in the room and the Guix Bang

[Csepp]

Ricardo Wurmus <rekado@elephly.net> writes:

> Nathan Dehnel <ncdehnel@gmail.com> writes:
>
>> heard about guile-studio, but it doesn't appear to have a dark mode,
>> and I imagine trying to add one would require a bunch of emacs-style
>> screwing around with it.
>
> M-x modus-themes-toggle RET
>
> i.e. hold Alt, press x, then type “modus-themes-toggle” and hit the
> return key.
>
> We can add a little toggle button to Guile Studio that does this.

Kinda tangential, but could Emacs be made to just use the system (GTK)
theme?
(In general there are a looot of places where Emacs should just stop
doing its own thing and properly integrate with the system services and
settings.)

Re: The e(macs)lephant in the room and the Guix Bang

[Ricardo Wurmus]

Csepp <raingloom@riseup.net> writes:

> Ricardo Wurmus <rekado@elephly.net> writes:
>
>> Nathan Dehnel <ncdehnel@gmail.com> writes:
>>
>>> heard about guile-studio, but it doesn't appear to have a dark mode,
>>> and I imagine trying to add one would require a bunch of emacs-style
>>> screwing around with it.
>>
>> M-x modus-themes-toggle RET
>>
>> i.e. hold Alt, press x, then type “modus-themes-toggle” and hit the
>> return key.
>>
>> We can add a little toggle button to Guile Studio that does this.
>
> Kinda tangential, but could Emacs be made to just use the system (GTK)
> theme?

Yes, that’s my plan, but I don’t have enough time this month to work on
it.  My notes:

+ when =dconf read /org/gnome/desktop/interface/color-scheme= returns
  ’prefer-dark’ enable dark mode by default.

+ use =xprop= to change the theme variant *after* the frame has been created; see
  https://gist.github.com/itoshkov/850c46746705e32e2039fb0112a75ec7
  
+ we may also need to set =GTK_THEME= to =Adwaita:dark= before actually
  launching Guile Studio.  Or rather the value at
  =/org/gnome/desktop/wm/preferences/theme= followed by =:dark=.  This
  can be done in shell wrapper.

-- 
Ricardo

Re: The e(macs)lephant in the room and the Guix Bang

[MSavoritias]

On 9/23/23 13:00, Janneke Nieuwenhuizen wrote:
> paul writes:
>
> Dear Paul,
>
>> On 9/23/23 09:37, Janneke Nieuwenhuizen wrote:
>>> Nathan Dehnel writes:
>>>
>>>> I don't use emacs either (because it's so impenetrable)
>>> Emacs might be somewhat different from what you know, but this is utter
>>> bollocks.
>> Thank you for your opinion but it's just that: a subjective judgement
>> based on your own episodic experience.
> I'm sorry if my tone was too harsh, I now realise this is still
> triggering old pain.
>
> Why is it still OK to for people to keep spreading negative anecdotes
> about Emacs, and problematic to refute them or counter them with
> positive anecdotes?
>
> It's been me believing exactly such lies that scared me away from
> starting with Emacs for years, lost years in a way; something I deeply
> regret: this has to stop.
>
> Greetings,
> Janneke
>
Depends what Emacs you mean.

The vanilla Emacs experience is traditionally horrible until you start 
tweaking it.

And it for years the maintainers of Emacs refuse to do anything to fix 
it. So I would say complaints are pretty valid

when its the same people that push Emacs as the "blessed" way to 
contribute (as in the guix manual) and then people see Emacs vanilla and 
cant use it.


The problematic is not that you say positive stuff about Emacs. I have a 
lot of positive stuff to say too :)

The problem part is the way you dismissed the persons experience as 
"bollocks". The knowledge that the Emacs community is pretty 
conservative in changing anything for decades in the default config also 
doesn't help.


MSavoritias

Re: The e(macs)lephant in the room and the Guix Bang

[MSavoritias]

On 9/24/23 11:51, Liliana Marie Prikler wrote:
> Am Sonntag, dem 24.09.2023 um 02:37 -0500 schrieb Nathan Dehnel:
>>> I'm sorry if my tone was too harsh, I now realise this is still
>>> triggering old pain.
>>> Why is it still OK to for people to keep spreading negative
>>> anecdotes about Emacs, and problematic to refute them or counter
>>> them with positive anecdotes?
>> It was a mistake to say that. I felt the reflexive need to justify
>> why I don't use emacs, or else people would just tell me to use it
>> anyways as a result of talking about not knowing of a decent
>> (alternative) lisp editor.
> I mean, you could try using it anyways, whether it's vanilla emacs,
> customized emacs, guile studio, or the heavily popularized spacemacs,
> doom, etc. variants.  On the Guix side, it doesn't really matter, our
> configuration works with packages based on Emacs.
>
> It's fine if you prefer another editor, but don't count on us to write
> documentation for every editor out there, especially when it almost
> always turns out to be invoking "guix edit" followed by "git commit …"
> or perhaps using that editor's built-in VC integration to do so.  I'm
> also not convinced you need to bring the big guns of lisp editing to
> the table.  From personal experience, an editor that autocompletes the
> closing bracket and has parentheses matching capabilities suffices.
> The latter is even implemented by crude tools such as gnome-text-
> editor.

How about we start with two editors then besides vanilla Emacs then?

Because we don't even have two now.

>>> It's been me believing exactly such lies that scared me away from
>>> starting with Emacs for years, lost years in a way; something I
>>> deeply regret: this has to stop.
>> I want to clarify that I'm not just repeating rumors and I actually
>> have tried to use emacs.
> There is a wide span of "tried emacs".  I personally wouldn't say I've
> "tried" vi after hitting ESC :q once and being done or even that I've
> tried using ed after vaguely figuring out how you can make it actually
> change the contents of a file.
>
> Now whether you want to qualify your experience further or not is up to
> you, and even if you do, your personal choice of a suitable editor
> remains personal.  However, I don't think that repeating the age old
> jokes of "herp derp, me no likes defaults" as has happened in other
> branches of this topic is helpful.  *The defaults in Emacs do not
> matter.*  You don't need to be happy with the editor you get out of the
> box.  You can change it into the editor you want and there's ample
> documentation on how to do so.  Coming full circle, this is why we
> reference Emacs in the manual, enough people collaborated to suggest a
> workflow that works for them or at least goes in the right direction.
> However, I think it's fair to say that most folks' setup will differ
> ever so slightly from what is presented there.
>
> Cheers
>
>
That's the thing you are missing.

The default of Emacs absolutely do matter.

Because

1. not everybody has time to learn elisp and configure Emacs so it 
doesn't break.

2. By how the defaults are you see how the community around a program is.

If the defaults are good and empower the person using the program that 
means that the community is open

to suggestions and changes at the very least. which is not what happens 
with Emacs.

This is from someone who uses Emacs.


MSavoritias

Re: Enabling contribution through documentation

[Samuel Christie via Development of GNU Guix and the GNU System distribution.]

Ekaitz Zarraga <ekaitz@elenq.tech> writes:

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

As a long-time wannabe-contributor who has been intimidated by the 
unfamiliar process, I agree with this statement.

In fact, (to acknowledge the other more controversial branch of 
this conversation), I am already an avid user of emacs and 
plain-text email, so they do not in the least discourage me from 
contributing. The "difficulties" of editing s-expressions are 
non-issues for me; I have been using guix as both a daily driver 
and headless server for a while, and occasionally edit system 
definitions and even code snippets using mediocre editors like 
nano without difficulty. That said, I never quite figured out a 
good development environment and workflow for building packages or 
hacking on guix itself. Some of that is on me, but I think there 
is probably room for improvement in both the tools and 
documentation.

However, the unfamiliar process and my cautious personality 
fearing I might "mess something up" or "bother somebody" have been 
the biggest barriers to getting started. And last I checked there 
was not really a tutorial or "safe zone" for practicing to help 
overcome those challenges. I have actually been planning to start 
pushing through and writing up a tutorial as I go, and signing up 
for the guix-devel mailing list again was a step in that 
direction, so this discussion is rather timely.

My recommendation consists of three parts:
  1. Write a clear tutorial
  2. Offer a "test environment" for new users to practice in
  3. Refine documentation into clearer 'how-to' and 'reference' 
  material

My current thoughts are building off the 'theory of documentation' 
described here:
  https://documentation.divio.com/index.html

(1) According to this theory, tutorials are learning experiences 
that that don't explain much, but simply guide the newbie with 
step-by-step directions they can follow as-is. We can probably 
adapt the sourcehut git + email tutorial for part of that purpose:
  https://git-send-email.io/
Such a tutorial would be helpful for onboarding new contributors 
because they don't have to know anything before getting started, 
just start at the beginning and follow the steps. The tutorial I 
was envisioning would work through the steps of writing a simple 
package, testing it, then submitting the patches.

I also thought it would be neat if we could have a more difficult 
version assigns outdated packages for upgrading (could even have a 
leaderboard and make a game out of it), but that's probably a 
different project.

(2) The test environment idea is based partly on the sourcehut 
tutorial, and at simplest is a separate mailing list that people 
can send test attempts to. Other people could subscribe and reply 
with comments on how to fix things, or we could (eventually) 
automate it to return feedback instantly. Ideally this environment 
would be as close to the real one as possible, but I'm not sure 
what that would mean exactly.

(3) The third point is a longer term goal for cleaning up the 
existing documentation, which is a mixture of all four kinds. For 
example, the 'Sending a patch series' page is written casually 
like a tutorial but abstractly covers several ways of doing it 
instead of guiding with concrete steps to achieve a specific goal. 
Unfortunately, this point is a lot of work and a much longer term 
goal, and I'm not really prepared or motivated to do all of it 
myself. I'm just mentioning it here as a potential path toward 
better documentation.


Now, for a proposal / call to action:

I intended to start working on the tutorial by myself soon anyway, 
but I am more likely to be motivated and successful if someone 
else cared about what I was working on. Would any of you more 
experienced developers be willing to "shepherd" me through this 
process, and help set up the test environment, etc.?

Thanks,
-shcv

Re: The e(macs)lephant in the room and the Guix Bang

[Liliana Marie Prikler]

Am Montag, dem 25.09.2023 um 14:19 +0300 schrieb MSavoritias:
> 
> On 9/24/23 11:51, Liliana Marie Prikler wrote:
> > [...]
> > It's fine if you prefer another editor, but don't count on us to
> > write documentation for every editor out there [...]
> 
> How about we start with two editors then besides vanilla Emacs then?
> 
> Because we don't even have two now.
Well, assuming you count Emacs variants (given the "vanilla" prefix
it'd only be fair if you did), we actually have at least four covered
with the manual, if not more. :)

As for other editors, I point to the sign above, with "us" being folks
who are happy to contribute to Guix from Emacs.  I know there are vi
folk out there who could probably make our section on "The Perfect
Setup" less biased, but I neither want nor am able to speak on their
behalf when it comes to actually doing so.

> > > > It's been me believing exactly such lies that scared me away
> > > > from starting with Emacs for years, lost years in a way;
> > > > something I deeply regret: this has to stop.
> > > I want to clarify that I'm not just repeating rumors and I
> > > actually have tried to use emacs.
> > There is a wide span of "tried emacs".  I personally wouldn't say
> > I've "tried" vi after hitting ESC :q once and being done or even
> > that I've tried using ed after vaguely figuring out how you can
> > make it actually change the contents of a file.
> > 
> > Now whether you want to qualify your experience further or not is
> > up to you, and even if you do, your personal choice of a suitable
> > editor remains personal.  However, I don't think that repeating the
> > age old jokes of "herp derp, me no likes defaults" as has happened
> > in other branches of this topic is helpful.  *The defaults in Emacs
> > do not matter.*  You don't need to be happy with the editor you get
> > out of the box.  You can change it into the editor you want and
> > there's ample documentation on how to do so.  Coming full circle,
> > this is why we reference Emacs in the manual, enough people
> > collaborated to suggest a workflow that works for them or at least
> > goes in the right direction.  However, I think it's fair to say
> > that most folks' setup will differ ever so slightly from what is
> > presented there.
> > 
> > Cheers
> > 
> > 
> That's the thing you are missing.
> 
> The default of Emacs absolutely do matter.
> 
> Because
> 
> 1. not everybody has time to learn elisp and configure Emacs so it 
> doesn't break.
> 
> 2. By how the defaults are you see how the community around a program
> is.
> 
> If the defaults are good and empower the person using the program
> that means that the community is open to suggestions and changes at
> the very least. which is not what happens with Emacs.
> 
> This is from someone who uses Emacs.
I share neither the experience nor the argument.  Now granted, I do see
the appeal of preconfigured Emacsen for those who don't want to go
through the trouble of configuring it for themselves; however, there is
no "one size fits all" solution among these offerings as far as I can
see.  In fact, I'd argue the opposite, as they themselves have to offer
customization so to appeal to a broader audience.  For all the rant
about how insane the defaults of Emacs are, the various "sane defaults"
offered by others sure tend in various different directions.  It's
almost as though coding for the common case leaves many people out and
the customization mechanism is what actually empowers users.

Cheers

Re: The e(macs)lephant in the room and the Guix Bang

[Simon Tournier]

Hi,

On Mon, 25 Sep 2023 at 20:54, Liliana Marie Prikler <liliana.prikler@gmail.com> wrote:

>> The default of Emacs absolutely do matter.

[...]

> I share neither the experience nor the argument. 

[...]

Please, we are not on the emacs-devel mailing list. :-)  Or maybe, we
need to create some guix-tagents mailing list. ;-)

Cheers,
simon

Re: The e(macs)lephant in the room and the Guix Bang

[Christine Lemmer-Webber]

Nathan Dehnel <ncdehnel@gmail.com> writes:

> ________________________________
>
>> Hi, for some reason emacs has become the elephant in the room of the
>> discussion on contributing to guix.
>>
>> Regardless of one's opinion of emacs, I just want to add that this is
>> itself strange.  I have contributed some (package definition) patches
>> to guix, all without using emacs.
>>
>> I am not an emacs user, so emacs is not necessary for contributing to guix.
>> For what it's worth, the emacs-motif package in Guix was my addition.
>> I don't use it myself.
>
> I don't use emacs either (because it's so impenetrable), so I just use
> kate instead, which isn't a great environment for me either. It has
> rainbow parens, but it doesn't balance them, which is a hassle. I keep
> using it though due to lack of time to browse through alternatives. I
> heard about guile-studio, but it doesn't appear to have a dark mode,
> and I imagine trying to add one would require a bunch of emacs-style
> screwing around with it.
>
> https://archive.fosdem.org/2022/schedule/event/lispforeveryone/
> This is the only setup for coding in lisp that has actually looked
> attractive to me. (Coding in wisp with colored blocks that transpiles
> to s-expressions) Though I haven't had the time (and probably
> expertise) to set it up for myself.

Happy to see this talk get some attention.  It does advocate a variety
of possible approaches, one of them Wisp (and the wisp-mode colored
block stuff is pretty awesome).

If you like that approach and want to not have to do the
parenthesis-balancing as much yourself, there's an interesting overlap
between Wisp and parinfer, which automatically infers the parentheses
from whitespace but keeps them in the actual source.  I have personally
never tried using parinfer for serious tasks though.  It still requires
an editor set up for those features.

Since Spritely is also using Guile heavily, we have also spent a lot of
time talking about possible directions for helping non-emacs-users get
going with our tooling.  Personally I think the biggest path to success
is likely to be seeing Guile support (starting with parenthetical Guile)
also be very strong in mainstream editors.  A lot has changed in the
programming editor world recently: LSP looks like a very promising
direction for this.  (Anyway, there's no decisionmaking yet in terms of
what we're doing, it just has come up quite a bit.)

Has anyone tried using an LSP-like environment and seeing if they can
get something approximating the comfort that Guile and Geiser users in
emacs have, I wonder?  I have seen there are a couple of guile LSP
packages but I have not personally tried them.

 - Christine

Re: The e(macs)lephant in the room and the Guix Bang

[Nathan Dehnel]

Which packages are those? I' ve only seen scheme-lsp-server, which
isn't merged yet


On Wed, Sep 27, 2023 at 1:44 PM Christine Lemmer-Webber
<cwebber@dustycloud.org> wrote:
>
> Nathan Dehnel <ncdehnel@gmail.com> writes:
>
> > ________________________________
> >
> >> Hi, for some reason emacs has become the elephant in the room of the
> >> discussion on contributing to guix.
> >>
> >> Regardless of one's opinion of emacs, I just want to add that this is
> >> itself strange.  I have contributed some (package definition) patches
> >> to guix, all without using emacs.
> >>
> >> I am not an emacs user, so emacs is not necessary for contributing to guix.
> >> For what it's worth, the emacs-motif package in Guix was my addition.
> >> I don't use it myself.
> >
> > I don't use emacs either (because it's so impenetrable), so I just use
> > kate instead, which isn't a great environment for me either. It has
> > rainbow parens, but it doesn't balance them, which is a hassle. I keep
> > using it though due to lack of time to browse through alternatives. I
> > heard about guile-studio, but it doesn't appear to have a dark mode,
> > and I imagine trying to add one would require a bunch of emacs-style
> > screwing around with it.
> >
> > https://archive.fosdem.org/2022/schedule/event/lispforeveryone/
> > This is the only setup for coding in lisp that has actually looked
> > attractive to me. (Coding in wisp with colored blocks that transpiles
> > to s-expressions) Though I haven't had the time (and probably
> > expertise) to set it up for myself.
>
> Happy to see this talk get some attention.  It does advocate a variety
> of possible approaches, one of them Wisp (and the wisp-mode colored
> block stuff is pretty awesome).
>
> If you like that approach and want to not have to do the
> parenthesis-balancing as much yourself, there's an interesting overlap
> between Wisp and parinfer, which automatically infers the parentheses
> from whitespace but keeps them in the actual source.  I have personally
> never tried using parinfer for serious tasks though.  It still requires
> an editor set up for those features.
>
> Since Spritely is also using Guile heavily, we have also spent a lot of
> time talking about possible directions for helping non-emacs-users get
> going with our tooling.  Personally I think the biggest path to success
> is likely to be seeing Guile support (starting with parenthetical Guile)
> also be very strong in mainstream editors.  A lot has changed in the
> programming editor world recently: LSP looks like a very promising
> direction for this.  (Anyway, there's no decisionmaking yet in terms of
> what we're doing, it just has come up quite a bit.)
>
> Has anyone tried using an LSP-like environment and seeing if they can
> get something approximating the comfort that Guile and Geiser users in
> emacs have, I wonder?  I have seen there are a couple of guile LSP
> packages but I have not personally tried them.
>
>  - Christine

Re: The e(macs)lephant in the room and the Guix Bang

[Munyoki Kilyungi]

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

Janneke Nieuwenhuizen <janneke@gnu.org> aliandika:


[...]


>>
>> Thank you for your opinion but it's just that: a subjective judgement
>> based on your own episodic experience.
>
> I'm sorry if my tone was too harsh, I now realise this is still
> triggering old pain.
>
> Why is it still OK to for people to keep spreading negative anecdotes
> about Emacs, and problematic to refute them or counter them with
> positive anecdotes?
>
> It's been me believing exactly such lies that scared me away from
> starting with Emacs for years, lost years in a way; something I deeply
> regret: this has to stop.
>

This I agree with.  I got into Emacs about a
decade ago.  And what helped me I guess, was that
no one in my environment used Emacs nor knew too
much about it.  And the internet wasn't as fast as
it is now.  So in a sense, I got into the
ecosystem "by faith", and it stuck.  However, this
is not the case today.  I'm running a SICP reading
book club community locally, and the feedback I'm
getting from people who are trying it out, is that
it's "very difficult to learn", and most of these
sentiments are from the internet.


-- 
(Life is like a pencil that will surely run out,
    but will leave the beautiful writing of life.)
(D4F09EB110177E03C28E2FE1F5BBAE1E0392253F
    (hkp://keys.openpgp.org))

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

Re: The e(macs)lephant in the room and the Guix Bang

[Ludovic Courtès]

Hi Andy,

Andy Tai <atai@atai.org> skribis:

> Regardless of one's opinion of emacs, I just want to add that this is
> itself strange.  I have contributed some (package definition) patches
> to guix, all without using emacs.
>
> I am not an emacs user, so emacs is not necessary for contributing to guix.
> For what it's worth, the emacs-motif package in Guix was my addition.
> I don't use it myself.

I agree.  It’s great that some of us are so passionate about Emacs (and
I’m certainly one of them), but I think we should make sure not to
spread the idea that one *has* to master Emacs to contribute to Guix.

Quite a few long-time contributors do not use Emacs; the tooling (‘guix
edit’, ‘guix refresh’, ‘guix style’) is also there to provide a good
experience whether or not one uses Emacs.

Ludo’.

Re: Enabling contribution through documentation

[Matt]

One elephant was already spoken about.  Your message points toward another: the Guile documentation.  The Guile documentation needs significant editing.

This is a problem because Guix is forever bound to Guile.  For every benefit Guix gains from Guile, it also suffers by inheriting its shortcomings.

 ---- On Mon, 25 Sep 2023 17:13:58 +0200  Samuel Christie via "Development of GNU Guix and the GNU System distribution."  wrote --- 

 > My recommendation consists of three parts:
 >   1. Write a clear tutorial
 >  ...
 > Such a tutorial would be helpful for onboarding new contributors 
 > because they don't have to know anything before getting started, 
 > just start at the beginning and follow the steps. The tutorial I 
 > was envisioning would work through the steps of writing a simple 
 > package, testing it, then submitting the patches.

I tried this and reached the conclusion that it's not possible without addressing shortcomings in the Guile documentation.  

Specifically, I tried to write a tutorial on packaging GNU Hello.  Really, if I were to look over the shoulder of someone packaging GNU Hello, what would it look like?  Why are they doing what they're doing in addition to what and how.  It's not obvious at all.  The Cookbook touches on GNU Hello.  However, it's hard to see how someone new to the details of Guix packaging, such as myself, is supposed to go from 'Section 2.1.1 A “Hello World” package' to actually packaging something in the wild.  All paths inevitably lead to the Guile manual.

Packaging is inherently complex.  It requires *at least* knowing something about Unix-like systems, build systems, and details of software development ranging from general programming concepts to specific applications to all the surrounding tooling.  

A common assumption is that "they don't have to know anything before getting started".  Unfortunately, this is not true.  Fortunately, we can often abstract this away by giving only the necessary information (not easy to do!) for whatever we're explaining and handing off details to another resource.  This is where the Guile documentation fails Guix.

For example, trying to understand (source (origin (method url-fetch) ... )), I looked at the Guix documentation.  The Guix documentation says,

#+begin_quote
'method' A monadic procedure that handles the given URI.

https://guix.gnu.org/en/manual/devel/en/html_node/origin-Reference.html
#+end_quote

I mistook 'method' to be a procedure that takes a URI.  But, no, it's a data type.

Several problems jump out to me:

1. The documentation assumes you understand how it's laid out.  Unless I missed it, there's no section explaining conventions used by the manual.  For example, https://www.gnu.org/software/emacs/manual/html_node/elisp/Format-of-Descriptions.html

2. There is not a clear way, even within Emacs, to figure out what 'method' is.  You *must* read the Guix manual.  This is the other elephant, the shortcomings of editors.

3. How, really, does someone who doesn't know what is meant by "Data Type" in this context supposed to get that information?  How are they to understand what's significant and what's not?  Trying to answer this inevitably leads to the Guile documentation.

 > Would any of you more 
 > experienced developers be willing to "shepherd" me through this 
 > process, and help set up the test environment, etc.?

I'd be happy to work alongside you.  

I'd also be happy to discuss the Guile docs in that mailing list.

Re: Enabling contribution through documentation

[Samuel Christie via Development of GNU Guix and the GNU System distribution.]

Hello Matt; sorry, I've been distracted and almost missed your 
reply a few weeks ago.

Matt <matt@excalamus.com> writes:

> [...] I tried to write a tutorial on packaging GNU Hello. 
> Really, if I were to look over the shoulder of someone packaging 
> GNU Hello, what would it look like? Why are they doing what 
> they're doing in addition to what and how. It's not obvious at 
> all. The Cookbook touches on GNU Hello.  However, it's hard to 
> see how someone new to the details of Guix packaging, such as 
> myself, is supposed to go from 'Section 2.1.1 A “Hello World” 
> package' to actually packaging something in the wild. All paths 
> inevitably lead to the Guile manual.

Yes, there are several layers of complexity at play: building the 
target package (not easy when all dependencies must also be 
packaged), and specifying the package in Guile.

I'm not that uncomfortable with scheme, though I don't think I 
fully understand g-expressions yet. It would be easier if I could 
get Geiser working for looking up symbols, but if the docs were 
better I suppose I wouldn't have to read the code.

I have successfully packaged some of my own things, trying to use 
guix for managing dev environments; it's not too bad for some 
things, but gets much more complicated when I have to step outside 
the comfort zone of directly using existing packages and build 
systems as inputs.  The other major thing I'm not yet familiar 
with is the patch submission and management process; not that I 
have anything patch-worthy yet, but it is a hurdle.

> Packaging is inherently complex. It requires *at least* knowing 
> something about Unix-like systems, build systems, and details of 
> software development ranging from general programming concepts 
> to specific applications to all the surrounding tooling.

I think it would be fair to assume minimal competence with using a 
shell. Everything else should be given as clear, exact steps to 
take ('mkdir package' not 'make a directory for your package'), so 
that even someone who knows nothing can perform the steps and 
produce the result.

> A common assumption is that "they don't have to know anything 
> before getting started".  Unfortunately, this is not true. 
> Fortunately, we can often abstract this away by giving only the 
> necessary information (not easy to do!) for whatever we're 
> explaining and handing off details to another resource. This is 
> where the Guile documentation fails Guix.

I think of tutorials as exposure rather than explanation, so the 
tutorial itself shouldn't need to explain much or rely on external 
resources. However, once the reader has finished the tutorial, 
they should be able to look up the steps they were exposed to. 
That is what the rest of the documentation is for, so I agree it 
should be improved. 

It's less clear how to "fix the documentation" than "write a 
tutorial" though. Maybe we can start with the tutorial, then 
improve the documentation for everything it used?

> I'd be happy to work alongside you.

Cool! I'm going to be pretty distracted this week, but we could 
start working on it asynchronously. Any thoughts on process? Maybe 
we could have a repo managed the same way Guix is, so I can learn 
that at the same time. (That is, emails for discussion and patches 
to the tutorial)
How hard would that be to get or set up? That could also be the 
'practice repo' people doing the tutorial would use for the final 
submission parts.

After that, I think the first step is picking an easy but 
non-trivial package to do. Maybe it should be one that's already 
been packaged... I went through a list of packages that I wished 
Guix had, and sadly none of them were easy enough for me to do. My 
first choice was INN (a Usenet server), but it has multiple 
service dependencies I wasn't sure how to handle. My other choices 
were apparently in Rust, which always has waaay too many deps. We 
could also do a better Hello tutorial. Thoughts?

Thanks,
-Samuel

Re: Enabling contribution through documentation

[Matt]

 ---- On Mon, 06 Nov 2023 23:43:07 +0100 Samuel Christie wrote ---
 >
 > Hello Matt; sorry, I've been distracted and almost missed your reply a few weeks ago.

Not a problem!  I've been distracted, too.  :)

 > Any thoughts on process? Maybe we could have a repo managed the same way Guix is, so I can learn that at the same time. (That is, emails for discussion and patches to the tutorial) How hard would that be to get or set up?

A central repo makes sense.  I'm open to exchanging patches over email rather than doing PRs.

If it's okay with the Guix mailing list, I would be happy to have that exchange here so that others may observe, comment, and contribute.

I've set up a repo here: https://codeberg.org/excalamus/guix-packaging-tutorial/src/branch/master/guix-packaging-tutorial.org

 > After that, I think the first step is picking an easy but non-trivial package to do. Maybe it should be one that's already been packaged... I went through a list of packages that I wished Guix had, and sadly none of them were easy enough for me to do. My first choice was INN (a Usenet server), but it has multiple service dependencies I wasn't sure how to handle. My other choices were apparently in Rust, which always has waaay too many deps. We could also do a better Hello tutorial. Thoughts?

I think we should do a more detailed Hello tutorial.  It is already referenced in the cookbook, it's non-trivial, and this is the use case it was created for.  The package definition already exists (gnu/packages/base.scm).

Some words on the document:

I'd like to see the finished tutorial included in the cookbook.  For that, it needs to be written in Texinfo.  It's currently in Org.  That's simply what I'm most familiar with and the format my notes were in.  Org exports to Texinfo and info.  While I'm sure the conversion is imprecise, sticking with Org allows me (at least) to write more easily.  It's familiar and generates an (approximate) info file.  My intent is to focus on explaining the topic and worry about the details of Texinfo later.

Otherwise, Org provides a practical benefit: it embeds "live" source blocks.  We can run all our shell calls from the document.  My hope is that this will keep the source code and shell call snippets accurate.

For anyone unfamiliar with Org, I've heavily annotated the document with explanations about how to navigate, edit, and transform it to other formats.  If that's too much, that's okay.  Just edit the text and we can take care of any markup syntax later.

I'm excited to work on this with you and anyone else.  I'm curious what your thoughts are :)