~sircmpwn/sr.ht-docs

4f455f128fac94132798af12e4e2aad01d344278 — Drew DeVault 3 years ago c34ee17
Improve the onboarding flow for new users
A index.html => index.html +138 -0
@@ 0,0 1,138 @@
<p>
  <strong>Welcome to sr.ht!</strong> You can access each of the main services
  from the links in the navigation at the top of the site. You're currently on
  man.sr.ht, which hosts the sr.ht user manual and provides wikis for projects
  hosted on sr.ht.
</p>
<style>
dt {
  font-weight: normal;
}
.event-row .col-md-6:first-child {
  padding-right: 0.25rem;
}
.event-row .col-md-6:last-child {
  padding-left: 0.25rem;
}
</style>
<div class="row event-row">
  <div class="col-md-6 event-list">
    <div class="event">
      <h3>Start here!</h3>
      <p>
        New here? We have some great tutorials to introduce you to the site.
      </p>
      <a href="tutorials" class="btn btn-success btn-block">
        Read the tutorials
        <span class="icon icon-caret-right">
          <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 192 512"><path d="M0 384.662V127.338c0-17.818 21.543-26.741 34.142-14.142l128.662 128.662c7.81 7.81 7.81 20.474 0 28.284L34.142 398.804C21.543 411.404 0 402.48 0 384.662z"/></svg>
        </span>
      </a>
    </div>
    <div class="event">
      <h3>General documentation</h3>
      <p>
        Information on billing, terms of service, privacy policy, and so on.
      </p>
      <a href="sr.ht" class="btn btn-default btn-block">
        Read boring stuff
        <span class="icon icon-caret-right">
          <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 192 512"><path d="M0 384.662V127.338c0-17.818 21.543-26.741 34.142-14.142l128.662 128.662c7.81 7.81 7.81 20.474 0 28.284L34.142 398.804C21.543 411.404 0 402.48 0 384.662z"/></svg>
        </span>
      </a>
    </div>
  </div>
  <div class="col-md-6 event-list">
    <div class="event">
      <h3>Getting help</h3>
      <p>
        Need support? There are several resources available to you.
      </p>
      <a href="support.md" class="btn btn-default btn-block">
        Support resources
        <span class="icon icon-caret-right">
          <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 192 512"><path d="M0 384.662V127.338c0-17.818 21.543-26.741 34.142-14.142l128.662 128.662c7.81 7.81 7.81 20.474 0 28.284L34.142 398.804C21.543 411.404 0 402.48 0 384.662z"/></svg>
        </span>
      </a>
    </div>
    <div class="event">
      <h3>Developers & admins</h3>
      <p>
        Hacking on or deploying sr.ht yourself? Resources here.
      </p>
      <a href="installation.md" class="btn btn-default btn-block">
        Getting started
        <span class="icon icon-caret-right">
          <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 192 512"><path d="M0 384.662V127.338c0-17.818 21.543-26.741 34.142-14.142l128.662 128.662c7.81 7.81 7.81 20.474 0 28.284L34.142 398.804C21.543 411.404 0 402.48 0 384.662z"/></svg>
        </span>
      </a>
    </div>
  </div>
</div>
<div class="alert alert-warning">
  <strong>Notice</strong>: sr.ht documentation is a work in progress, and is
  incomplete in many places.
</div>
<h3>Service Documentation</h3>
<dl class="row">
  <div class="col-md-6">
    <dt>
      <strong>git.sr.ht</strong>: git hosting
    </dt>
    <dd>
      <a href="/git.sr.ht">User Manual</a>
    </dd>
  </div>
  <div class="col-md-6">
    <dt>
      <strong>builds.sr.ht</strong>: build service
    </dt>
    <dd>
      <a href="/builds.sr.ht">User Manual</a>
      &mdash;
      <a href="/builds.sr.ht/api.md">API Reference</a>
    </dd>
  </div>
  <div class="col-md-6">
    <dt>
      <strong>todo.sr.ht</strong>: bug tracking
    </dt>
    <dd>
      <a href="/todo.sr.ht">User Manual</a>
    </dd>
  </div>
  <div class="col-md-6">
    <dt>
      <strong>lists.sr.ht</strong>: mailing lists
    </dt>
    <dd>
      <a href="/lists.sr.ht">User Manual</a>
    </dd>
  </div>
  <div class="col-md-6">
    <dt>
      <strong>man.sr.ht</strong>: manual &amp; wikis
    </dt>
    <dd>
      <a href="/man.sr.ht">User Manual</a>
    </dd>
  </div>
  <div class="col-md-6">
    <dt>
      <strong>dispatch.sr.ht</strong>: task automation
    </dt>
    <dd>
      <a href="/dispatch.sr.ht">User Manual</a>
    </dd>
  </div>
  <div class="col-md-6">
    <dt>
      <strong>meta.sr.ht</strong>: account &amp; security
    </dt>
    <dd>
      <a href="/meta.sr.ht">User Manual</a>
      &mdash;
      <a href="/meta.sr.ht/api.md">API Reference</a>
    </dd>
  </div>
</dl>

D index.md => index.md +0 -100
@@ 1,100 0,0 @@
Welcome to sr.ht, a network for helping hackers maintain their projects!
You can access each of our main tools from the navigation above. You're
currently on man.sr.ht, which is the documentation hub for sr.ht and many of the
projects hosted here.

If you're new here, you'll probably want to tweak your account settings at
[meta.sr.ht](https://meta.sr.ht/profile) and perhaps create some git
repositories on [git.sr.ht](https://git.sr.ht). You probably also want to
subscribe to the [sr.ht-announce](https://lists.sr.ht/~sircmpwn/sr.ht-announce)
mailing list, a low-volume list of new features and announcements. Join [#sr.ht
on irc.freenode.net](http://webchat.freenode.net/?channels=%23sr.ht&uio=d4) for
real-time chat support and sr.ht-related discussion.

For general help on using, reporting bugs, installing, hacking on, or
contributing to sr.ht, see the [General Documentation](/sr.ht).

**NOTICE**: This documentation is a work in progress, and is incomplete in many
places.

**NOTICE**: While sr.ht is in the alpha phase, all features are free. However,
once sr.ht enters the beta phase, a fee will be asked of all users to ensure the
site is sustainable without external investment. [Details here][fees].

[fees]: https://lists.sr.ht/~sircmpwn/sr.ht-discuss/%3C20180718225440.GA4503%40homura.localdomain%3E

---

<dl class="row" style="margin-bottom: 0">
  <div class="col-md-6">
    <dt>sr.ht</dt>
    <dd>
      <a href="/sr.ht">General Documentation</a>
    </dd>
  </div>
  <div class="col-md-6">
    <dt>
        <a href="https://builds.sr.ht">builds.sr.ht</a>
        build service
    </dt>
    <dd>
      <a href="/builds.sr.ht">User Manual</a>
      &mdash;
      <a href="/builds.sr.ht/api.md">API Reference</a>
    </dd>
  </div>
  <div class="col-md-6">
    <dt>
        <a href="https://git.sr.ht">git.sr.ht</a>
        git hosting
    </dt>
    <dd>
      <a href="/git.sr.ht">User Manual</a>
    </dd>
  </div>
  <div class="col-md-6">
    <dt>
        <a href="https://lists.sr.ht">lists.sr.ht</a>
        mailing lists
    </dt>
    <dd>
      <a href="/lists.sr.ht">User Manual</a>
    </dd>
  </div>
  <div class="col-md-6">
    <dt>
        <a href="https://todo.sr.ht">todo.sr.ht</a>
        bug tracking
    </dt>
    <dd>
      <a href="/todo.sr.ht">User Manual</a>
    </dd>
  </div>
  <div class="col-md-6">
    <dt>
        <a href="https://dispatch.sr.ht">dispatch.sr.ht</a>
        task automation
    </dt>
    <dd>
      <a href="/dispatch.sr.ht">User Manual</a>
    </dd>
  </div>
  <div class="col-md-6">
    <dt>
        <a href="https://meta.sr.ht">meta.sr.ht</a>
        account &amp; security
    </dt>
    <dd>
      <a href="/meta.sr.ht">User Manual</a>&mdash;<a href="#">API Reference</a>
    </dd>
  </div>
  <div class="col-md-6">
    <dt>man.sr.ht wikis</dt>
    <dd>
      <a href="/man.sr.ht">User Manual</a>
    </dd>
  </div>
</dl>

Please review the sr.ht [terms of service](terms.md) and [privacy
policy](privacy.md).

M sr.ht/index.md => sr.ht/index.md +8 -47
@@ 1,53 1,14 @@
Welcome to sr.ht! For directions to documentation about specific sr.ht sites,
see [the index](/). This page serves to document the whole.
Here are some general resources about sr.ht as a whole.

# Reporting bugs
# Billing

You can report bugs and request features for sr.ht at their relevant ticket
trackers:
For information on billing, refer to the [billing FAQ](/billing-faq.md).

- [builds.sr.ht](https://todo.sr.ht/~sircmpwn/builds.sr.ht)
- [dispatch.sr.ht](https://todo.sr.ht/~sircmpwn/dispatch.sr.ht)
- [git.sr.ht](https://todo.sr.ht/~sircmpwn/git.sr.ht)
- [lists.sr.ht](https://todo.sr.ht/~sircmpwn/lists.sr.ht)
- [man.sr.ht](https://todo.sr.ht/~sircmpwn/man.sr.ht)
- [meta.sr.ht](https://todo.sr.ht/~sircmpwn/meta.sr.ht)
- [todo.sr.ht](https://todo.sr.ht/~sircmpwn/todo.sr.ht)
# Terms of Service

There is also a general tracker for tickets that affect the whole network or for
which you are unsure of the appropriate tracker:
By using sr.ht, you agree to its [terms of service](/terms.md).

- [sr.ht](https://todo.sr.ht/~sircmpwn/sr.ht)
# Privacy Policy

# Getting help

sr.ht questions, feature requests, and general discussion are held on the
~sircmpwn/sr.ht-discuss mailing list:

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

Please search the archives for threads related to your question before posting.

# Development

sr.ht development takes place on the
[sr.ht-dev](https://lists.sr.ht/~sircmpwn/sr.ht-dev) mailing list. Please email
patches and development-related questions there.

Source code for sr.ht is available on [~sircmpwn's git.sr.ht
account](https://git.sr.ht/~sircmpwn/?search=sr.ht). Installation instructions
can be found [here](/installation.md).

# IRC

An IRC channel is also available for sr.ht-related discussion: [#sr.ht
on Freenode](http://webchat.freenode.net/?channels=%23sr.ht&uio=d4).

# Billing help

A dedicated [billing FAQ](../billing-faq.md) is available.

# Security vulnerabilities?

Please send an email to [sir@cmpwn.com](mailto:sir@cmpwn.com), optionally using
the public key [7BC79407090047CA](https://drewdevault.com/publickey.txt).
We take your privacy extremely seriously. To learn more, review our [privacy
policy](/privacy.md).

A support.md => support.md +60 -0
@@ 0,0 1,60 @@
# Asking the community

A great place to ask for general questions with using sr.ht, starting
discussions about your ideas and feature requests, and generally getting to know
the sr.ht community is the
[sr.ht-discuss](https://lists.sr.ht/~sircmpwn/sr.ht-discuss) mailing list. You
can post here by writing an email to
[~sircmpwn/sr.ht-discuss@lists.sr.ht](mailto:~sircmpwn/sr.ht-discuss@lists.sr.ht).
Please review the [mailing list etiquette guide](../lists.sr.ht/etiquette)
first! Be sure to search through the archives, as your question may have been
asked before.

# Asking the admins

You can reach Drew DeVault, the maintainer of sr.ht and your friendly
neighborhood sysadmin, by sending an email to
[sir@cmpwn.com](mailto:sir@cmpwn.com). Feel free to email him for any reason,
but this is your best bet with account-related problems, billing issues, and
similar woes.

# Real time chat

Both community members and admins hang out at [#sr.ht on
irc.freenode.net][webchat], where you're welcome to ask questions and have
discussions in a more free-form, real-time context. There's not always someone
paying attention here, so be prepared to wait or follow-up with an email if
necessary.

[webchat]: http://webchat.freenode.net/?channels=%23sr.ht&uio=d4

# Paid support

Normally, support is provided at the best effort of the sysadmins, which may be
impacted by time and resource constraints. However, paid support options are
available for organizations and businesses hoping to get to the front of the
queue. For details, [send me an email](mailto:sir@cmpwn.com).

# Submitting bug reports

Each service of sr.ht has a dedicated bug tracker:

- [git.sr.ht](https://todo.sr.ht/~sircmpwn/git.sr.ht)
- [builds.sr.ht](https://todo.sr.ht/~sircmpwn/builds.sr.ht)
- [todo.sr.ht](https://todo.sr.ht/~sircmpwn/todo.sr.ht)
- [lists.sr.ht](https://todo.sr.ht/~sircmpwn/lists.sr.ht)
- [man.sr.ht](https://todo.sr.ht/~sircmpwn/man.sr.ht)
- [dispatch.sr.ht](https://todo.sr.ht/~sircmpwn/dispatch.sr.ht)
- [meta.sr.ht](https://todo.sr.ht/~sircmpwn/meta.sr.ht)

There is also a [general-purpose bug
tracker](https://todo.sr.ht/~sircmpwn/sr.ht) for issues that fit nowhere else,
or that you're unsure of the appropriate place to report your bug:


# Security vulnerabilities

Please send an email to [sir@cmpwn.com](mailto:sir@cmpwn.com), optionally using
the public key [7BC79407090047CA](https://drewdevault.com/publickey.txt). Please
do not discuss security vulnerabilities in public until a fix has been developed
and deployed.

A tutorials/getting-started-with-builds.md => tutorials/getting-started-with-builds.md +131 -0
@@ 0,0 1,131 @@
# Getting started with builds.sr.ht

builds.sr.ht is our build automation platform. We're going to walk through the
process of running jobs on builds.sr.ht and a look at few useful features.

## Build manifests

Unlike platforms like Jenkins, builds.sr.ht does not allow you to pre-configure
jobs. And unlike platforms like Travis, jobs are not inherently tied to a git
repository. Each job on builds.sr.ht is described ad-hoc with a build manifest,
which can be submitted to builds.sr.ht for processing.

Let's start with a basic manifest:

```yml
image: alpine/edge
tasks:
- example: |
    echo "hello world"
```

This is a build manifest, written in [YAML](http://yaml.org/). When we submit
this to builds.sr.ht, it will boot up an [Alpine
Linux](https://alpinelinux.org/) virtual machine using the edge release of
Alpine Linux. Then it will execute each of our build tasks - in this case,
saying "hello world".

## Submitting jobs on the web

builds.sr.ht has a web submission form, where you can paste a build manifest and
submit the job without any additional configuration. This is a useful way of
testing build manifests before giving them a permanent home, or running one-off
tasks. Visit the [job submission form](https://builds.sr.ht/submit) and paste in
the example manifest. Add a note, perhaps "my first job", and click "submit" to
run the job.

You'll be redirected to the job detail page. In a moment, one of our job runners
will pick up the task and start processing it. Within a few seconds, you should
see "hello world" shown under the "example" task.

## Adding git repositories to builds

Let's try a new build manifest. This one is going to compile and test the
[scdoc](https://git.sr.ht/~sircmpwn/scdoc) project.

```yml
image: alpine/edge
sources:
- https://git.sr.ht/~sircmpwn/scdoc
tasks:
- build: |
    cd scdoc
    make
- test: |
    cd scdoc
    make check
```

Before starting your tasks, builds.sr.ht will clone each repository listed in
"sources" to the build environment. You can have as many or as few (including
zero) git repositories as you like.

## Adding dependencies

scdoc is a simple project with no dependencies. Let's try a slightly more
complex one: [mrsh](https://git.sr.ht/~emersion/mrsh), which depends on
[meson](https://mesonbuild.com/). Here's a build manifest for it:

```yml
image: alpine/edge
packages:
- meson
sources:
- https://git.sr.ht/~emersion/mrsh
tasks:
- configure: |
    cd mrsh
    meson build
- build: |
    cd mrsh
    ninja -C build
- test: |
    cd mrsh
    ninja -C build test
```

This time, builds.sr.ht will install [Alpine Linux's meson
package](https://pkgs.alpinelinux.org/package/edge/main/x86_64/meson) before
starting your build. This uses Alpine's native `apk` package manager - other
images use different package managers.

## Testing on other platforms

Portability is important - so let's try running the same manifest on another
operating system.

```yml
image: freebsd
packages:
- meson
sources:
- https://git.sr.ht/~emersion/mrsh
tasks:
- configure: |
    cd mrsh
    meson build
- build: |
    cd mrsh
    ninja -C build
- test: |
    cd mrsh
    ninja -C build test
```

This one happens to work without any changes, but note that some images have
different names for packages, different distributions of coreutils, and so on.

## Adding these builds to your git repository

If you put a build manifest in `.build.yml` at the top of your repo, a build job
will be created each time you push new commits. You can also create multiple
manifests, for example to test multiple platforms, by putting several build
manifests at `.builds/*.yml`.

---

Other resources:

- [builds.sr.ht user manual](/builds.sr.ht)
- [Build manifest reference](/builds.sr.ht/manifest.md)
- [dispatch.sr.ht](/dispatch.sr.ht)

A tutorials/index.html => tutorials/index.html +80 -0
@@ 0,0 1,80 @@
<p>
  <strong>Welcome to sr.ht!</strong> We have lots of helpful tutorials to
  introduce you to our platform and get you productive as soon as possible.
</p>
<style>
.tutorial:not(:last-child) {
  margin-bottom: 1rem;
}
</style>
<div class="event-list">
  <div class="event" style="margin-left: -0.5rem; margin-right: -0.5rem;">
    <h3>Setting up your account &amp; first git repository</h3>
    <p>
      This tutorial is recommended as the first stop for any new user.
    </p>
    <a href="set-up-account-and-git.md" class="btn btn-success">
      Read more
      <span class="icon icon-caret-right">
        <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 192 512"><path d="M0 384.662V127.338c0-17.818 21.543-26.741 34.142-14.142l128.662 128.662c7.81 7.81 7.81 20.474 0 28.284L34.142 398.804C21.543 411.404 0 402.48 0 384.662z"/></svg>
      </span>
    </a>
  </div>
</div>
<div class="tutorial">
  <h3>Getting started with builds.sr.ht</h3>
  <p>
    Running your first few jobs on our continuous integration platform,
    builds.sr.ht.
  </p>
  <a href="getting-started-with-builds.md" class="btn btn-default">
    Read more
    <span class="icon icon-caret-right">
      <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 192 512"><path d="M0 384.662V127.338c0-17.818 21.543-26.741 34.142-14.142l128.662 128.662c7.81 7.81 7.81 20.474 0 28.284L34.142 398.804C21.543 411.404 0 402.48 0 384.662z"/></svg>
    </span>
  </a>
</div>
<!--
<div class="tutorial">
  <h3>Contributing to projects on sr.ht</h3>
  <p>
    How to configure git to send emails and sending your first patches.
  </p>
  <a href="contributing-to-projects.md" class="btn btn-default">
    Read more
    <span class="icon icon-caret-right">
      <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 192 512"><path d="M0 384.662V127.338c0-17.818 21.543-26.741 34.142-14.142l128.662 128.662c7.81 7.81 7.81 20.474 0 28.284L34.142 398.804C21.543 411.404 0 402.48 0 384.662z"/></svg>
    </span>
  </a>
</div>
<div class="tutorial">
  <h3>Accepting patches from a mailing list</h3>
  <p>
    Integrating patches from mailing lists into your own projects.
  </p>
  <a href="accepting-patches-from-lists.md" class="btn btn-default">
    Read more
    <span class="icon icon-caret-right">
      <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 192 512"><path d="M0 384.662V127.338c0-17.818 21.543-26.741 34.142-14.142l128.662 128.662c7.81 7.81 7.81 20.474 0 28.284L34.142 398.804C21.543 411.404 0 402.48 0 384.662z"/></svg>
    </span>
  </a>
</div>
<div class="tutorial">
  <h3>Using secrets on builds.sr.ht</h3>
  <p>
    How to securely use secret data in builds.sr.ht jobs.
  </p>
  <a href="using-secrets-in-builds.md" class="btn btn-default">
    Read more
    <span class="icon icon-caret-right">
      <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 192 512"><path d="M0 384.662V127.338c0-17.818 21.543-26.741 34.142-14.142l128.662 128.662c7.81 7.81 7.81 20.474 0 28.284L34.142 398.804C21.543 411.404 0 402.48 0 384.662z"/></svg>
    </span>
  </a>
</div>
-->
<hr />
<div class="alert alert-primary">
  <strong>More tutorials are coming!</strong>
  Is there something in particular you want to see here? Mention it on
  <a href="https://lists.sr.ht/~sircmpwn/sr.ht-discuss">sr.ht-discuss</a>!
</div>

A tutorials/set-up-account-and-git.md => tutorials/set-up-account-and-git.md +76 -0
@@ 0,0 1,76 @@
If this is your first time using git, we recommend starting with the [Git
Book](https://git-scm.com/book/en/v2). It's free, translated into many
languages, and easy to read. Read at least the first 3 chapters.

# Setting up your account & first git repository

Thanks for signing up for sr.ht! Let's start by setting up your profile details.
Your profile page is on meta.sr.ht, the sr.ht account management service. You
can fill in some basic (and optional) details like your bio on your [profile
page](https://meta.sr.ht/profile). Before we can get any work done, however, we
need to set up your SSH key and add it on the keys page.

## Generating an SSH key

sr.ht does not support pushing to git repositories over HTTPS with a
username+password - SSH keys are mandatory. If you already have an SSH key, you
can skip this step. If not, run the following command to generate one:

    ssh-keygen

If you accept the defaults, the public key will be written to
`~/.ssh/id_rsa.pub` and the private key to `~/.ssh/id_rsa`.

## Uploading your key to meta.sr.ht

The meta.sr.ht [keys page](https://meta.sr.ht/keys) has a form for adding your
SSH key. If you followed the earlier instructions to generate an SSH key, your
public key is stored at `~/.ssh/id_rsa.pub`. Copy the contents of this file to
your clipboard and paste it into the text field. Click "Add key" and your key
will now be valid for pushing to git repositories.

## Creating a git repository

If you already have a git repository you want to push to git.sr.ht, you can skip
this step. If not, open up a shell and run the following commands to create a
test repository for experimenting with:

    mkdir example
    cd example
    git init
    echo "Hello world!" >README.md
    git add README.md
    git commit -m "Initial commit"

This created a new git repository and added a `README.md` file to it, then
created the initial commit.

## Pushing your repository to git.sr.ht

The following commands will add a "remote" to your local git repository, which
will allow you to push changes to a remote repository on git.sr.ht.

    git remote add origin git@git.sr.ht:~username/example

Make sure to replace `username` with your own. Then this command will push your
master branch to git.sr.ht:

    git push -u origin master

Since this repository didn't previously exist, you'll be prompted with a link to
create the repository on git.sr.ht - click that link and fill out the form on
that page. You'll be redirected to your repository on git.sr.ht: you're done!

<div class="alert alert-primary">
    <strong>Tip</strong>: You can create repositories on the web on the
    git.sr.ht <a href="https://git.sr.ht/create">new repository page</a>.
</div>

---

Next: [Getting started with builds.sr.ht](getting-started-with-builds.md)

Other resources:

- [The git book](https://git-scm.com/book/en/v2)
- [git.sr.ht user manual](/git.sr.ht)