Contributing to Uberspace 8 Lab¶

Help others run software on Uberspace 8: report a problem, improve a guide, or write a new one. Small fixes are welcome, and you do not need to install anything locally to contribute through Codeberg.

Report a problem¶

Use the issue button on a guide or open an issue. Name the application and explain what happened and what you expected. Include relevant commands or errors, with passwords and other secrets removed. You do not need a proposed fix, special title format, or labels.

Fix a guide¶

Edit its docs/guide_<appname>.md file in your fork and open a pull request. Explain what changed and how you checked it. You can use Codeberg's web editor. An issue first is optional; for larger changes it can help coordinate work. Maintainers will help with formatting and review feedback.

Add a guide¶

Copy docs/meta/guide_boilerplate to docs/guide_<appname>.md.
Fill in the metadata, add a logo under docs/_static/images/guides/, and replace the example content. Remove optional sections that do not apply.
Test the instructions on a fresh Uberspace 8 Asteroid and record the versions.
Open a pull request describing what you tested and any remaining questions.

Use a clear title and commit message; no prefix is required. Maintainers handle labels. After review, your contribution appears in the Hall of Fame. New guides and substantial edits can earn a goodie. If possible, stay available to help keep your guide working.

What a guide needs¶

The boilerplate supplies the metadata and shared header. Keep these fields: render_macros: true, title, logo, authors, tags, website, license, and tested with quoted app and uberspace versions.

Every author needs a name and an email address or website/profile URL. These details are public: the Hall of Fame links to the URL when supplied, otherwise to the email address. organization is optional.

Use existing tags from mkdocs.yml → extra.tag_descriptions, or add a short description there for a new tag.

Keep the shared header first, followed by a short introduction, then these sections in order. Omit optional sections when they do not apply.

Section	When needed
Prerequisites	Optional; explain required knowledge in a note before or within this section
Installation	Required; working installation steps
Configuration	Optional
Tuning	Optional
Debugging	Optional
Updates	Required; update steps and a note linking to releases or an update feed
Further Reading	Optional

Exact separator lengths and stock wording are not required.

Write in clear English for readers with basic shell knowledge. Explain unusual steps and flags, use portable paths such as /var/www/virtual/$USER/html/, and show relevant output. Use Uberspace's mariadb / mariadb-dump commands and my_print_defaults client for database credentials. Explain destructive steps and changing default passwords.

Use console-remote fences for server commands and console for local commands. The usual examples are [isabell@moondust ~]$ and [localuser@localhost ~]$. Use a language fence for configuration files. Link to the Uberspace Manual for shared concepts instead of repeating its instructions.

Optional local checks¶

Install uv, then run:

uv sync --frozen
uv run -- python hooks/check_guide.py docs/guide_appname.md
uv run -- mkdocs serve --strict

The checker also accepts --all, --staged, or --changed (committed changes against main; use --base REVISION for another base).

With Task installed, task check runs guide checks, unit tests, and a strict site build. task lint runs the optional local linters; task hooks:install installs Git hooks if you want them. Neither is required to submit a contribution. Automated PR checks report errors and maintainers use the review checklist to assess the instructions themselves.

Code of conduct¶

Be excellent to each other.

Boilerplate¶

---
render_macros: true
title: AppName
logo: _static/images/guides/AppName.png
authors:
  - name: Your Name
    # Supply email or url (both are welcome); used publicly in the Hall of Fame.
    url: https://your-website.com
tags:
  - tag1
  - tag2
  - tag3
website: https://example.com/appname
license: AGPLv3
tested:
  app: "1.0.0"
  uberspace: "8.0.0"
---

{% include 'guide_header.md' %}

Short description of the application.

----

!!! note

    For this guide you should be familiar with the basic concepts of:

    * [PHP](https://u8manual.uberspace.de/lang_php/)
    * [MariaDB](https://u8manual.uberspace.de/database_mariadb/)

## Prerequisites

Describe the runtimes and versions this application needs.

You'll need your MariaDB credentials:

```console-remote
[isabell@moondust ~]$ my_print_defaults client
--default-character-set=utf8mb4
--user=isabell
--password=MySuperSecretPassword
```

## Installation

Step-by-step installation instructions...

```console-remote
[isabell@moondust ~]$ cd /var/www/virtual/$USER/html/
[isabell@moondust html]$ wget https://example.com/latest.zip
```

## Configuration

Post-installation configuration steps...

## Tuning

How to make your installation really fly 🚀

## Debugging

Where to look when things are not working as expected.

## Updates

!!! note

    Check the [release page or update feed](https://github.com/example/app/releases.atom) regularly.

Instructions for updating...

## Further Reading

Optional links for debugging, advanced configuration, and deeper documentation:

- [Official documentation](https://example.com/docs): application docs and configuration reference
- [Community support](https://example.com/community): forum or chat for troubleshooting