Simplify contribution by using user-friendly bug tracker and git interface

Simplify contribution by using user-friendly bug tracker and git interface

[Jan Wielkiewicz]

Hi,

I feel that emails are not the best system for interacting with the
project. The issue tracker is not helpful, it's hard to find anything
there, there are no tags/labels/milestones... Sending patches also
involves using a tedious and counterintuitive interface, scaring off
possible contributors.

I think a good solution would be hosting a forgejo instance [1] or
making a codeberg mirror [2] where users could send their pull
requests to. These have a friendly user interface with labels, a bug
tracker, etc. Well, unless the point of the email interface is to
gatekeep and scare off contributors...

[1] https://forgejo.org/
[2] https://codeberg.org/

--

Jan Wielkiewicz

Re: Simplify contribution by using user-friendly bug tracker and git interface

[Ekaitz Zarraga]

Hi Jan,

On 2024-08-31 00:35, Jan Wielkiewicz wrote:
> Hi,
> 
> I feel that emails are not the best system for interacting with the
> project. The issue tracker is not helpful, it's hard to find anything
> there, there are no tags/labels/milestones... Sending patches also
> involves using a tedious and counterintuitive interface, scaring off
> possible contributors.
> 
> I think a good solution would be hosting a forgejo instance [1] or
> making a codeberg mirror [2] where users could send their pull
> requests to. These have a friendly user interface with labels, a bug
> tracker, etc. Well, unless the point of the email interface is to
> gatekeep and scare off contributors...
> 
> [1] https://forgejo.org/
> [2] https://codeberg.org/

First, there are tags in the issue system:

https://issues.guix.gnu.org/search?query=tag%3Aeasy


The issue of friendliness has been brought up in the past, I suggest you 
to search in the mailing list for previous interactions in the topic.

In fact, I took part on a discussion about more general topics and I 
mentioned we should be more empathetic with other people's needs:
https://lists.gnu.org/archive/html/guix-devel/2023-09/msg00488.html


Tedious and counterintuitive are very loaded words, and not very 
objective either. The intuitiveness of things is based on the previous 
context people has. This is a GNU project, and the context for many GNU 
developers is autotools, mail based workflow and so on: maybe for GNU 
developers that's the most intuitive thing. Who should we please?

In my case, I find the Github-like PR based approach quite 
counterintuitive, but I got used to it before collaborating in Guix and 
now I don't dislike it. Starting using PRs for everything made me a 
little bit reluctant to try the email based approach. Surprisingly, it 
happens to be way easier than it looks, and it's actually quite cool.

You should give it a go: https://git-send-email.io/
(If you don't like or you can't use that, you can paste the patches in 
an email, or send them as attachments, which is as difficult as taking 
part in this mailing list.)

Once you use it for as long as you used other options, I'd love to have 
this conversation with you again (I'm not saying you'd change your mind, 
but the conversation would be fairer).

I will share some thought here that I know many people in the community 
doesn't agree with (and I'm kind of a 50-50 on it) but I think it's 
worth sharing:


So, it is true that making the access to things harder than the possible 
minimum is simply stupid. There's no discussion there.
That being said, it would be very sad if a seasoned software developer, 
who proved to be able to write code for a complex project like Guix, is 
not able, is discouraged to, or is afraid of sending the patches via 
email (but is ok opening an account, making a fork, making a pr and so on).

Putting it in a different way: not every contribution is worth 
attention. If people who want to contribute are not able to send an 
email, I don't think their potential contributions would be that 
interesting or worthy. The skills needed to be able to participate in 
Guix are quite advanced, I don't think the email is a burden for people 
that have them.
So let's say, yes: we do migrate to codeberg.org. And now what? Do you 
think the amount of contributions will skyrocket? Do you think the 
amount of meaningful contributions will be higher?

I know what I say here might smell like some intellectual classism or 
something, but if we slow down a little bit: implying that there's a lot 
of people wanting to contribute to Guix and they cannot overcome the 
burden of the tooling we use is a little bit condescending to them.

*People are smart*. They'll figure out. Our process could be better, 
specially the documentation for newcomers (which btw improved a lot 
recently, and mumi is great), for sure, but, in summary:

- I don't dislike the PR style
- I doubt if using a PR based approach would result in more and better 
contributions
- Just because something is more popular that the other thing it doesn't 
mean the latter is less intuitive
- Our process is not more complex, but it might be *new* for people
- If we provide GOOD documentation, people will understand it
- We have communication channels (that work) for the cases when people 
gets stuck


Those are my thoughts.

Re: Simplify contribution by using user-friendly bug tracker and git interface

[Jan Wielkiewicz]

Hello again,

On Sat, 31 Aug 2024 01:45:04 +0200
Ekaitz Zarraga <ekaitz@elenq.tech> wrote:

> Hi Jan,
> 
> 
> First, there are tags in the issue system:
> 
> https://issues.guix.gnu.org/search?query=tag%3Aeasy
> 

Missed this completely. Where is this documented?

> 
> The issue of friendliness has been brought up in the past, I suggest
> you to search in the mailing list for previous interactions in the
> topic.
> 
> In fact, I took part on a discussion about more general topics and I 
> mentioned we should be more empathetic with other people's needs:
> https://lists.gnu.org/archive/html/guix-devel/2023-09/msg00488.html
> 

Okay, will read this later.

> 
> Tedious and counterintuitive are very loaded words, and not very 
> objective either. The intuitiveness of things is based on the
> previous context people has. This is a GNU project, and the context
> for many GNU developers is autotools, mail based workflow and so on:
> maybe for GNU developers that's the most intuitive thing. Who should
> we please?
> 

I used these words because they convey my feelings related to the
current process. The discoverability of the system is low - every time
I send patches I need to reread documentation to then finding out my
email provider does not cooperate (failing SMTP, having to re-enable
email client support to proceed). So I probably need to change my email
provider in order to contribute to Guix smoothly.
I'm aware this is a GNU project, I'm a free software enthusiast and
GNU/Linux user myself, but I'm not an epic GNU hacker and you can't
expect all contributors (who simply want to update a package they use)
to be epic GNU hackers.

> In my case, I find the Github-like PR based approach quite 
> counterintuitive, but I got used to it before collaborating in Guix
> and now I don't dislike it. Starting using PRs for everything made me
> a little bit reluctant to try the email based approach. Surprisingly,
> it happens to be way easier than it looks, and it's actually quite
> cool.
> 

Wasn't easy to learn it at first, but running "git push origin" to
update a remote branch linked to a PR is pretty straight-forward.

> You should give it a go: https://git-send-email.io/
> (If you don't like or you can't use that, you can paste the patches
> in an email, or send them as attachments, which is as difficult as
> taking part in this mailing list.)

I have this installed and use it, can't send patches to Guix
otherwise...

> Once you use it for as long as you used other options, I'd love to
> have this conversation with you again (I'm not saying you'd change
> your mind, but the conversation would be fairer).
> 
> I will share some thought here that I know many people in the
> community doesn't agree with (and I'm kind of a 50-50 on it) but I
> think it's worth sharing:
> 
> 
> So, it is true that making the access to things harder than the
> possible minimum is simply stupid. There's no discussion there.
> That being said, it would be very sad if a seasoned software
> developer, who proved to be able to write code for a complex project
> like Guix, is not able, is discouraged to, or is afraid of sending
> the patches via email (but is ok opening an account, making a fork,
> making a pr and so on).

I'm apparently smart enough to install Guix as my daily driver distro,
learn Emacs with Paredit and hack together packages, and then an
email-based system filters me out...

> Putting it in a different way: not every contribution is worth 
> attention. If people who want to contribute are not able to send an 
> email, I don't think their potential contributions would be that 
> interesting or worthy. The skills needed to be able to participate in 
> Guix are quite advanced, I don't think the email is a burden for
> people that have them.
> So let's say, yes: we do migrate to codeberg.org. And now what? Do
> you think the amount of contributions will skyrocket? Do you think
> the amount of meaningful contributions will be higher?

Guix is not one thing - updating packages is not the same kind of task
as for example hacking on low-level system or package manager
functionality. I believe simplifying or making contributions more
similar to what other projects have would indeed help. One example
would be a free software game project I take part in. The original
founder of the game did not know git and maintained the game using
GitHub's online editor. Then when he stepped down, we moved the project
to Codeberg. In the very same project we also taught a literal Windows
user how to use git and command line which then enabled him to make
cool and meaningful contributions. And then I myself did several
contributions to Guix while barely knowing what I'm doing. So I'd be
careful with underestimating the power of inexperienced users.

> I know what I say here might smell like some intellectual classism or 
> something, but if we slow down a little bit: implying that there's a
> lot of people wanting to contribute to Guix and they cannot overcome
> the burden of the tooling we use is a little bit condescending to
> them.

I'm doing my best to overcome the burden of tooling, but in the very
same time I could just make my own channel with software I want updated
on Codeberg, instead of contributing them to upstream Guix.

> 
> *People are smart*. They'll figure out. Our process could be better, 
> specially the documentation for newcomers (which btw improved a lot 
> recently, and mumi is great), for sure, but, in summary:

Yeah, the current format of the document makes it easy to overlook
important things, for example there's no header called "Canceling Your
Issue", "Updating Your Patch Series", etc. Codeberg's user interface
makes these things discoverable under nice green/red buttons.

> 
> - I don't dislike the PR style
> - I doubt if using a PR based approach would result in more and
> better contributions
> - Just because something is more popular that the other thing it
> doesn't mean the latter is less intuitive
> - Our process is not more complex, but it might be *new* for people
> - If we provide GOOD documentation, people will understand it
> - We have communication channels (that work) for the cases when
> people gets stuck
> 
> 
> Those are my thoughts.

In the end you could argue that it's my own fault for using a
broken/incompetent email provider, but then it's the contribution
system of Guix that exposed this issue as opposed to alternative
systems like web GUIs that usually just work. Perhaps adding "your
email provider may be broken, try using a different one" and "make sure
to enable support for a standalone email clients in your email
settings" to the documentation would help? I spent more time than
needed in my life looking for solutions to fix email sending.


So yeah, that's pretty much it

--

Have a nice day
Jan Wielkiewicz

Re: Simplify contribution by using user-friendly bug tracker and git interface

[Ekaitz Zarraga]

Hi,

On 2024-08-31 14:05, Jan Wielkiewicz wrote:
> Hello again,
> 
> On Sat, 31 Aug 2024 01:45:04 +0200
> Ekaitz Zarraga <ekaitz@elenq.tech> wrote:
> 
>> Hi Jan,
>>
>>
>> First, there are tags in the issue system:
>>
>> https://issues.guix.gnu.org/search?query=tag%3Aeasy
>>
> 
> Missed this completely. Where is this documented?

In the bottom of the search box, you can show hints and then it suggests 
to use them.

>>
>> The issue of friendliness has been brought up in the past, I suggest
>> you to search in the mailing list for previous interactions in the
>> topic.
>>
>> In fact, I took part on a discussion about more general topics and I
>> mentioned we should be more empathetic with other people's needs:
>> https://lists.gnu.org/archive/html/guix-devel/2023-09/msg00488.html
>>
> 
> Okay, will read this later.
> 
>>
>> Tedious and counterintuitive are very loaded words, and not very
>> objective either. The intuitiveness of things is based on the
>> previous context people has. This is a GNU project, and the context
>> for many GNU developers is autotools, mail based workflow and so on:
>> maybe for GNU developers that's the most intuitive thing. Who should
>> we please?
>>
> 
> I used these words because they convey my feelings related to the
> current process. The discoverability of the system is low - every time
> I send patches I need to reread documentation to then finding out my
> email provider does not cooperate (failing SMTP, having to re-enable
> email client support to proceed). So I probably need to change my email
> provider in order to contribute to Guix smoothly.

This was literally my situation not that long ago. I'll explain more below.

> I'm aware this is a GNU project, I'm a free software enthusiast and
> GNU/Linux user myself, but I'm not an epic GNU hacker and you can't
> expect all contributors (who simply want to update a package they use)
> to be epic GNU hackers.

I agree with this. We are not expecting that either. That's why I was 
trying to push for a better documentation. I read your original message 
as coming from frustration and I don't think you were very empathetic 
when you wrote it.

>> In my case, I find the Github-like PR based approach quite
>> counterintuitive, but I got used to it before collaborating in Guix
>> and now I don't dislike it. Starting using PRs for everything made me
>> a little bit reluctant to try the email based approach. Surprisingly,
>> it happens to be way easier than it looks, and it's actually quite
>> cool.
>>
> 
> Wasn't easy to learn it at first, but running "git push origin" to
> update a remote branch linked to a PR is pretty straight-forward.

As simple as `git send-email HEAD~`. Our way is not more complex, it's 
just different.

>> You should give it a go: https://git-send-email.io/
>> (If you don't like or you can't use that, you can paste the patches
>> in an email, or send them as attachments, which is as difficult as
>> taking part in this mailing list.)
> 
> I have this installed and use it, can't send patches to Guix
> otherwise...

The link is a very good tutorial on how to use git-send-email. I like to 
share it because it made a huge difference to me. It's just a very short 
tutorial that explains very well the workflow in a practical way.

>> Once you use it for as long as you used other options, I'd love to
>> have this conversation with you again (I'm not saying you'd change
>> your mind, but the conversation would be fairer).
>>
>> I will share some thought here that I know many people in the
>> community doesn't agree with (and I'm kind of a 50-50 on it) but I
>> think it's worth sharing:
>>
>>
>> So, it is true that making the access to things harder than the
>> possible minimum is simply stupid. There's no discussion there.
>> That being said, it would be very sad if a seasoned software
>> developer, who proved to be able to write code for a complex project
>> like Guix, is not able, is discouraged to, or is afraid of sending
>> the patches via email (but is ok opening an account, making a fork,
>> making a pr and so on).
> 
> I'm apparently smart enough to install Guix as my daily driver distro,
> learn Emacs with Paredit and hack together packages, and then an
> email-based system filters me out...

This is a very interesting point and I encourage you to dive deeper on 
it. In my case I had pushed for a less emacs-centric approach in the 
docs, and I wrote some parts of the documentation for people that used 
other editors. I'm not smart enough to use emacs, and I gave up on it, 
but with the tutorial above I overcame my fears with the email based 
approach.

>> Putting it in a different way: not every contribution is worth
>> attention. If people who want to contribute are not able to send an
>> email, I don't think their potential contributions would be that
>> interesting or worthy. The skills needed to be able to participate in
>> Guix are quite advanced, I don't think the email is a burden for
>> people that have them.
>> So let's say, yes: we do migrate to codeberg.org. And now what? Do
>> you think the amount of contributions will skyrocket? Do you think
>> the amount of meaningful contributions will be higher?
> 
> Guix is not one thing - updating packages is not the same kind of task
> as for example hacking on low-level system or package manager
> functionality. I believe simplifying or making contributions more
> similar to what other projects have would indeed help. One example
> would be a free software game project I take part in. The original
> founder of the game did not know git and maintained the game using
> GitHub's online editor. Then when he stepped down, we moved the project
> to Codeberg. In the very same project we also taught a literal Windows
> user how to use git and command line which then enabled him to make
> cool and meaningful contributions. And then I myself did several
> contributions to Guix while barely knowing what I'm doing. So I'd be
> careful with underestimating the power of inexperienced users.

Yeah, I can agree with you, but we should as a whole make a cost-benefit 
analysis of this. Maybe making our current audience uncomfortable just 
for potential contributions that we don't know how many they can be is 
not a good idea. We should think about this deeply, and I opposed your 
email just because it was too categorical and I wanted to share the 
other side of the coin with you.

>> I know what I say here might smell like some intellectual classism or
>> something, but if we slow down a little bit: implying that there's a
>> lot of people wanting to contribute to Guix and they cannot overcome
>> the burden of the tooling we use is a little bit condescending to
>> them.
> 
> I'm doing my best to overcome the burden of tooling, but in the very
> same time I could just make my own channel with software I want updated
> on Codeberg, instead of contributing them to upstream Guix.
> 

This is fine, Guix's nature does not only allow this but also encourage 
it. In the moment you want to upstream your changes, you'll have my help 
in the IRC or in the Mailing List to guide you over the process.

>>
>> *People are smart*. They'll figure out. Our process could be better,
>> specially the documentation for newcomers (which btw improved a lot
>> recently, and mumi is great), for sure, but, in summary:
> 
> Yeah, the current format of the document makes it easy to overlook
> important things, for example there's no header called "Canceling Your
> Issue", "Updating Your Patch Series", etc. Codeberg's user interface
> makes these things discoverable under nice green/red buttons.
> 

This is way more constructive than your previous email and is very 
interesting. Suggestions like this help a lot to make a better 
documentation and become more welcoming and are not radical changes that 
require a huge agreement in the community. This we can do, right now.

About those specific issues, debbugs allows to close the issues by 
email. Guix documentation shows how to do it with mumi:

mumi compose --close

But I agree we could do better, and I suggest you to point out all the 
things you'd like to have and I commit myself to updating the 
documentation with them.

>>
>> - I don't dislike the PR style
>> - I doubt if using a PR based approach would result in more and
>> better contributions
>> - Just because something is more popular that the other thing it
>> doesn't mean the latter is less intuitive
>> - Our process is not more complex, but it might be *new* for people
>> - If we provide GOOD documentation, people will understand it
>> - We have communication channels (that work) for the cases when
>> people gets stuck
>>
>>
>> Those are my thoughts.
> 
> In the end you could argue that it's my own fault for using a
> broken/incompetent email provider, but then it's the contribution
> system of Guix that exposed this issue as opposed to alternative
> systems like web GUIs that usually just work. Perhaps adding "your
> email provider may be broken, try using a different one" and "make sure
> to enable support for a standalone email clients in your email
> settings" to the documentation would help? I spent more time than
> needed in my life looking for solutions to fix email sending.
> 

I have had SMTP problems with my previous email provider (protonmail) 
and I had to paste the patches in the body of the emails, or add them as 
attachments. It worked, but this was one of the main things that 
prevented me from trying git-send-email.

I am familiar with your issue, and it's really disappointing. I finally 
changed my provider and my quality of life was improved dramatically.

If you don't want to change your provider, which is perfectly ok, you 
are probably going to find some things a little bit more uncomfortable, 
but it's still possible.

When I had issues with all this, people in the Guix community helped me 
with the setup, corrected my patches, and encouraged me to be do it 
better next time. I wasn't scared off by people: nobody here wants that. 
What I got were some mentors that encouraged me to give the best of 
myself, not only in this project but also in others.

Please correct me if I'm wrong but from your previous message I read you 
were frustrated and maybe angry about it. From this message I read what 
you need is just some support. I think I can help. If you want, we can 
guide you to be more comfortable with the platform and document 
everything that made your life easier in order to make next person's 
approach to Guix smoother.

> So yeah, that's pretty much it

What do you think?

Should we start?

Re: Simplify contribution by using user-friendly bug tracker and git interface

[Jan Wielkiewicz]

On Sat, 31 Aug 2024 15:05:58 +0200
Ekaitz Zarraga <ekaitz@elenq.tech> wrote:

> Hi,
> 
> On 2024-08-31 14:05, Jan Wielkiewicz wrote:
> > Hello again,
> > 
> > On Sat, 31 Aug 2024 01:45:04 +0200
> > Ekaitz Zarraga <ekaitz@elenq.tech> wrote:
> > 
> >> Hi Jan,
> >>
> >>
> >> First, there are tags in the issue system:
> >>
> >> https://issues.guix.gnu.org/search?query=tag%3Aeasy
> >>
> > 
> > Missed this completely. Where is this documented?
> 
> In the bottom of the search box, you can show hints and then it
> suggests to use them.
> 
> >>
> >> The issue of friendliness has been brought up in the past, I
> >> suggest you to search in the mailing list for previous
> >> interactions in the topic.
> >>
> >> In fact, I took part on a discussion about more general topics and
> >> I mentioned we should be more empathetic with other people's needs:
> >> https://lists.gnu.org/archive/html/guix-devel/2023-09/msg00488.html
> >>
> > 
> > Okay, will read this later.
> > 
> >>
> >> Tedious and counterintuitive are very loaded words, and not very
> >> objective either. The intuitiveness of things is based on the
> >> previous context people has. This is a GNU project, and the context
> >> for many GNU developers is autotools, mail based workflow and so
> >> on: maybe for GNU developers that's the most intuitive thing. Who
> >> should we please?
> >>
> > 
> > I used these words because they convey my feelings related to the
> > current process. The discoverability of the system is low - every
> > time I send patches I need to reread documentation to then finding
> > out my email provider does not cooperate (failing SMTP, having to
> > re-enable email client support to proceed). So I probably need to
> > change my email provider in order to contribute to Guix smoothly.
> 
> This was literally my situation not that long ago. I'll explain more
> below.
> 
> > I'm aware this is a GNU project, I'm a free software enthusiast and
> > GNU/Linux user myself, but I'm not an epic GNU hacker and you can't
> > expect all contributors (who simply want to update a package they
> > use) to be epic GNU hackers.
> 
> I agree with this. We are not expecting that either. That's why I was 
> trying to push for a better documentation. I read your original
> message as coming from frustration and I don't think you were very
> empathetic when you wrote it.
> 
> >> In my case, I find the Github-like PR based approach quite
> >> counterintuitive, but I got used to it before collaborating in Guix
> >> and now I don't dislike it. Starting using PRs for everything made
> >> me a little bit reluctant to try the email based approach.
> >> Surprisingly, it happens to be way easier than it looks, and it's
> >> actually quite cool.
> >>
> > 
> > Wasn't easy to learn it at first, but running "git push origin" to
> > update a remote branch linked to a PR is pretty straight-forward.
> 
> As simple as `git send-email HEAD~`. Our way is not more complex,
> it's just different.
> 
> >> You should give it a go: https://git-send-email.io/
> >> (If you don't like or you can't use that, you can paste the patches
> >> in an email, or send them as attachments, which is as difficult as
> >> taking part in this mailing list.)
> > 
> > I have this installed and use it, can't send patches to Guix
> > otherwise...
> 
> The link is a very good tutorial on how to use git-send-email. I like
> to share it because it made a huge difference to me. It's just a very
> short tutorial that explains very well the workflow in a practical
> way.
> 
> >> Once you use it for as long as you used other options, I'd love to
> >> have this conversation with you again (I'm not saying you'd change
> >> your mind, but the conversation would be fairer).
> >>
> >> I will share some thought here that I know many people in the
> >> community doesn't agree with (and I'm kind of a 50-50 on it) but I
> >> think it's worth sharing:
> >>
> >>
> >> So, it is true that making the access to things harder than the
> >> possible minimum is simply stupid. There's no discussion there.
> >> That being said, it would be very sad if a seasoned software
> >> developer, who proved to be able to write code for a complex
> >> project like Guix, is not able, is discouraged to, or is afraid of
> >> sending the patches via email (but is ok opening an account,
> >> making a fork, making a pr and so on).
> > 
> > I'm apparently smart enough to install Guix as my daily driver
> > distro, learn Emacs with Paredit and hack together packages, and
> > then an email-based system filters me out...
> 
> This is a very interesting point and I encourage you to dive deeper
> on it. In my case I had pushed for a less emacs-centric approach in
> the docs, and I wrote some parts of the documentation for people that
> used other editors. I'm not smart enough to use emacs, and I gave up
> on it, but with the tutorial above I overcame my fears with the email
> based approach.
> 
> >> Putting it in a different way: not every contribution is worth
> >> attention. If people who want to contribute are not able to send an
> >> email, I don't think their potential contributions would be that
> >> interesting or worthy. The skills needed to be able to participate
> >> in Guix are quite advanced, I don't think the email is a burden for
> >> people that have them.
> >> So let's say, yes: we do migrate to codeberg.org. And now what? Do
> >> you think the amount of contributions will skyrocket? Do you think
> >> the amount of meaningful contributions will be higher?
> > 
> > Guix is not one thing - updating packages is not the same kind of
> > task as for example hacking on low-level system or package manager
> > functionality. I believe simplifying or making contributions more
> > similar to what other projects have would indeed help. One example
> > would be a free software game project I take part in. The original
> > founder of the game did not know git and maintained the game using
> > GitHub's online editor. Then when he stepped down, we moved the
> > project to Codeberg. In the very same project we also taught a
> > literal Windows user how to use git and command line which then
> > enabled him to make cool and meaningful contributions. And then I
> > myself did several contributions to Guix while barely knowing what
> > I'm doing. So I'd be careful with underestimating the power of
> > inexperienced users.
> 
> Yeah, I can agree with you, but we should as a whole make a
> cost-benefit analysis of this. Maybe making our current audience
> uncomfortable just for potential contributions that we don't know how
> many they can be is not a good idea. We should think about this
> deeply, and I opposed your email just because it was too categorical
> and I wanted to share the other side of the coin with you.
> 
> >> I know what I say here might smell like some intellectual classism
> >> or something, but if we slow down a little bit: implying that
> >> there's a lot of people wanting to contribute to Guix and they
> >> cannot overcome the burden of the tooling we use is a little bit
> >> condescending to them.
> > 
> > I'm doing my best to overcome the burden of tooling, but in the very
> > same time I could just make my own channel with software I want
> > updated on Codeberg, instead of contributing them to upstream Guix.
> > 
> 
> This is fine, Guix's nature does not only allow this but also
> encourage it. In the moment you want to upstream your changes, you'll
> have my help in the IRC or in the Mailing List to guide you over the
> process.
> 
> >>
> >> *People are smart*. They'll figure out. Our process could be
> >> better, specially the documentation for newcomers (which btw
> >> improved a lot recently, and mumi is great), for sure, but, in
> >> summary:
> > 
> > Yeah, the current format of the document makes it easy to overlook
> > important things, for example there's no header called "Canceling
> > Your Issue", "Updating Your Patch Series", etc. Codeberg's user
> > interface makes these things discoverable under nice green/red
> > buttons.
> > 
> 
> This is way more constructive than your previous email and is very 
> interesting. Suggestions like this help a lot to make a better 
> documentation and become more welcoming and are not radical changes
> that require a huge agreement in the community. This we can do, right
> now.
> 
> About those specific issues, debbugs allows to close the issues by 
> email. Guix documentation shows how to do it with mumi:
> 
> mumi compose --close
> 
> But I agree we could do better, and I suggest you to point out all
> the things you'd like to have and I commit myself to updating the 
> documentation with them.
> 
> >>
> >> - I don't dislike the PR style
> >> - I doubt if using a PR based approach would result in more and
> >> better contributions
> >> - Just because something is more popular that the other thing it
> >> doesn't mean the latter is less intuitive
> >> - Our process is not more complex, but it might be *new* for people
> >> - If we provide GOOD documentation, people will understand it
> >> - We have communication channels (that work) for the cases when
> >> people gets stuck
> >>
> >>
> >> Those are my thoughts.
> > 
> > In the end you could argue that it's my own fault for using a
> > broken/incompetent email provider, but then it's the contribution
> > system of Guix that exposed this issue as opposed to alternative
> > systems like web GUIs that usually just work. Perhaps adding "your
> > email provider may be broken, try using a different one" and "make
> > sure to enable support for a standalone email clients in your email
> > settings" to the documentation would help? I spent more time than
> > needed in my life looking for solutions to fix email sending.
> > 
> 
> I have had SMTP problems with my previous email provider (protonmail) 
> and I had to paste the patches in the body of the emails, or add them
> as attachments. It worked, but this was one of the main things that 
> prevented me from trying git-send-email.
> 
> I am familiar with your issue, and it's really disappointing. I
> finally changed my provider and my quality of life was improved
> dramatically.
> 
> If you don't want to change your provider, which is perfectly ok, you 
> are probably going to find some things a little bit more
> uncomfortable, but it's still possible.
> 
> When I had issues with all this, people in the Guix community helped
> me with the setup, corrected my patches, and encouraged me to be do
> it better next time. I wasn't scared off by people: nobody here wants
> that. What I got were some mentors that encouraged me to give the
> best of myself, not only in this project but also in others.
> 
> Please correct me if I'm wrong but from your previous message I read
> you were frustrated and maybe angry about it. From this message I
> read what you need is just some support. I think I can help. If you
> want, we can guide you to be more comfortable with the platform and
> document everything that made your life easier in order to make next
> person's approach to Guix smoother.
> 
> > So yeah, that's pretty much it
> 
> What do you think?
> 
> Should we start?
> 
> 

I apologize for my emotional and not constructive reply at first, I'll
try making more constructive replies next time.

As for help, now I'm good because I managed to send patches
correctly-ish. I'll probably end up looking for another email provider.
The issue that needs to be addressed however is the documentation, this
page to be precise: 
https://guix.gnu.org/en/manual/devel/en/html_node/Sending-a-Patch-Series.html
I propose turning it into numbered list of things a contributors needs
to do in order to successfully sending 1) a single patch or 2) a patch
series, with clearly visible headers. Then as I mentioned in the
previous reply, sections such as "Canceling Issue", "Adding More
Patches", "Updating/Changing the Patch Series" and "Troubleshooting"
should be added. This should make the guide easier to follow and more
friendly. The "Troubleshooting" section should cover typical
mistakes/errors and mention the issue we were having.
That way possible contributors will at least have a hint what could be
wrong with their setup, which should limit the level of frustration.
You could also add "make sure to ask on the IRC or mailing list first
if you can't resolve the issue".

That should do.

--

Jan Wielkiewicz

Re: Simplify contribution by using user-friendly bug tracker and git interface

[Suhail Singh]

Jan Wielkiewicz <tona_kosmicznego_smiecia@interia.pl> writes:

> The issue that needs to be addressed however is the documentation, this
> page to be precise: 
> https://guix.gnu.org/en/manual/devel/en/html_node/Sending-a-Patch-Series.html
> I propose turning it into numbered list of things a contributors needs
> to do in order to successfully sending 1) a single patch or 2) a patch
> series, with clearly visible headers. Then as I mentioned in the
> previous reply, sections such as "Canceling Issue", "Adding More
> Patches", "Updating/Changing the Patch Series" and "Troubleshooting"
> should be added. This should make the guide easier to follow and more
> friendly. The "Troubleshooting" section should cover typical
> mistakes/errors and mention the issue we were having.
> That way possible contributors will at least have a hint what could be
> wrong with their setup, which should limit the level of frustration.
> You could also add "make sure to ask on the IRC or mailing list first
> if you can't resolve the issue".

In case you weren't aware, the repository for the website is at
<https://git.savannah.gnu.org/cgit/guix/guix-artwork.git> and patches
can be sent to <mailto:guix-patches@gnu.org>.

Regards,
-- 
Suhail

Re: Simplify contribution by using user-friendly bug tracker and git interface

[Ekaitz Zarraga]

Hi

On 2024-08-31 15:44, Jan Wielkiewicz wrote:
> 
> I apologize for my emotional and not constructive reply at first, I'll
> try making more constructive replies next time.

No, don't worry about it. It is a normal reaction and I'm glad you 
started there because we were able to create something from it.

> As for help, now I'm good because I managed to send patches
> correctly-ish. I'll probably end up looking for another email provider.
> The issue that needs to be addressed however is the documentation, this
> page to be precise:
> https://guix.gnu.org/en/manual/devel/en/html_node/Sending-a-Patch-Series.html
> I propose turning it into numbered list of things a contributors needs
> to do in order to successfully sending 1) a single patch or 2) a patch
> series, with clearly visible headers. Then as I mentioned in the
> previous reply, sections such as "Canceling Issue", "Adding More
> Patches", "Updating/Changing the Patch Series" and "Troubleshooting"
> should be added. This should make the guide easier to follow and more
> friendly. The "Troubleshooting" section should cover typical
> mistakes/errors and mention the issue we were having.
> That way possible contributors will at least have a hint what could be
> wrong with their setup, which should limit the level of frustration.
> You could also add "make sure to ask on the IRC or mailing list first
> if you can't resolve the issue".
> 
> That should do.

Good, I'll get to it. I'll send you the patch for review :)

Thanks for the guidance, it will be helpful for newcomers. I'm sure.

Best,
Ekaitz

Re: Simplify contribution by using user-friendly bug tracker and git interface

[Steve George]

Hi Jan,

There are multiple ways to set-up for creating and dealing with patches. We've been organising 'monthly' online meetups to review patches. As part of that I spent some time writing a 'how-to' with bulleted instructions. It might be useful *in addition* to the manual:

https://libreplanet.org/wiki/Group:Guix/PatchReviewSessions2024

As I say, there are many ways to do this, this is one way and I tried to make it very 'direct'. 

Jgart also did a video on how to use a different interface Mumi, which was created for Guix:

https://youtu.be/8m8igXrKaqU

Hope this helps!

Steve / Futurile



On 31 Aug, Ekaitz Zarraga wrote:
> Hi
> 
> On 2024-08-31 15:44, Jan Wielkiewicz wrote:
> > 
> > I apologize for my emotional and not constructive reply at first, I'll
> > try making more constructive replies next time.
> 
> No, don't worry about it. It is a normal reaction and I'm glad you started
> there because we were able to create something from it.
> 
> > As for help, now I'm good because I managed to send patches
> > correctly-ish. I'll probably end up looking for another email provider.
> > The issue that needs to be addressed however is the documentation, this
> > page to be precise:
> > https://guix.gnu.org/en/manual/devel/en/html_node/Sending-a-Patch-Series.html
> > I propose turning it into numbered list of things a contributors needs
> > to do in order to successfully sending 1) a single patch or 2) a patch
> > series, with clearly visible headers. Then as I mentioned in the
> > previous reply, sections such as "Canceling Issue", "Adding More
> > Patches", "Updating/Changing the Patch Series" and "Troubleshooting"
> > should be added. This should make the guide easier to follow and more
> > friendly. The "Troubleshooting" section should cover typical
> > mistakes/errors and mention the issue we were having.
> > That way possible contributors will at least have a hint what could be
> > wrong with their setup, which should limit the level of frustration.
> > You could also add "make sure to ask on the IRC or mailing list first
> > if you can't resolve the issue".
> > 
> > That should do.
> 
> Good, I'll get to it. I'll send you the patch for review :)
> 
> Thanks for the guidance, it will be helpful for newcomers. I'm sure.
> 
> Best,
> Ekaitz
> 
> 

Re: Simplify contribution by using user-friendly bug tracker and git interface

[Attila Lendvai]

> I'm apparently smart enough to install Guix as my daily driver distro,
> learn Emacs with Paredit and hack together packages, and then an
> email-based system filters me out...


i often feel that getting some of my (non-controversial) contributions merged is an equivalent effort compared to creating the contribution itself. that should bother any reasonable engineer.

and if someone feels the urge to dismiss it as just another inexperienced guix user, i already have non-trivial fixes in shepherd, and i'm coding for 30+ years, and most of it in opensource contexts, just not the GNU flavour.

and yet, i still remember the effort it took to send my first few patches to guix, and it's still a source of frustration even now that i already learned the necessary incantations. a lot of it feels like jumping through hoops.

such things always serve as "elaborate filters"; that part is inevitable. the only question is what gets filtered out and what gets through. and what gets filtered out here is mostly unobservable, while it has the power to make or break a project.

i'm writing this with two minds: as a very enthusiastic user, and as a reluctant contributor. the fact that this topic comes up repeatedly shows that i'm probably not alone with this split mind. the enthusiasm makes some of the frustraton observable (as opposed to silently walking away), which should be seen as a blessing here.

--
• attila lendvai
• PGP: 963F 5D5F 45C7 DFCD 0A39
--
“The most urgent necessity is, not that the State should teach, but that it should allow education. All monopolies are detestable, but the worst of all is the monopoly of education.”
	— Frédéric Bastiat (1801–1850), 'What Is Money?'