docs: add all current features (#34)

.gitattributes

@@ -0,0 +1 @@
+*.png filter=lfs diff=lfs merge=lfs -text

.github/workflows/docs.yaml

@@ -14,7 +14,7 @@ jobs:
     steps:
       - uses: actions/checkout@v4
         with:
-          fetch-depth: 0
+          lfs: "true"
       - name: Install latest mdbook
         run: |
           tag=$(curl 'https://api.github.com/repos/rust-lang/mdbook/releases/latest' | jq -r '.tag_name')

action.yml

@@ -5,17 +5,19 @@ branding:
   icon: 'package'
   color: 'red'
 inputs:
+  # Remember to update docs/reference/github-action.md
   branch:
     default: main
     description: "This branch is used as the target for releases."
   token:
-    description: 'GitHub token for creating and grooming release PRs, defaults to using secrets.GITHUB_TOKEN'
+    description: 'GitHub token for creating and updating release PRs, defaults to using secrets.GITHUB_TOKEN'
     required: false
     default: ${{ github.token }}
   extra-files:
     description: 'List of files that are scanned for version references.'
     required: false
     default: ""
+  # Remember to update docs/reference/github-action.md
 outputs: {}
 runs:
   using: 'docker'

docs/SUMMARY.md

@@ -19,6 +19,7 @@
 
 # Reference
 
+- [Glossary](reference/glossary.md)
 - [Pull Request Options](reference/pr-options.md)
 - [GitHub Action](reference/github-action.md)
 - [GitLab CI]()

docs/explanation/release-pr.md

@@ -1 +1,21 @@
 # Release Pull Request
+
+A _release pull request_ is opened by `releaser-pleaser` when it detects that there are _releasable changes_.
+The pull request contains an _auto-generated Changelog_ and a _suggested next version_.
+Once someone merges this pull request, `releaser-pleaser` will create a matching Git Tag and Release on GitHub/GitLab.
+
+Maintainers can fill various fields in the pull request description and through labels to change the proposed release. Some examples of this are: _Changelog Prefix & Suffix text_ and _requesting a pre-release_ (`alpha`, `beta`, `rc`) version.
+
+The pull request is automatically updated by `releaser-pleaser` every time it runs.
+
+### Example Screenshot
+
+![Screenshot of an example Release Pull Request on GitHub](./release-pr.png)
+
+## Related Documentation
+
+- **Guide**
+  - [Pre-releases](../guides/pre-releases.md)
+  - [Release Notes](../guides/release-notes.md)
+- **Reference**
+  - [Pull Request Options](../reference/pr-options.md)

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.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)

docs/reference/github-action.md

@@ -1 +1,25 @@
 # GitHub Action
+
+## Reference
+
+The action is available as `apricote/releaser-pleaser` on github.com.
+
+## Versions
+
+The `apricote/releaser-pleaser` action is released together with `releaser-pleaser` and they share the version number.
+
+The action does not support floating tags (e.g. `v1`) right now ([#31](https://github.com/apricote/releaser-pleaser/issues/31)). You have to use the full version or commit SHA instead: `apricote/releaser-pleaser@v0.2.0`.
+
+## Inputs
+
+The following inputs are supported by the `apricote/releaser-pleaser` GitHub Action.
+
+| Input         | Description                                            |         Default |                                                              Example |
+| ------------- | :----------------------------------------------------- | --------------: | -------------------------------------------------------------------: |
+| `branch`      | This branch is used as the target for releases.        |          `main` |                                                             `master` |
+| `token`       | GitHub token for creating and updating release PRs     | `$GITHUB_TOKEN` |                                `${{secrets.RELEASER_PLEASER_TOKEN}}` |
+| `extra-files` | List of files that are scanned for version references. |            `""` | <pre><code>version/version.go<br>deploy/deployment.yaml</code></pre> |
+
+## Outputs
+
+The action does not define any outputs.

docs/reference/glossary.md

@@ -0,0 +1,47 @@
+# Glossary
+
+### Changelog
+
+The Changelog is a file in the repository (`CHANGELOG.md`) that contains the [Release Notes](#release-notes) for every release of that repository. Usually, new releases are added at the top of the file.
+
+### Conventional Commits
+
+[Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) is a specification for commit messages. It is the only supported commit message schema in `releaser-pleaser`. Follow the link to learn more.
+
+### Forge
+
+A **forge** is a web-based collaborative software platform for both developing and sharing computer applications.[^wp-forge]
+
+Right now only **GitHub** is supported. We plan to support **GitLab** in the future ([#4](https://github.com/apricote/releaser-pleaser/issues/4)). For other forges like Forgejo or Gitea, please open an issue and submit a pull request.
+
+[^wp-forge]: Quote from [Wikipedia "Forge (software)"](<https://en.wikipedia.org/wiki/Forge_(software)>)
+
+### Markdown
+
+[Markdown](https://en.wikipedia.org/wiki/Markdown) is a lightweight markup language used on many [forges](#forge) as the preferred way to format text.
+
+In `releaser-pleaser` Markdown is used for most texts.
+
+### Pre-release
+
+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.
+
+Learn more in the [Pre-releases](../guides/pre-releases.md) guide.
+
+### Release Pull Request
+
+A Release Pull Request is opened by `releaser-pleaser` whenever it finds releasable commits in your project. It proposes a new version number and the Changelog. Once it is merged, `releaser-pleaser` creates a matching release.
+
+Learn more in the [Release Pull Request](../explanation/release-pr.md) explanation.
+
+### Release Notes
+
+Release Notes describe the changes made to the repository since the last release. They are made available in the [Changelog](#changelog), in Git Tags and through the [forge](#forge)-native Releases.
+
+Learn more in the [Release Notes customization](../guides/release-notes.md) guide.
+
+### Semantic Versioning (SemVer)
+
+[Semantic Versioning](https://semver.org/) is a specification for version numbers. It is the only supported versioning schema in `releaser-pleaser`. Follow the link to learn more.

docs/reference/pr-options.md

@@ -1 +1,46 @@
 # Pull Request Options
+
+The proposed releases can by influenced by changing the description and labels of either the release pull request or the normal pull requests created by other developers. This document lists the available options for both types of pull requests.
+
+## Release Pull Request
+
+Created by `releaser-pleaser`.
+
+### Release Type
+
+**Labels**:
+
+- `rp-next-version::alpha`
+- `rp-next-version::beta`
+- `rp-next-version::rc`
+- `rp-next-version::normal`
+
+Adding one of these labels will change the type of the next release to the one indicated in the label. This is used to create [pre-releases](../guides/pre-releases.md).
+
+Adding more than one of these labels is not allowed and the behaviour if multiple labels are added is undefined.
+
+### Release Notes
+
+**Code Blocks**:
+
+- `rp-prefix`
+- `rp-suffix`
+
+Any text in code blocks with these languages is being added to the start or end of the Release Notes and Changelog. Learn more in the [Release Notes](../guides/release-notes.md) guide.
+
+### Status
+
+**Labels**:
+
+- `rp-release::pending`
+- `rp-release::tagged`
+
+These labels are automatically added by `releaser-pleaser` to release pull requests. They are used to track if the corresponding release was already created.
+
+Users should not set these labels themselves.
+
+## Other Pull Requests
+
+Not created by `releaser-pleaser`.
+
+Normal pull requests do not support any options right now.