Skip to content

armgit / papra

Public Imported from GitHub
0

The minimalistic document archiving platform.

feat(docs): add versioning and tagging documentation (#797)

Corentin Thomassetb458a22d850d
diff --git a/apps/docs/src/content/docs/04-resources/04-versioning-and-tagging.mdx b/apps/docs/src/content/docs/04-resources/04-versioning-and-tagging.mdx
new file mode 100644
index 00000000..c38063c0
--- /dev/null
+++ b/apps/docs/src/content/docs/04-resources/04-versioning-and-tagging.mdx
@@ -0,0 +1,74 @@
+---
+title: Versioning & Tagging
+description: Understanding Papra's versioning strategy for the monorepo packages and Docker images.
+slug: resources/versioning-and-tagging
+---
+
+Papra uses different versioning strategies depending on the type of package in the monorepo.
+
+## Monorepo Structure
+
+Papra is organized as a monorepo containing multiple packages, each with its own release lifecycle:
+
+- **Library packages** (e.g., `@papra/api-sdk`, `@papra/cli`, `@papra/webhooks`) follow **SemVer** (Semantic Versioning)
+- **Application** (`@papra/app`) follows **CalVer** (Calendar Versioning)
+
+## Semantic Versioning (SemVer)
+
+Library packages follow the standard [SemVer](https://semver.org/) format `MAJOR.MINOR.PATCH`:
+
+- **MAJOR**: Incompatible API changes
+- **MINOR**: Backward-compatible functionality additions
+- **PATCH**: Backward-compatible bug fixes
+
+**Examples:**
+- `@papra/[email protected]`
+- `@papra/[email protected]`
+- `@papra/[email protected]`
+
+## Calendar Versioning (CalVer)
+
+Since **v0.9.6**, the app uses CalVer with the format `YY.M.N`:
+
+- **YY**: Last 2 digits of the year
+- **M**: Month number (1-12, not zero-padded, where 1 = January, 12 = December)
+- **N**: Release number for that month (starting at 0)
+
+**Examples:**
+- `26.1.0`: First release of January 2026
+- `26.1.1`: Second release of January 2026
+- `26.5.11`: 12th release of May 2026
+
+## Git Tags
+
+All packages in the monorepo are tagged and GitHub-released using the format `package-name@version`:
+
+```
+```
+
+:::note[Historical Note]
+Up to and including **v26.0.0**, the application package was named `@papra/docker` and git tags followed the format `@papra/[email protected]`. Starting from **>v26.0.0**, the package was renamed to `@papra/app` and tags follow the format `@papra/[email protected]`.
+:::
+
+## Docker Images
+
+Docker images follow the application package versioning and use the same version numbers. Images are automatically built and pushed to the container registry via CI/CD pipeline when a git tag is pushed.
+
+**Docker image tags:**
+```bash
+# Specific version
+docker pull ghcr.io/papra-hq/papra:26.0.0
+docker pull corentinth/papra:26.0.0
+
+# Latest versions
+docker pull ghcr.io/papra-hq/papra:latest
+docker pull corentinth/papra:latest
+```
+
+See [Self-hosting documentation](/self-hosting/using-docker) for more details on using the Docker images.
+
+The Docker image version always matches the `@papra/app` package version, ensuring consistency across distribution methods.
diff --git a/apps/docs/src/content/navigation.ts b/apps/docs/src/content/navigation.ts
index a3ca23b2..50173f6f 100644
--- a/apps/docs/src/content/navigation.ts
+++ b/apps/docs/src/content/navigation.ts
@@ -94,6 +94,10 @@ export const sidebar = [
label: 'API Endpoints',
slug: 'resources/api-endpoints',
},
+ {
+ label: 'Versioning & Tagging',
+ slug: 'resources/versioning-and-tagging',
+ },
],
},
] satisfies StarlightUserConfig['sidebar'];
diff --git a/apps/docs/src/pages/changelog.astro b/apps/docs/src/pages/changelog.astro
index 7fd005f3..ccd9e76c 100644
--- a/apps/docs/src/pages/changelog.astro
+++ b/apps/docs/src/pages/changelog.astro
@@ -17,7 +17,7 @@ const changelog = parseChangelog(rawChangelog);
>
<p>
Here are the changelogs of the docker images released by Papra.<br />
- For version after v0.9.6, Papra uses Calver as a versioning system with the format YY.MM.N where N is the number of releases in the month starting at 0 (e.g. 25.06.0 is the first release of June 2025).
+ For version after v0.9.6, Papra uses Calver as a versioning system with the format YY.M.N where M is the month number (1-12, not zero-padded, where 1 = January and 12 = December) and N is the number of releases in the month starting at 0 (e.g. 26.5.11 is the 12th release of May 2026).
</p>
diff --git a/packages/app/README.md b/packages/app/README.md
index 815cb801..26be9ef5 100644
--- a/packages/app/README.md
+++ b/packages/app/README.md
@@ -4,10 +4,10 @@ This package contains the Papra application, distributed as Docker images.
## Versioning
-This package uses **CalVer** (Calendar Versioning) with the format `YY.MM.N`:
+This package uses **CalVer** (Calendar Versioning) with the format `YY.M.N`:
- `YY`: Two-digit year
-- `MM`: Two-digit month (zero-padded)
+- `M`: Month number (1-12, not zero-padded, where 1 = January, 12 = December)
- `N`: Release number for that month (starting at 0)
### Examples