Present your app

If you share your app, its presentation decides whether people trust it enough to install it. A clear introduction, honest documentation, and a changelog go a long way. None of these files are required, but a published app without them feels unfinished.

README.md in the app folder is the introduction. The app store shows it on the page of the app before it is installed. Keep it short: what the app does, and why someone would want it. It is also what people see when they browse your repository on GitHub.

DOCS.md is the documentation, shown on the Documentation tab of the app. This is where users go when something does not work, so cover:

• How to install and set up the app.
• Every option, what it does, and an example.
• Anything the user needs to do outside the app, like setting up an integration.
• Known limitations.
• Where to ask for help and report bugs.
• The license of the app.

If your app needs more privileges than usual, like host_network or turning off protection mode, explain why here. Users see the warnings, and they deserve to know the reason.

CHANGELOG.md lists the changes per version. Users see it when an update is available, and they read it to decide whether to update now. Put the newest version on top, and call out backward-incompatible changes clearly. Keep a Changelog is a good format to follow.

The icon shows up in the app store and the list of installed apps, the logo on the app page. Both are optional. Make sure they look good on light and dark backgrounds.

The Configuration tab shows your options and ports. Without translations, it shows the raw keys, like log_level or 8080/tcp. Add a file per language to the translations folder to give them readable names and descriptions:

# translations/en.yaml
configuration:
  log_level:
    name: "Log level"
    description: "How much detail to write to the log."
network:
  8080/tcp: "Web interface (not needed with ingress)"

See Add options and the translation file format.

Not every app is ready for everyone. Set stage in config.yaml to tell users where your app stands:

• stable: the default.
• experimental: works, but expect rough edges and changes.
• deprecated: no longer maintained. Point users to an alternative in the documentation.

To let users try new versions before everyone else, keep them in a separate branch. Users add your repository with the branch name after a #:

https://github.com/me/my-apps#next

Give the repository a different name in the repository.yaml of that branch, like "My apps (beta)", so users can tell them apart in the app store. Mention the beta channel in your documentation.