~sircmpwn/sr.ht-docs

0270d908f8e3f11769035d3ccb41e761cad57e5b — Ludovic Chabant 2 years ago 1d17947
Add mercurial docs
4 files changed, 362 insertions(+), 0 deletions(-)

A hg.sr.ht/email.md
A hg.sr.ht/index.md
A hg.sr.ht/installation.md
M index.html
A hg.sr.ht/email.md => hg.sr.ht/email.md +238 -0
@@ 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

A hg.sr.ht/index.md => hg.sr.ht/index.md +80 -0
@@ 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).


A hg.sr.ht/installation.md => hg.sr.ht/installation.md +36 -0
@@ 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


M index.html => index.html +8 -0
@@ 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>