~petersanchez/wikimain

ref: 1799b369c2fdd92d156171d754c7db95e705b62d wikimain/contributing.md -rw-r--r-- 8.5 KiB
1799b369Peter Sanchez Updating links to contributing doc 7 months ago

#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, Git, and Mercurial 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 = "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 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:

#Why?

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

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.

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