Skip to content

README.md

Latest commit

 

History

History
132 lines (95 loc) · 6.38 KB

README.md

File metadata and controls

132 lines (95 loc) · 6.38 KB
Raw

3D City Database (3DCityDB) v5 documentation

Welcome to the repository of the 3D City Database and software tools documentation starting from version 5.

This page is dedicated to developers. Please find the live version of the user manual here:

🚀 docs.3dcitydb.org 🚀

What's included

This documentation covers the 3D City Database (3DCityDB) v5, a free and open-source package for managing virtual 3D city models:

  • 🏗️ Database schema with Feature, Geometry, Appearance, Metadata, and Codelist modules explained.
  • 🛠️ citydb-tool for data import/export, database operations, ...
  • 📄 Format support for CityGML and CityJSON with CQL2 query language support.
  • 🐳 Docker integration for containerized deployment of database and tools.
  • 🚀 Getting started guides with setup instructions and migration from previous versions.
  • 🔄 Compatibility guide covering CityGML version migration, database upgrades, and format conversion between CityGML 1.0/2.0/3.0 and CityJSON.

Releases and versioning

This documentation uses a branch-based versioning system with automated deployment via GitHub Actions.

Branch naming convention

The version information is derived directly from the branch name, following this pattern:

  • Main branch (main): Deploys as edge version (latest development documentation)
  • Release branches (release-X.Y): Deploy versioned documentation using major.minor format only

Examples:

  • release-1.0 → Documentation version 1.0
  • release-2.3 → Documentation version 2.3
  • release-10.15 → Documentation version 10.15

Release workflow

The documentation deployment follows this workflow:

  1. Main branch (main):

    • Automatically deploys as edge version
    • Represents the latest development documentation

  2. Release branches (release-X.Y):

    • Must be named with major.minor version format (e.g., release-1.0, release-2.3)
    • Automatically deploys versioned documentation
    • Creates or updates corresponding GitHub releases with tag vX.Y
    • The highest version number among all release branches becomes the latest version
    • The latest alias points to the most recent stable release

CI/CD behavior

The GitHub Actions workflow (.github/workflows/ci.yml) automatically:

  • Extracts version from the branch name (main → edge, release-X.Y → X.Y)
  • Validates branch naming format
  • Scans all release-* branches to determine the latest version
  • Deploys documentation using mike for version management
  • Creates GitHub releases with appropriate tags (vX.Y) for release branches
  • Updates the latest alias to point to the highest version number
  • Sets the default documentation version to latest
  • Manages GitHub release "latest" flag to match the highest version

Version management

To create a new documentation release:

  1. Create a new branch named release-X.Y (e.g., release-1.0, release-2.5)
  2. Push the branch - CI will automatically:
    • Deploy the new documentation version
    • Create a GitHub release with tag vX.Y
    • If this is the highest version number, mark it as the new latest

GitHub Releases

The CI automatically creates GitHub releases for each release branch:

  • Tag format: vX.Y (e.g., v1.0, v2.5)
  • Release name: Release vX.Y
  • Latest flag: Automatically set for the highest version number
  • Release notes: Include links to documentation and version information
  • Tag updates: Tags are automatically updated to point to the latest commit on release branches
  • No releases for edge: Main branch (edge) does not create GitHub releases

Updating content of an existing release

To update documentation content for an existing release version:

  1. Switch to the release branch: Check out the specific release-X.Y branch you want to update
  2. Make your changes: Edit the documentation files in the docs/ directory as needed
  3. Commit changes: Commit your updates to the release branch
  4. Push updates: Push the changes to the remote repository
  5. Automatic redeployment: The CI workflow will automatically trigger and:
    • Redeploy the updated documentation for that version
    • Update the git tag to point to the latest commit
    • Update the corresponding GitHub release

Important notes:

  • The version is automatically derived from the branch name
  • GitHub releases and git tags are created/updated automatically for release branches
  • Git tags are force-updated to always point to the latest commit on release branches
  • Content updates preserve the existing version number and aliases
  • The documentation will be redeployed with the same version identifier
  • If updating the current latest version, the changes will be immediately visible on the default documentation site

PR preview builds

Every pull request from a branch within this repository gets an ephemeral documentation preview so reviewers can see the rendered result before merging.

  • URL: https://docs.3dcitydb.org/pr/<PR-number>/ — a bot comment with the link is posted on the PR and updated on every push.
  • Not in the version menu: previews are published straight into the pr/ folder on the gh-pages branch and never touch versions.json, so they do not appear in the version dropdown at the top of the docs. They also carry a preview banner and are marked noindex.
  • Automatic cleanup: a scheduled job removes previews of closed/merged PRs once a week (Mondays), and can also be run manually via workflow_dispatch.
  • Fork PRs are excluded for now (a fork could inject content into the docs site).

The feature is implemented as a build/deploy split so it can be extended to forks later:

  • .github/workflows/pr-preview-build.yml — builds the preview with mkdocs.pr.yml using a read-only token (safe for untrusted code) and uploads it as an artifact.
  • .github/workflows/pr-preview-deploy.yml — publishes the artifact to gh-pages under pr/<num>/ and comments on the PR, using a write token via workflow_run.
  • .github/workflows/pr-preview-cleanup.yml — the weekly cleanup sweep.

mkdocs.pr.yml is a small overlay over mkdocs.yml (via INHERIT) that injects the per-PR site_url, enables the overrides/main.html banner, and hides the version selector — the production build (mkdocs.yml) is unchanged.