diff options
| -rw-r--r-- | index.html | 138 | ||||
| -rw-r--r-- | index.md | 100 | ||||
| -rw-r--r-- | sr.ht/index.md | 55 | ||||
| -rw-r--r-- | support.md | 60 | ||||
| -rw-r--r-- | tutorials/getting-started-with-builds.md | 131 | ||||
| -rw-r--r-- | tutorials/index.html | 80 | ||||
| -rw-r--r-- | tutorials/set-up-account-and-git.md | 76 |
7 files changed, 493 insertions, 147 deletions
diff --git a/index.html b/index.html new file mode 100644 index 0000000..3d299ed --- /dev/null +++ b/index.html @@ -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> + — + <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 & 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 & security + </dt> + <dd> + <a href="/meta.sr.ht">User Manual</a> + — + <a href="/meta.sr.ht/api.md">API Reference</a> + </dd> + </div> +</dl> diff --git a/index.md b/index.md deleted file mode 100644 index 6d7b1a0..0000000 --- a/index.md +++ /dev/null @@ -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> - — - <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 & security - </dt> - <dd> - <a href="/meta.sr.ht">User Manual</a>—<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). diff --git a/sr.ht/index.md b/sr.ht/index.md index 49641f0..6e2604b 100644 --- a/sr.ht/index.md +++ b/sr.ht/index.md @@ -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). diff --git a/support.md b/support.md new file mode 100644 index 0000000..56007e6 --- /dev/null +++ b/support.md @@ -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. diff --git a/tutorials/getting-started-with-builds.md b/tutorials/getting-started-with-builds.md new file mode 100644 index 0000000..7a0b29e --- /dev/null +++ b/tutorials/getting-started-with-builds.md @@ -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) diff --git a/tutorials/index.html b/tutorials/index.html new file mode 100644 index 0000000..5175c8f --- /dev/null +++ b/tutorials/index.html @@ -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 & 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> diff --git a/tutorials/set-up-account-and-git.md b/tutorials/set-up-account-and-git.md new file mode 100644 index 0000000..7d4b531 --- /dev/null +++ b/tutorials/set-up-account-and-git.md @@ -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) |