docs: add all current features (#34)

docs/guides/github-workflow-permissions.md

@@ -1 +1,83 @@
 # Workflow Permissions on GitHub
+
+## Default GitHub token permissions
+
+The [GitHub](../tutorials/github.md) tutorial uses the builtin `GITHUB_TOKEN` for the action to get access to the repository. It uses the following permissions on the token:
+
+```yaml
+jobs:
+  releaser-pleaser:
+    permissions:
+      # - list commits
+      # - push commits for the release pull request
+      # - push new releases & tags
+      contents: write
+
+      # - read pull requests for Changelog
+      # - read and write release pull request
+      # - create labels on the repository
+      pull-requests: write
+```
+
+These permissions are sufficient for simple operations. But fail if you want to run another workflow on `push: tag`.
+
+## Workflows on Tag Push
+
+When using the automatic `GITHUB_TOKEN` to create tags, GitHub does not create new workflow runs that are supposed to be created. This is done to prevent the user from "accidentally creating recursive workflow runs". You can read more about this behaviour in the [GitHub Actions docs](https://docs.github.com/en/actions/security-for-github-actions/security-guides/automatic-token-authentication#using-the-github_token-in-a-workflow).
+
+Workflows that have a trigger on pushed tags are often used to build artifacts for the release, like binaries or container images.
+
+```yaml
+on:
+  push:
+    tags:
+      - "v*.*.*"
+```
+
+To circumvent this restriction, you can create a personal access token and instruct `releaser-pleaser` to use that instead to talk to GitHub.
+
+### 1. Create Personal Access Token
+
+On your account settings, navigate to the [Personal access tokens](https://github.com/settings/tokens?type=beta) section.
+
+You can either use a "Fine-grained" or "Classic" token for this. Fine-grained tokens can be restricted to specific actions and repositories and are more secure because of this. On the other hand they have a mandatory expiration of 1 year maximum. Classic tokens have unrestricted access to your account, but do not expire.
+
+Copy the token for the next step.
+
+#### Fine-grained token
+
+When you create a fine-grained token, restrict the access to the repository where you are using `releaser-pleaser`.
+
+In the **repository permissions** you need to give **read and write** access for **Contents** and **Pull requests**. All other permissions can be set to **No access** (default).
+
+No **account permissions** are required and you can set all to **No access** (default).
+
+### 2. Repository Secret
+
+Next you need to add the personal access token as a repository secret.
+
+Open the repository settings to **Secrets and variables > Actions**:
+
+> `https://github.com/YOUR-NAME/YOUR-REPO/settings/secrets/actions`
+
+Click on **New repository secret** and add the personal access token to a secret named `RELEASER_PLEASER_TOKEN`.
+
+### 3. Update Workflow
+
+Update the workflow file (`.github/workflows/releaser-pleaser.yaml`) to pass the new secret to the `releaser-pleaser` action. You can also remove the permissions of the job, as they are now unused.
+
+```diff
+ jobs:
+   releaser-pleaser:
+     runs-on: ubuntu-latest # The action uses docker containers
+-    permissions:
+-      contents: write
+-      pull-requests: write
+     steps:
+       - name: releaser-pleaser
+         uses: apricote/releaser-pleaser@v0.2.0
++        with:
++          token: ${{ secrets.RELEASER_PLEASER_TOKEN }}
+```
+
+The next release created by releaser-pleaser will now create the follow-up workflows as expected.

docs/guides/pre-releases.md

@@ -1 +1,38 @@
 # Pre-releases
+
+Pre-releases are a concept of [SemVer](#semantic-versioning-semver). They follow the normal versioning schema but use a suffix out of `-alpha.X`, `-beta.X` and `-rc.X`.
+
+Pre-releases are not considered "stable" and are usually not recommended for most users.
+
+## Creating a pre-release
+
+If you want to create a pre-release, you can set **one** of the following labels on the release pull request:
+
+- `rp-next-version::alpha`
+- `rp-next-version::beta`
+- `rp-next-version::rc`
+
+This will cause `releaser-pleaser` to run, and it will change the release pull request to a matching version according to the type of pre-release.
+
+## Versioning
+
+For pre-releases, `releaser-pleaser` analyzes the commits made since the **last stable release**. The version bump from this is then applied to the last stable release and the pre-release info is added to the version number. If a previous pre-release of the matching type exists, the "pre-release counter" at the end of the version is increased by one.
+
+An examples:
+
+- The last stable version was `v1.0.0`
+- Since then a `feat` commit was merged, this causes a bump of the minor version: `v1.1.0`
+- The release pull request has the label `rp-next-version::beta`. This changes the suggested version to `v1.1.0-beta.0`
+
+If there was already a `v1.1.0-beta.0`, then the suggested version would be `v1.1.0-beta.1`.
+
+Changing the pre-release type (for example from `beta` to `rc`), resets the counter. `v1.1.0-beta.1` would be followed by `v1.1.0-rc.0`.
+
+## Stable Release
+
+`releaser-pleaser` ignores pre-releases when looking for releasable commits. This means that right after creating a new pre-release, `releaser-pleaser` again detects releasable commits and opens a new release pull request for the stable version.
+
+## Related Documentation
+
+- **Reference**
+  - [Pull Request Options](../reference/pr-options.md)

docs/guides/release-notes-collapsible.png

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:74f5f39210bdf9c55f7cec64d4b12465b569646efdfbb2e3eb08b32277cd5145
+size 3357

docs/guides/release-notes.md

@@ -1 +1,54 @@
 # Customizing Release Notes
+
+You can customize the generated Release Notes in two ways:
+
+## For a single commit / pull request
+
+This feature is still being worked on. Check out [#5](https://github.com/apricote/releaser-pleaser/issues/5) for the current status.
+
+## For the release
+
+It is possible to add custom **prefix** and **suffix** Markdown-formatted text to the Release Notes.
+
+The release pull request description has text fields where maintainers can add the prefix and suffix. To see these fields, toggle the collapsible section in the description:
+
+![Screenshot of the collapsed section](./release-notes-collapsible.png)
+
+When you edit the description, make sure to put your desired content into the code blocks named `rp-prefix` and `rp-suffix`. Only the content of these blocks is considered.
+
+>     ```rp-prefix
+>     ### Prefix
+>
+>     This will be shown as the Prefix.
+>     ```
+>
+>     ```rp-suffix
+>     ### Suffix
+>
+>     This will be shown as the Suffix.
+>     ```
+
+To match the style of the auto-generated release notes, you should start any headings at level 3 (`### Title`).
+
+Once the description was updated `releaser-pleaser` automatically runs again and adds the prefix and suffix to the Release Notes and to the committed Changelog:
+
+```markdown
+## v1.1.0
+
+### Prefix
+
+This will be shown as the Prefix.
+
+### Features
+
+- Added cool new thing (#1)
+
+### Suffix
+
+This will be shown as the Suffix.
+```
+
+## Related Documentation
+
+- **Reference**
+  - [Pull Request Options](../reference/pr-options.md)