Improve the onboarding flow for new users

1 files changed, 131 insertions, 0 deletions

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)