First off, thank you for wanting to know more about contributing to our open source projects and we really hope that do contribute. To help you on your way, here's some details.

We use mailing lists and email to manage community collaboration with our open source projects. This may feel odd if you're used to the fork, clone, work, submit pull request cycle but we think once you get the hang of it, you'll see that this is a very fast way to contribute with very little blockers.

If it's good enough for the massive Linux kernel, Git, Mercurial, PostgreSQL, and OpenBSD projects then it's good enough for us and our tiny ones.

#Before you contribute

There are some common sense things that you should know about collaborating via email and mailing lists. You must read the etiquette document below. If you're interested in how the mailing lists work on our platform, read the documentation as well.

1. Mailing list etiquette
2. Mailing list documentation

#How to contribute?

It's pretty straight forward to contribute to projects using this workflow. It's a matter of simply:

1. Clone the repository
2. Do your work
3. Commit your changes
4. Use hg email or git send-email to submit your changes

The best parts of this workflow are:

• No need to fork the repository, which means...
• No need to create an account on the hosting platform

Now before you submit your patches you should make sure you have your Mercurial or Git setup configured correctly. This ensures that it's able to send email, you know who the patch is being sent to, etc.

Let's go over each one individually.

#Mercurial repositories

Most (all?) of our open source repositories are Mercurial repo's, so we'll cover Mercurial first.

To start, please read our Mercurial email overview.

The overview will give you the steps to setup your Mercurial install to send email. The overview does briefly cover setting options specifically for the cloned repo you want to contribute to but now we'll dive a bit deeper into that.

In the interest of making this fast and easy for you, here's an example of how to configure a specific repo for it's own specific submission destination. In this case, a test mailing list and project on our platform named email-test-drive(repo, list)

Edit the .hg/hgrc file in your cloned repo with the following:

[email]
to = ~netlandish/email-test-drive@lists.code.netlandish.com

[patchbomb]
flagtemplate = {separate(' ', 'email-test-drive', flags)}

[diff]
git = 1

Save the file. And you're done. You just told Mercurial that when you use hg email while in the current repository to:

• Submit patches to the ~netlandish/email-test-drive@lists.code.netlandish.com mailing list.
• Configure the subject to start with [PATCH email-test-drive]
• To use git style diff formatting (but you knew that because you read the overview above)

Just like that, you're ready to contribute to our projects with Mercurial.

To submit your patch(es) to the mailing list you simply run:

hg email -o

Please refer to the Mercurial overview document for more detail on how to submit patches using hg email, process feedback, update patches, etc.

#Git repositories

To start, please read our Git email overview and also the awesome tutorial over at https://git-send-email.io

The overview and tutorial will give you the steps to setup your Git install to send email. The overview does briefly cover setting options specifically for the cloned repo you want to contribute you but now we'll dive a bit deeper into that.

In the interest of making this fast and easy for you, here's an example of how to configure a specific repo for it's own specific submission destination. In this case, a test mailing list and project on our platform named email-test-drive(repo, list)

Here are some commands to store the list settings for your repo clone:

git config sendemail.to "~netlandish/email-test-drive@lists.code.netlandish.com"

git config format.subjectPrefix "PATCH email-test-drive"

When looking at your repo's .git/config file, you should see the following:

[sendemail]
    to = ~netlandish/email-test-drive@lists.code.netlandish.com
[format]
    subjectPrefix = PATCH email-test-drive

You just told Git that when you use git send-email while in the current repository to:

• Submit patches to the ~netlandish/email-test-drive@lists.code.netlandish.com mailing list.
• Configure the subject to start with [PATCH email-test-drive]

Just like that, you're ready to contribute to our projects with Mercurial.

To submit your patch(es) to the mailing list you simply run:

git send-email HEAD^

Please refer to the Git overview document and tutorial for more detail on how to submit patches using git send-email, process feedback, update patches, etc.

#Testing

Feel free to submit your test patches for the email-test-drive repo's to the ~netlandish/email-test-drive@lists.code.netlandish.com mailing list. Once you submit your patches you should see your patch on the mailing list page. You can view the mailing list here:

https://lists.code.netlandish.com/~netlandish/email-test-drive

#FYI: Spam Filtering

If it's your first time submitting a patch to a code.netlandish.com mailing list, it may take up to 10 minutes for your patch to show in the mailing list page. This is because of spam filtering policies we have in place to help keep the noise out of our mailing lists.

Please be patient when you're first submitting. After your first submission you should no longer have any delays when submitting in the future.

#Where to contribute?

Each of our open source projects should have a README.md file that has a section titled Contributing. Check that section for the mailing list name to submit your patches to. However, it's a very good chance that it's one of the following 2:

• Netlandish public-inbox: ~netlandish/public-inbox@lists.code.netlandish.com
• Peter's public-inbox: ~petersanchez/public-inbox@lists.code.netlandish.com

#Why?

The main reason is BitBucket deciding end support for Mercurial. This left a very bad taste in our mouth and we've spent way too many hours trying to figure out what we should do next.

After much thought we agreed it's best to take back control of our data. Not just with our code hosting but also our email, calendars, contacts, etc. We never want to be in this situation again and honestly there is no reason we can't host our own stuff (we're pretty experienced sysadmins after all).

Now we can do things exactly how we want to.

#Why not migrate to Git(hub|lab), etc.

We strongly prefer Mercurial over Git. We have nothing against Git at all and we use it daily but for all of our own repo's we just prefer Mercurial. We don't see that changing anytime in the near future either.

No we're not going to engage in a flame war here. Git is great and you should always use the tools that make you more productive, happy, etc.

#But... What about forks and pull requests?

We realize for a certain subset of developers this method may seem old fashioned. It may even seem complicated. The truth is, it's actually not complicated at all. It's just different than what you're used to.

The Fork, clone, work, push, submit pull request workflow is an invention as of (roughly) 2008. The requirement to "fork" a repository is simply to force you to create an account on the service hosting the original code. That's fine but we feel that it's also a blocker for some people. Also it's tedious.

Using email is very fast. You can configure your Mercurial or Git install in about 60 seconds and never have to worry about it again. You can clone any public repo and submit your patches without being required to create accounts.

A very good break down of the email workflow was recently described in video and blog post by the creator of SourceHut himself, Drew Devault. You can read that article here:

https://drewdevault.com/2022/07/25/Code-review-with-aerc.html

For an interesting example of contributing to a new repo on an "accounts required" service versus email based service (also from Drew), see this:

https://spacepub.space/videos/watch/1619c000-7c44-4330-9177-29a0854bd759

If you'd like some more reading on the topic, Joe Nelson wrote an interesting post discussing the differences. See that here:

https://begriffs.com/posts/2018-06-05-mailing-list-vs-github.html

Martijn Braam recently wrote a nice post about how he much prefers the email workflow since switching about a year ago:

https://blog.brixit.nl/git-email-flow-versus-github-flow/

Also, Vincent Lee recently wrote an article titled "What's Wrong With GitHub Workflow?" that also goes into detail about the various issues with the typical "Github style" workflow.

https://www.vincent-lee.net/blog/2022-02-28-github/

While it may seem like the whole world follows the GitHub workflow, we'd wager that far more open source contributions happen via email than pull requests every day.

#Trusted collaboration

Software communities don’t just write code together. They brainstorm feature ideas, help new users get their bearings, and collaborate on best ways to use the software.

We couldn't have said it better ourselves. That's taken from the GitHub announcement of their new discussions feature. Of course to use that feature you have to be on their website.

Using mailing lists, you can use whatever your favorite email client is and interact whenever you'd like. Even offline, as long as you've got your email downloaded. Mailing lists are tried and trusted. Basically as old as email itself and still in use by practically every possible industry you can name.

Why? Because they work, they're convenient, there's basically no learning curve, and you can use whatever email client you're most comfortable with.

This is a huge advantage and helps keep the community more accessible and diverse.

#Conclusion

See, that isn't so bad. We hope this helps show you how to quickly contribute to any open source project currently hosted on our platform.

If you have any issues or questions, please send an email to the public inbox list (~netlandish/public-inbox@lists.code.netlandish.com) and we can assist you there.

Happy hacking!