~petersanchez/wikimain

d4aee7eb49bb0fdeb301e8c464cc0b3980ec2244 — Peter Sanchez 1 year, 4 months ago 4c3d520
Base docs for new setup
5 files changed, 416 insertions(+), 1 deletions(-)

A git/email.md
A git/index.md
A hg/email.md
A hg/index.md
M index.md
A git/email.md => git/email.md +74 -0
@@ 0,0 1,74 @@
---
title: Sending emails using Git and code.netlandish.com
---

**Note:** This document was taken from the [sourcehut documentation][srhtgit]. 
It's been adapted to fit our setup where appropriate.

[srhtgit]: https://man.sr.ht/git.sr.ht/send-email.md

This horrible wall of text has been replaced with a much better interactive
tutorial on using git send-email to send patches by email. Check it out here!

https://git-send-email.io

# For maintainers

## Tell people how to contribute

The first thing you need to do is help potential contributors figure out how to
contact you. The easiest way is to do nothing - git records your email with
every commit, so someone with a copy of your git repository can figure out how
to contact you. You'll probably want to make it a bit easier on them, though.

We recommend setting up a mailing list on
[lists.code.netlandish.com][lists-code] for this purpose. Once you do, you 
will get an email address for contributors to submit patches to. Write this 
into your docs! You will probably also want to link to the archives so that 
potential contributors can read other people's work to get a feel for your 
submission process.

## Reviewing patches

When a patch comes in, you should review it carefully. Read the code, apply the
patch locally and make sure it compiles, test the changes, and so on. During
this process you'll probably come up with feedback on the patch. Pull open that
email client and compose a reply to the patch author. When your client composes
the reply, don't be afraid to slice and dice the email you're replying to - trim
out the fat and only include specific lines that you want to comment on.

If you only have small comments here and there, feel free to make the changes
yourself, again utilizing [`git commit --amend`][git-commit-amend] and [`git
rebase`][git-rebase] to your heart's content. You may be wise to point out these
small errors when you thank the submitter for their patch, however, if you don't
want to see the same errors in future patches.

## Applying patches

In order to integrate the changes, you need to *apply* the patch. The tool for
this is [`git am`][git-am]. The difficult part here is going to be obtaining a
copy of the email to provide to `git am`. Some clients like [mutt][mutt] make
this easy (in mutt, you can use the `|` key to pipe an email directly to `git
am`), or tools like [offlineimap][offlineimap] can help (or a combination of the
two!). Most popular end-user clients do not provide this option. If you're in
this boat, the easiest way to get a raw email is to use the "raw" link on
lists.sr.ht, which is hidden away under the "details" button.

[git-am]: https://www.git-scm.com/docs/git-am
[git-commit-amend]: https://www.git-scm.com/docs/git-commit#Documentation/git-commit.txt---amend
[git-rebase]: https://www.git-scm.com/docs/git-rebase
[mutt]: http://www.mutt.org
[offlineimap]: http://www.offlineimap.org/

If you copy the link to the raw email from lists.code.netlandish.com, the 
command might look like this:

    curl -s https://lists.code.netlandish.com/... | git am

You can also just run `git am` alone and paste the patch into it, followed by
Ctrl+D. You can then make these commits available upstream by using [`git
push`][git-push] normally. Don't forget to send the contributor a thank you
email!

[git-push]: https://www.git-scm.com/docs/git-push
[lists-code]: https://lists.code.netlandish.com

A git/index.md => git/index.md +15 -0
@@ 0,0 1,15 @@
---
title: Git on code.netlandish.com
---

You can find all Git repositories on [git.code.netlandish.com][nlgit]. If
you have an account on our systems then you can also create your own repos for
hosting, etc.

Collaboration is handled via email. All patches, discussion, code review, etc. 
is done via email and our sourcehut platform.

Please read the [git email](/git/email.md) setup documentation for more 
details.

[nlgit]: https://git.code.netlandish.com

A hg/email.md => hg/email.md +253 -0
@@ 0,0 1,253 @@
---
title: Sending emails using Mercurial and code.netlandish.com
---

**Note:** This document was taken from the [sourcehut documentation][srhthg]. 
It's been adapted to fit our setup where appropriate.

[srhthg]: https://man.sr.ht/hg.sr.ht/email.md

sr.ht leverages mercurial's built-in collaboration tools for contributing to
projects hosted here. This guide will help you get started. If you run into any
trouble, please send an email to the [sr.ht-discuss][sr.ht-discuss] mailing list
for help.

[sr.ht-discuss]: https://lists.sr.ht/~sircmpwn/sr.ht-discuss

**Golden rule**: Do not copy-paste the output of `hg export` into your typical
mail client.

# For everyone

Before you dig too far into this guide, you should make sure that your email
client is configured to use plain text emails. By default, many email clients
compose emails with HTML, so you can use rich text formatting. Rich text is not
desirable for development-oriented email conversations, so you should disable
this feature and send your email as "plain text". Every email client is
different, you should research the options for your specific client. HTML emails
are rejected by all sr.ht services.

For real-world examples of how the discussions described in this document play
out, check out the [sr.ht-dev][sr.ht-dev] mailing list.

[sr.ht-dev]: https://lists.sr.ht/~sircmpwn/sr.ht-dev

# For contributors

## Preparing your changes

There's no need to "fork" the repository you want to contribute to -- simply use
[`hg clone`][hg-clone] to obtain a local copy of the mercurial repository and
[work normally][work-normally]. Be deliberate about your commits -- use
meaningful commit messages and take special care to commit your work in the form
of logically separate changes. When it comes time to review your work, your
commit history is an important tool for the reviewer and will be closely
examined.

[hg-clone]: https://www.mercurial-scm.org/doc/hg.1.html#clone
[work-normally]: https://book.mercurial-scm.org/read/

# Find out where to send your changes

This workflow is optional for projects hosted on sr.ht and each project will
have different requirements - review them carefully. To use this guide, you need
to find an email address to send your work to - this will often be a mailing
list on [lists.code.netlandish.com][lists-code]. You will also want to find 
people who can help review your changes - look for dedicated maintainers for 
the modules you're working on, or use [`hg annotate`][hg-annotate] to find 
people who have recently worked on similar code.

[hg-annotate]: https://www.mercurial-scm.org/doc/hg.1.html#annotate

# Configure hg email

When you've collected a list of email addresses to send your work to, we can use
[`hg email`][hg-email] to do the job. Its purpose is to convert your mercurial
commits into emails with [`hg export`][hg-export] and connect to your mail
server to deliver them with SMTP.

[hg-email]: https://www.mercurial-scm.org/doc/hg.1.html#email
[hg-export]: https://www.mercurial-scm.org/doc/hg.1.html#export

If you've never used hg email before, you will need to do some one-time setup to
enable the `email` command (which isn't accessible by default, but is available
in the `patchbomb` extension which ships with Mercurial), and introduce it to
your SMTP server. The connection details vary between mail providers, but you're
looking for information which is suitable for filling out these config fields in
[mercurial's configuration file][hgrc]:

[hgrc]: https://www.selenic.com/mercurial/hgrc.5.html

    [extensions]
    patchbomb =

    [smtp]
    host = mail.example.org
    port = 587
    tls = smtps
    username = you@example.org

You can also set your SMTP password as `smtp.password`. If you don't, you
will be prompted for it when it's needed.

## Send the patches along

When you've configured `hg email`, completed your work, and you're ready to send
your patches in, you can run `hg email -r [rev]`. The `[rev]` here is the same
as any other [revision number, identifier, or name][hg-rev]. The command will
prepare a patch for that commit and send it through your mail server.

A few things of note:

- `hg email -o [dest]` will prepare patches for any revision not already in the
  upstream `[dest]` repository (_i.e._ anything that would show up with `hg
  outgoing [dest]`). If you have configured the `default` destination (in the
  `[paths]` section), you can even just do `hg email -o`!
- `hg email -r tip` includes the last commit.
- You can use [revsets][hg-rev] to specify revision ranges, like, say, `hg
  email -r 3000:3005` for sending patches for revisions 3000 through 3005.
- Add the `--confirm` option to give you an extra step to catch mistakes.

[hg-rev]: https://www.mercurial-scm.org/doc/hg.1.html#specifying-revisions

Mercurial might prompt you for more information before sending the email. For
instance, it might ask you what your email address is. Although it uses what it
found in your config's `ui.username`, it wants to be sure. You can skip that
step by setting the `email.from` option in your config too:

    [email]
    from = Your Name <you@example.org>

If you're sending more than one patch at once, Mercurial will ask you to write
an introduction email to the patch series. In many cases, this is unnecessary,
so you can optionally disable this feature in your config (you can always pass
`--intro` to `hg email` if you want it back):

    [patchbomb]
    intro = never

## Handling feedback

You will likely receive replies to your email with feedback on your changes.
This is normal! Use tools like [`hg commit --amend`][hg-commit] and [`hg
rebase`][hg-rebase] (which, again, isn't accessible by default but is available
in the `rebase` extension which ships with Mercurial) to continue improving
your patch set and iterating on feedback. When you're ready to submit the next
version of your patches, use `hg email` normally, except:

- Add `--flag V2` to indicate that this is version 2 of your patch (or whatever
  number is appropriate).
- Optionally, add `--in-reply-to [msgid]`, where `[msgid]` is the message ID of
  the last email in the thread. On lists.sr.ht you can get this by clicking
  "details" on the email in question. If you can't find this, don't sweat it,
  it's no big deal.

[hg-commit]: https://www.mercurial-scm.org/doc/hg.1.html#commit
[hg-rebase]: https://www.mercurial-scm.org/doc/hg.1.html#rebase

## Pulling from upstream

As you continue to work, you may want to pull from the upstream, and you almost
certainly don't want to create a merge commit when you have work in progress or
unmerged changes in your history. To this end, you should generally use `hg pull
--rebase` (this option is only available once the `rebase` extension is
installed) to fetch the latest changes from upstream.

## Extra tips

Here are a few extra tricks you might find useful with `hg email`.

### Sending emails to the same address every time

If you send emails for a project to the same mailing list every time, you might
find it useful to set the default destination address. Edit the project's
repository config (`.hg/hgrc`) with:

    [email]
    to = patches@example.org

### Specifying a subproject for shared lists

Some projects have several repositories being discussed on a single mailing
list, and it's often helpful to specify the particular repository your patch
pertains to.

If you're just doing this once, add `--flags` to `hg email`. You can specify it
multiple times if you also need to specify `--flags V2`. For instance:

    hg email --flags 'example' -o

You can also specify this as the default for that mercurial repository by
editing its config (`.hg/hgrc`):

    [patchbomb]
    flagtemplate = {separate(' ', 'example', flags)}

This will build a default `--flags` starting with "`example`" and followed by
any other value passed through the command-line.

# For maintainers

## Tell people how to contribute

The first thing you need to do is help potential contributors figure out how to
contact you. The easiest way is to do nothing - mercurial records your email
with every commit, so someone with a copy of your mercurial repository can
figure out how to contact you. You'll probably want to make it a bit easier on
them, though.

We recommend setting up a mailing list on
[lists.code.netlandish.com][lists-code] for this purpose. Once you do, you 
will get an email address for contributors to submit patches to. Write this 
into your docs! You will probably also want to link to the archives so that 
potential contributors can read other people's work to get a feel for your 
submission process.

## Reviewing patches

When a patch comes in, you should review it carefully. Read the code, apply the
patch locally and make sure it compiles, test the changes, and so on. During
this process you'll probably come up with feedback on the patch. Pull open that
email client and compose a reply to the patch author. When your client composes
the reply, don't be afraid to slice and dice the email you're replying to - trim
out the fat and only include specific lines that you want to comment on.

If you only have small comments here and there, feel free to make the changes
yourself, again utilizing [`hg commit --amend`][hg-commit] and [`hg
rebase`][hg-rebase] to your heart's content. You may be wise to point out these
small errors when you thank the submitter for their patch, however, if you don't
want to see the same errors in future patches.

## Applying patches

In order to integrate the changes, you need to *apply* the patch. The tool for
this is [`hg import`][hg-import]. The difficult part here is going to be
obtaining a copy of the email to provide to `hg import`. Some clients like
[mutt][mutt] make this easy (in mutt, you can use the `|` key to pipe an email
directly to `hg import -`), or tools like [offlineimap][offlineimap] can help (or
a combination of the two!). Most popular end-user clients do not provide this
option. If you're in this boat, the easiest way to get a raw email is to use the
"raw" link on lists.sr.ht, which is hidden away under the "details" button.

[hg-import]: https://www.mercurial-scm.org/doc/hg.1.html#import
[mutt]: http://www.mutt.org
[offlineimap]: http://www.offlineimap.org/

If you copy the link to the raw email from lists.sr.ht, you can pass that
directly to `hg import` and it will download it for you:

    hg import https://lists.sr.ht/...

You can also just run `hg import -` paste the patch into it, followed by Ctrl+D.

If you use the [evolve](https://www.mercurial-scm.org/doc/evolution/)
extension, it is advised to also add the `--obsolete` option to `hg import`
command. This way, the contributor would see their changesets "evolved" when
pulling from the upstream repository.

Once applied, you can make these commits available upstream by using [`hg
push`][hg-push] normally. Don't forget to send the contributor a thank you
email!

[hg-push]: https://www.mercurial-scm.org/doc/hg.1.html#push
[lists-code]: https://lists.code.netlandish.com

A hg/index.md => hg/index.md +15 -0
@@ 0,0 1,15 @@
---
title: Mercurial on code.netlandish.com
---

You can find all Mercurial repositories on [hg.code.netlandish.com][nlhg]. If
you have an account on our systems then you can also create your own repos for
hosting, etc.

Collaboration is handled via email. All patches, discussion, code review, etc. 
is done via email and our sourcehut platform.

Please read the [mercurial email](/hg/email.md) setup documentation for more 
details.

[nlhg]: https://hg.code.netlandish.com

M index.md => index.md +59 -1
@@ 1,1 1,59 @@
Hello World.
---
title: Documentation Wiki's on code.netlandish.com
---

Welcome to the Netlandish software management systems.

Thanks to BitBucket [sunsetting support for Mercurial][bbhg] we've been forced
to find a new place to host our repositories, workflow, etc.

We decided that it's best that we're not in this situation again in the future
and that we should have our own systems to manage our code, CI/CD, ticket
tracker, etc.

We looked at several options and decided that [sourcehut][srht], aka sr.ht, 
was the best fit for us. It's a suite of very light weight applications 
designed to work totally independent of each other (well, for the most part.)

This allows us to slowly roll out new services as needed.

Sourcehut is also 100% open source and has a small, but active, community.
While we know that it's still primitive looking and rough around the
edges, it's already a very advanced system with advanced methods of
collaboration. Some may call it **hardcore** but we call it *comfortable*.

Here are the list of services we currently have running:

- [hg.code.netlandish.com][nlhg] - Mercurial Repo Hosting
- [git.code.netlandish.com][nlgit] - Git Repo Hosting
- [meta.code.netlandish.com][nlmeta] - Account Management
- [todo.code.netlandish.com][nltodo] - Issue Trackers
- [man.code.netlandish.com][nlman] - Wiki Hosting (Where you're reading this)


## Service Specific Docs

Here are some service specific docs:

- [Mercurial Docs](/hg)
- [Git Docs](/git)

**Note:** This platform is still very new, even to us, and the docs are very
limited. While this platform is mostly for the Netlandish staff and family
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.


## Status

Please refer to the [status page](/status.md) for any service issues or status
updates.

[bbhg]: https://bitbucket.org/blog/sunsetting-mercurial-support-in-bitbucket
[srht]: https://sourcehut.org
[nlhg]: https://hg.code.netlandish.com
[nlgit]: https://git.code.netlandish.com
[nlmeta]: https://meta.code.netlandish.com
[nltodo]: https://todo.code.netlandish.com
[nlman]: https://man.code.netlandish.com