Add mercurial docs

4 files changed, 362 insertions, 0 deletions

diff --git a/hg.sr.ht/email.md b/hg.sr.ht/email.md
new file mode 100644
index 0000000..9172f2c
--- /dev/null
+++ b/hg.sr.ht/email.md
@@ -0,0 +1,238 @@
+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
+
+Unsure if your setup is correct? Try sending the patch to sir@cmpwn.com for
+feedback first - make sure you mention in the email that you want feedback.
+
+# 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.sr.ht](/lists.sr.ht). 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`][amend] and [`hg
+rebase`][hg-rebase] 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` 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 git repository by editing its
+config (`.hg/hrc`):
+
+    [patchbomb]
+    flagtemplate = example {flags}
+
+The `{flags}` placeholder indicates where other `--flags` will go in the email
+subject (in thise case: after "`example`").
+
+# 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.sr.ht](/lists.sr.ht) 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.
+
+One 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
diff --git a/hg.sr.ht/index.md b/hg.sr.ht/index.md
new file mode 100644
index 0000000..15bd5b5
--- /dev/null
+++ b/hg.sr.ht/index.md
@@ -0,0 +1,80 @@
+[hg.sr.ht](https://hg.sr.ht) is a service for hosting mercurial repositories on
+sr.ht.
+
+**See also**:
+
+- [Installation guide](installation.md)
+
+**Important**: hg.sr.ht is a work in progress. As a consequence, URLs of
+specific files, commits, branches, etc in the repository viewer are **NOT**
+guaranteed to remain consistent forever. When we finish writing our new
+repository viewer, these will change.
+
+# New to mercurial?
+
+Learning how to use mercurial in general is out of the scope of our
+documentation. Here are some good resources:
+
+- [Mercurial: The Definitive Guide](https://book.mercurial-scm.org/read/)
+- [Learning Mercurial in Workflows](https://www.mercurial-scm.org/guide)
+- [Mercurial man page](https://www.mercurial-scm.org/doc/hg.1.html)
+
+We do have some general resources for helping you use mercurial with sr.ht:
+
+- [Using hg-email for sending and retrieving patches on sr.ht](email.md)
+
+# hg.sr.ht manual
+
+The following sections document various features of hg.sr.ht.
+
+## Repository creation
+
+Creating new repositories is done on the [create page](https://hg.sr.ht/create),
+which you can access from any page via the navigation on the top right. You can
+also create a new repository by pushing to one that does not yet exist, and
+clicking the link which is printed in the `hg push` output to complete the
+creation process.
+
+The *name* and *description* fields are used to describe your repository to the
+public. The *visibility* field will change how your repository is shown on the
+website. Public repositories are visible on your profile, to anonymous users,
+and on third-party search engines. Unlisted repositories are visible to anyone
+who has the link, but are not shown in your profile or in search results.
+Private repositories are only visible to you and other logged-in users who you
+explicitly [grant access to](#access).
+
+## Settings
+
+Each repository's settings may be accessed via the settings link on the
+repository's detail page.
+
+### Info
+
+You can change the repository's visibility and description on this page. Click
+"Rename?" if you wish to rename your repository. Renaming your repository sets
+up a redirect from the previous name to the new.
+
+### Access
+
+The access page allows you to grant other users read or write access to your
+repository. Users with read access will be able to clone and view private
+repositories on the web, and users with write access will be able to push new
+to your repository. Users with write access will not be able to edit your
+repository's settings.
+
+### Delete
+
+You can delete your repository from this page. This operation cannot be undone.
+This does not delete any other resources that may be associated with this
+project, such as a ticket tracker on todo.sr.ht or build history on
+builds.sr.ht.
+
+## Profile
+
+Your public profile is available at hg.sr.ht/~username. Here any public
+repositories on your account are listed and searchable, but unlisted and private
+repositories are hidden unless you're logged in.
+
+The information displayed on your profile page is sourced from your [meta.sr.ht
+profile](/meta.sr.ht#profile).
+
diff --git a/hg.sr.ht/installation.md b/hg.sr.ht/installation.md
new file mode 100644
index 0000000..23a58eb
--- /dev/null
+++ b/hg.sr.ht/installation.md
@@ -0,0 +1,36 @@
+hg.sr.ht is the hg repository hosting service for the sr.ht network.
+
+# Installation
+
+hg.sr.ht is a standard sr.ht web service and can be installed through the
+[standard procedure](/installation.md). However, there are several additional
+steps required.
+
+## Repository storage
+
+You will need to set up a directory for repositories to be stored in - we
+suggest `/var/lib/hg/`. Also configure a `hg` user and assign ownership over
+`/var/lib/hg/` to this user. The hg.sr.ht package will automatically prepare
+these for you. If you do not use the package, you must create the user yourself
+and ensure that the hg.sr.ht web application runs as this user.
+
+## SSH dispatch
+
+At the moment, hg.sr.ht uses git.sr.ht's SSH dispatcher, which you need to setup
+as the system-wide SSH authorization hook. See the [git.sr.ht
+documentation](../git.sr.ht/installation.md#ssh-dispatch) for more information.
+
+Once this is done, you need to make the hg.sr.ht authorization hook be part of
+the SSH dispatching, via the `hgsrht-keys` and `hgsrht-shell` scripts. See the
+`[dispatch]` section of you hg.sr.ht configuration for details on how this
+works.
+
+Authorization logs are written to `hg-srht-shell`.
+
+## Cronjobs
+
+You must also configure `hgsrht-periodic` to run periodically with your
+favorite cron daemon. We recommend the following crontab:
+
+    */20 * * * * hgsrht-periodic
+
diff --git a/index.html b/index.html
index 3d299ed..e18ad05 100644
--- a/index.html
+++ b/index.html
@@ -135,4 +135,12 @@ dt {
       <a href="/meta.sr.ht/api.md">API Reference</a>
     </dd>
   </div>
+  <div class="col-md-6">
+    <dt>
+      <strong>hg.sr.ht</strong>: mercurial hosting
+    </dt>
+    <dd>
+      <a href="/hg.sr.ht">User Manual</a>
+    </dd>
+  </div>
 </dl>