From 01cd15bb79bdf07215b4985acb57995451129d66 Mon Sep 17 00:00:00 2001 From: Peter Sanchez Date: Thu, 23 Jul 2020 12:31:00 -0700 Subject: [PATCH] Adding contributing docs --- contributing.md | 225 ++++++++++++++++++++++++++++++++++++++++++++++++ git/email.md | 32 +++++++ index.md | 16 ++++ 3 files changed, 273 insertions(+) create mode 100644 contributing.md diff --git a/contributing.md b/contributing.md new file mode 100644 index 0000000..38ec3e8 --- /dev/null +++ b/contributing.md @@ -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! diff --git a/git/email.md b/git/email.md index 42c156f..facd08a 100644 --- a/git/email.md +++ b/git/email.md @@ -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 diff --git a/index.md b/index.md index 86d019d..785b64c 100644 --- a/index.md +++ b/index.md @@ -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 -- 2.43.0