---
title: Contributing on code.netlandish.com
---

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][linux], [Git][], and
[Mercurial][hg] projects then it's good enough for us and our tiny ones.

[linux]: https://www.kernel.org/doc/html/latest/process/submitting-patches.html
[git]: https://git-scm.com/docs/SubmittingPatches
[hg]: https://www.mercurial-scm.org/wiki/ContributingChanges

## 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][etiquette]
1. [Mailing list documentation][lists]

[lists]: https://man.code.netlandish.com/lists/
[etiquette]: https://man.code.netlandish.com/lists/etiquette.md

# 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
1. Do your work
1. Commit your changes
1. 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][hgemail].

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][etdhgrepo], [list][etdlist])

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

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

    [patchbomb]
    flagtemplate = "email-test-drive"

    [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][hgemail] for more detail on
how to submit patches using `hg email`, process feedback, update patches, etc.

[hgemail]: https://man.code.netlandish.com/hg/email.md
[etdhgrepo]: https://hg.code.netlandish.com/~netlandish/email-test-drive
[etdlist]: https://lists.code.netlandish.com/~netlandish/email-test-drive

## Git repositories

To start, please read our [Git email overview][gitemail] 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][etdgitrepo], [list][etdlist])

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][gitemail] and tutorial for more
detail on how to submit patches using `git send-email`, process feedback,
update patches, etc.

[gitemail]: https://man.code.netlandish.com/git/email.md
[etdgitrepo]: https://git.code.netlandish.com/~netlandish/email-test-drive

## 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][nlpinbox]:
  `~netlandish/public-inbox@lists.code.netlandish.com`
- [Peter's public-inbox][pspinbox]:
  `~petersanchez/public-inbox@lists.code.netlandish.com`

[nlpinbox]: https://lists.code.netlandish.com/~netlandish/public-inbox
[pspinbox]: https://lists.code.netlandish.com/~petersanchez/public-inbox

# Why?

The main reason is BitBucket deciding [end support for Mercurial][bbhg]. 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*. 

[bbhg]: https://bitbucket.org/blog/sunsetting-mercurial-support-in-bitbucket

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

For an interesting example of contributing to a new repo on an "accounts
required" service versus email based service, 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

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

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][ghdis]. 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.

[ghdis]: https://github.blog/2020-05-06-new-from-satellite-2020-github-codespaces-github-discussions-securing-code-in-private-repositories-and-more/#discussions

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