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.mdxnew file mode 100644index 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`:++```+@papra/[email protected]+@papra/[email protected]+@papra/[email protected]+@papra/[email protected]+```++:::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.tsindex 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.astroindex 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.mdindex 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