From 753fcba68896b8dbf7ab19faf569b58117ff5ad8 Mon Sep 17 00:00:00 2001 From: Eli Bosley Date: Thu, 14 May 2026 11:15:56 -0400 Subject: [PATCH 1/5] docs(community-apps): add submission process docs - Purpose: document the Community Applications repository submission process in the docs site. - Before: the Community Applications page only had a brief contribution section and pointed maintainers to the old Asana submission form. - Problem: app maintainers lacked in-repo guidance for repository structure, XML metadata, supported fields, and the current submission portal. - Change: add a dedicated submission docs section with overview, repository XML, ca_profile.xml, field reference, and builder guide pages. - Implementation: link the existing Community Applications page to the new section, move the submission URL to ca.unraid.net/submit, update translated snapshot links, and adjust sidebar ordering. --- .../_category_.json | 8 +++ .../builder-guide.mdx | 49 +++++++++++++ .../repository-info-xml.mdx | 42 +++++++++++ .../repository-xml-format.mdx | 66 +++++++++++++++++ .../submission-overview.mdx | 45 ++++++++++++ .../xml-field-reference.mdx | 72 +++++++++++++++++++ .../community-applications.mdx | 4 +- .../managing-and-customizing-containers.mdx | 2 +- .../community-applications.mdx | 2 +- .../community-applications.mdx | 2 +- .../community-applications.mdx | 2 +- .../community-applications.mdx | 2 +- .../community-applications.mdx | 2 +- 13 files changed, 291 insertions(+), 7 deletions(-) create mode 100644 docs/unraid-os/using-unraid-to/run-docker-containers/community-applications-submissions/_category_.json create mode 100644 docs/unraid-os/using-unraid-to/run-docker-containers/community-applications-submissions/builder-guide.mdx create mode 100644 docs/unraid-os/using-unraid-to/run-docker-containers/community-applications-submissions/repository-info-xml.mdx create mode 100644 docs/unraid-os/using-unraid-to/run-docker-containers/community-applications-submissions/repository-xml-format.mdx create mode 100644 docs/unraid-os/using-unraid-to/run-docker-containers/community-applications-submissions/submission-overview.mdx create mode 100644 docs/unraid-os/using-unraid-to/run-docker-containers/community-applications-submissions/xml-field-reference.mdx diff --git a/docs/unraid-os/using-unraid-to/run-docker-containers/community-applications-submissions/_category_.json b/docs/unraid-os/using-unraid-to/run-docker-containers/community-applications-submissions/_category_.json new file mode 100644 index 00000000000..22eb7701f9b --- /dev/null +++ b/docs/unraid-os/using-unraid-to/run-docker-containers/community-applications-submissions/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Community Applications submissions", + "position": 3, + "link": { + "type": "doc", + "id": "unraid-os/using-unraid-to/run-docker-containers/community-applications-submissions/submission-overview" + } +} diff --git a/docs/unraid-os/using-unraid-to/run-docker-containers/community-applications-submissions/builder-guide.mdx b/docs/unraid-os/using-unraid-to/run-docker-containers/community-applications-submissions/builder-guide.mdx new file mode 100644 index 00000000000..950885ec498 --- /dev/null +++ b/docs/unraid-os/using-unraid-to/run-docker-containers/community-applications-submissions/builder-guide.mdx @@ -0,0 +1,49 @@ +--- +sidebar_position: 5 +sidebar_label: Builder guide +--- + +# Builder Guide + +Use this flow to create a Community Applications repository that is ready for validation, scan, and moderation review. + +## Start with the scaffold + +The [Community Apps starter repository](https://github.com/unraid/unraid-community-apps-starter) is the recommended starting point. It includes the expected root files, example Docker and plugin XML files, and placeholder metadata that you can replace with real values. + +## Quick start + +1. Create a new repository from the starter repository, or copy its structure into your existing repository. +2. Confirm the repository is public, active, and not archived. +3. Replace placeholder values in `README.md`, `LICENSE`, `icon.svg`, `ca_profile.xml`, and any template XML files. +4. Delete example Docker or plugin files you do not need. +5. Add one XML file for each Docker app or plugin you want to publish. +6. Commit the changes and open [ca.unraid.net/submit](https://ca.unraid.net/submit). +7. Run validation and scan checks. +8. Fix reported issues, commit the fixes, and rerun validation and scan. +9. Submit for review when all checks pass. + +## Suggested repository layout + +```text +my-ca-repo/ + README.md + LICENSE + .gitignore + icon.svg + ca_profile.xml + templates/ + example-app.xml + plugins/ + example-plugin.xml +``` + +## Builder paths + +- **Template-first:** Create XML files directly and iterate with scanner feedback. +- **App-first:** Start from one working Docker template, then copy and refine it for additional apps. +- **Plugin-first:** Publish the plugin manifest first, then add the matching plugin wrapper XML with enough review context. + +## Before review + +Review [Repository XML format](./repository-xml-format.mdx), confirm [Repository information XML](./repository-info-xml.mdx), and use the [XML field reference](./xml-field-reference.mdx) when you need tag-level guidance. The submission should not be sent for moderation review until validation and scan checks pass in the submission portal. diff --git a/docs/unraid-os/using-unraid-to/run-docker-containers/community-applications-submissions/repository-info-xml.mdx b/docs/unraid-os/using-unraid-to/run-docker-containers/community-applications-submissions/repository-info-xml.mdx new file mode 100644 index 00000000000..bdfa86ebc52 --- /dev/null +++ b/docs/unraid-os/using-unraid-to/run-docker-containers/community-applications-submissions/repository-info-xml.mdx @@ -0,0 +1,42 @@ +--- +sidebar_position: 3 +sidebar_label: Repository information XML +--- + +# Repository Information XML + +Every submission repository needs a `ca_profile.xml` file at the repository root. Community Applications uses this file to build the repository profile, show maintainer-level support information, and decide whether the repository can be submitted. + +## Required rules + +- Name the file exactly `ca_profile.xml`. +- Place it at the repository root. +- Include a non-empty `` element. + +If `ca_profile.xml` is missing, or if `` is empty, the submission portal blocks final submission. + +## Recommended profile + +Fill in the fields users and moderators need first: repository overview, icon, home page, and support location. + +```xml + + + Describe what users will find in this repository, which apps or plugins you maintain, and where they should go for support. + + https://raw.githubusercontent.com/example/community-apps/main/icon.svg + https://github.com/example/community-apps + https://forums.unraid.net/topic/example-support-thread + +``` + +## Optional fields + +Only add optional fields when they point to real, maintained destinations: + +- `` for an invite or community server. +- ``, ``, or `` for maintainer or project social links. +- `` and `` for sponsorship. +- `` or `