@@ 0,0 1,225 @@
+---
+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?
+
+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!
@@ 12,6 12,38 @@ tutorial on using git send-email to send patches by email. Check it out here!
https://git-send-email.io
+To get setup quickly, read on (you should still refer back to the tutorial
+above! It's truly amazing and also a very fast read.)
+
+# For contributors
+
+You need to make sure that your git install is configured to be able to send
+email. To do this, you should edit your git config file, typically
+`~/.git/config`, to contain something like the following:
+
+ [user]
+ name = Your Name
+ email = you@example.org
+
+ [sendemail]
+ smtpserver = mail.example.org
+ smtpuser = you@example.org
+ smtpencryption = tls
+ smtpserverport = 587
+
+You can also set them from the command line. However this is usually more work
+to do it all at once than simply editing your config file. Still, if you want
+to do it this way, you can do:
+
+ git config --global user.email "you@example.org"
+ git config --global user.name "Your Name"
+ git config --global sendemail.smtpserver "mail.example.org"
+ ...
+
+If you don't set your password here, you will be prompted for it when
+submitting a patch. If you wish to set it, the setting name is `smtppass`. For
+more info on git config options, see `git help config`.
+
# For maintainers
## Tell people how to contribute
@@ 65,6 65,22 @@ companies, we also understand that there are collaborators who want to
contribute to some of our open source projects. Please bear with us while we
work out all the kinks.
+# Contributing
+
+If you want to know how to contribute to open source projects hosted on our
+platform, read the [contributing documentation](contributing.md).
+
+Once you've read that and you happen to find typos, errors, or just want to
+improve this wiki, you can follow the steps in the contributing documentation
+above. You can clone the repo here:
+https://git.code.netlandish.com/~petersanchez/wikimain
+
+Contribute any changes to `~netlandish/public-inbox@lists.code.netlandish.com`
+
+Here's some helper commands to save these settings in your clone:
+
+ git config sendemail.to "~netlandish/public-inbox@lists.code.netlandish.com"
+ git config format.subjectPrefix "PATCH wikimain"
## Status