From 4330f449e85ea0e04ac9e83ea6bc90c047a1cd17 Mon Sep 17 00:00:00 2001
From: Carlos A Becker <caarlos0@gmail.com>
Date: Fri, 12 Nov 2021 00:58:06 -0300
Subject: [PATCH] docs: how it works

first draft, this shall be improved over time

closes #1315
---
 www/docs/how-it-works.md | 25 +++++++++++++++++++++++++
 www/mkdocs.yml           |  1 +
 2 files changed, 26 insertions(+)
 create mode 100644 www/docs/how-it-works.md

diff --git a/www/docs/how-it-works.md b/www/docs/how-it-works.md
new file mode 100644
index 000000000..8520abe89
--- /dev/null
+++ b/www/docs/how-it-works.md
@@ -0,0 +1,25 @@
+# How it works
+
+GoReleaser goal is to automate most of the boring work you'll had while releasing software.
+Ideally, using sensible defaults and making the most common usecases easy.
+
+GoReleaser expects a couple of things:
+
+- a `.goreleaser.yml` file with the configuration (see the [customization section](/customization) for more info)
+- a clean working tree
+- a SemVer-compatible version (e.g. `10.21.34-something`)
+
+And that's it.
+
+## What happens when you release
+
+A GoReleaser run is split into 4 major steps:
+
+- **defaulting**: configures sensible defaults for each step
+- **building**: builds the binaries, archives, packages, Docker images, etc
+- **publishing**: publishes the release to the configured SCM, Docker registries, blob storages...
+- **announcing**: announces your release to the configured channels
+
+Some steps might be skipped with `--skip-foo`-like flags (check the [command line docs](/cmd/goreleaser/) for details).
+
+If any of the previous steps fails, the next steps will not run.
diff --git a/www/mkdocs.yml b/www/mkdocs.yml
index 6f469e87e..076b353b7 100644
--- a/www/mkdocs.yml
+++ b/www/mkdocs.yml
@@ -49,6 +49,7 @@ nav:
 - intro.md
 - install.md
 - quick-start.md
+- how-it-works.md
 - Limitations:
   - limitations/cgo.md
   - limitations/semver.md