~petersanchez/wikimain

01cd15bb79bdf07215b4985acb57995451129d66 — Peter Sanchez 8 months ago 18df70e
Adding contributing docs
3 files changed, 273 insertions(+), 0 deletions(-)

A contributing.md
M git/email.md
M index.md
A contributing.md => contributing.md +225 -0
@@ 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!

M git/email.md => git/email.md +32 -0
@@ 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

M index.md => index.md +16 -0
@@ 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