1. 19
  1. 6

    Nice article! Sorry to hear you found this to be a struggle. My key takeaways are:

    1. openring’s readme doesn’t actually tell you how to contribute [fixed]
    2. The page you land on when you finish registration should have a more obvious “how to contribute to projects on sourcehut” link. [fixed] Out of curiosity, did you click through the tutorials link? The tutorial that would have saved you isn’t there, but I’d like to know if it would have helped if it were.
    3. There should probably be a troubleshooting page for when you run into issues like these with git-send-email (this isn’t normal)
    1. 6

      The page you land on when you finish registration (…)

      As far as I understand sourcehut one doesn’t need an account to contribute. Maybe it would be beneficial to advertise it? (something like “you don’t need to register, just send e-mail to xyz”).

      1. 4

        Hm, good point. I’ll work on that.

      2. 2

        openring’s readme doesn’t actually tell you how to contribute [fixed]

        Looks good!

        did you click through the tutorials link?

        I didn’t see one. I think I clicked on man and didn’t see anything relevant, and then gave up and decided to email a patch.

        a troubleshooting page for when you run into issues like these with git-send-email

        Part of why I wrote the blog post was so my error messages would show up to other people searching ;)

        One thing I didn’t end up putting in the post was that there was actually another round of silliness: after I installed Net::SMTP::SSL and IO::Socket::SSL I didn’t notice that the error message I was getting had changed (I was getting sleepy) and I spent a while trying to figure out why they hadn’t installed properly (I thought maybe I’d selected the wrong value for local-vs-global?) Eventually I realized the error message was different and continued on.

        1. 2

          I didn’t see one. I think I clicked on man and didn’t see anything relevant, and then gave up and decided to email a patch.

          Normally once you complete account registration you land on man’s index page, which has a (hopefully) attractive green button taking you to tutorials. Did something else happen for you?

          1. 2

            I don’t remember, sorry!

            1. 4

              Okay, no worries. I appreciate your feedback!

      3. 5

        I consider git send-email to be unsuitable these days for several reasons, each of them contributing to why I consider it to be an anti-feature for my use cases at least.

        1. git send-email does not work out of the box on almost any setup. SMTP configuration is explicitly necessary. Often, the e-mail support is separate as well. (As an aside: The fact that SMTP configuration is required is a testament to how fundamentally broken e-mail is in general; you can’t just set up a *NIX box on defaults and expect it to send e-mail.)
        2. Making e-mail your only way to send a patch is a gamble if you’re using any of the big e-mail providers; gmail amd hotmail come to mind. They tend to have aggressive anti-spam policies that may silently drop e-mail for non-discernible reasons. I vividly remember trying to sort out issues sending e-mail for an IRC network. Maybe it also just lands in the spam folder, never to be actually acknowledged.
        3. I’m a happy ProtonMail user, personally. However, by design, it does not support sending e-mail via SMTP, instead requiring a separate program to do so. git-send-email.io recommends hydroxide, which seems to work with the free plan; ProtonMail is making their own, for-profit ProtonMail Bridge. There might be a murky legal battle there coming up, pushing contribution for ProtonMail users behind a paywall. You might argue that this is the ProtonMail users’ problem, but few are in the position to dictate people’s e-mail providers.
        4. This is the only contribution process that I’m aware of that mandates use of a specific program. I can contribute patches to, say, OpenBSD via e-mail just fine by sending them inline (admittedly, they don’t use Git). As a contributor, this seems like an excessive amount of work.

        Having said that, I still respect SirCmpwn’s choices and I’m sure they were made with due consideration.

        1. 4

          Agreed with everything here. I also put some patches in for a sr.ht project, and I didn’t have the same trouble as you did, but it was a fiddle to get it all to work out right. It’s not a big deal, except EVERY vcs hosted project has their own rules around how patches are accepted, and they all vary just enough that it’s generally a 10-60 minute pain EVERY TIME you want to do it, unless you are a regular contributor.

          This is why I think it would be great for a webpage form that accepts universal diffs & patches also be supported for sourcehut(sr.ht) and other VCS websites(github, gitlab, fossil, etc). I’ve never seen any of them support this however.

          Part of my job is evaluating new tech , so I’m always playing with X or Y, and when I find issues I used to work at sending patches, but now it’s generally a PITA, so at best I file an issue, depending on how much pain even that takes. If it’s not easy to contribute, it’s not remotely surprising that few do it.

          1. 5

            Sad this is a problem, glad that I get to hear about it. One thing to note is that setting up git-send-email once will generally get you 90% of the way there for most projects which accept email, though it can definitely be daunting upfront (I wrote a guide which helps a bit, feedback strongly desired).

            Another thing I want to do to help solve this is to show extra messages on git clone that succinctly describe what you need to do to upstream your work - things like automatically setting sendemail.to, format.subjectPrefix, and printing a short summary to your console when git clone completes.

            1. 3

              Another thing I want to do to help solve this is to show extra messages on git clone that succinctly describe what you need to do to upstream your work - things like automatically setting sendemail.to, format.subjectPrefix, and printing a short summary to your console when git clone completes.

              That would be very cool! I usually put this kind of info in README.

              Do you have a relevant Message-ID or link to git mailing list discussion about this subject?

              1. 3

                I haven’t pitched it to the git ML yet because I haven’t solved all of the unknowns I know of myself yet.

                1. 2

                  As far as I remember git will print remote output (GitHub/Gitlab use it when pushing to feature branches to print info on how to open PR/MR). Maybe the same thing can be reused for printing instructions on initial clone…

              2. 3

                I agree you are working on making git send email more user-friendly, and I think that’s great. But there will still be cases where people run into trouble(s). It doesn’t help that the git send email upstream code is perl, so even “binaries” for a given platform may not work out of the box. It also makes it impossible for people from tablets & phones to make contributions (git clients exist, but none of them support send-email that I’m aware of).

                I’m not saying it’s your problem to solve and I want to thank you for your work to make git send email more friendly.. something the git team could have taken on themselves, but haven’t for whatever reason.

                sourcehut, like github, etc support exactly 1 way to accept patches, and every system is different. I think this is bad and leads to less contributions overall.

                I think allowing git to auto-set some per-repo settings for patches is a good idea.

                I think about my teenage son, who can barely open a command line. He uses some open source software and has found some issues, but getting him set up to send documentation fix patches is generally way more trouble than he is willing to go through. Getting him to use git send-email is a non-starter. Now he is a young teenage boy, so maybe his documentation fixes would be too full of fart jokes to be actually useful.. ;P But if it was easy to contribute, maybe in a few years his contributions would actually be useful. But today as it stands, there is basically zero chance that will ever happen.

                1. 1

                  In my opinion, it’s more appropriate to teach people about the right tools than to spend time catering to iPad programmers.

            2. 3

              I gave up and decided to email a patch to the author. I ran git format-patch -1 HEAD to package up my most recent commit, and sent that as an attachment.

              Seems like that would work fine… On the postgresql mailing list, for instance, people send regular messages with their mail client and attach patches.

              Drew wrote back … saying that they only accept patches sent through the git email protocol

              Why the insistence that git itself do the emailing? Can’t the file generated by format-patch be applied on the receiving end with “git apply” or even by the standard unix patch utility? The “git send-email or die” sounds like a bit of pedantry, unless perhaps it makes it easier for the committer to attach the desired author metadata.

              1. 3

                The “git send-email or die” sounds like a bit of pedantry, unless perhaps it makes it easier for the committer to attach the desired author metadata.

                It makes it possible to review the patch inline. Even if git apply works with attachments it’s basically all-or-nothing. No way to comment on specific parts of the patch.

                1. 1

                  No way to comment on specific parts of the patch.

                  Couldn’t you reply to the email containing the patch, quoting sections of the code? For instance, here’s commentary on a recent random postgres patch: https://www.postgresql.org/message-id/20190602214257.GA17525%40telsasoft.com

                  Or am I misunderstanding what you mean by reviewing a patch inline?

                  1. 2

                    Yes, that’s what I mean. If the patch is sent inline one just hits reply and the patch is reviewed well… inline.

                    If the patch is attached as a file it needs to be copied to the response and then reviewed inline. Still doable… but extra work for no reason. Still this may be a good idea to include in e-mail clients that are specifically designed to handle patches (such as aerc).

              2. 2

                So, ok, I follow the docs at git-send-email.io, also helpfully written by this author (…)

                Maybe it would be also possible to built an interactive “git-send-email.io” script that can be run locally, would accept e-mail address and configure everything and then check it for the user.

                For example, Mozilla maintains a list of configuration values for various e-mail providers (see here). The protocol is also configurable (as one would call today “federated”).

                Sending an e-mail through that tool (that would call “git send-email”) would test the entire thing by sending an e-mail to some well known good ML (such as https://lists.sr.ht/~sircmpwn/email-test-drive).