Skip to content

Contribute

This page shows how to work on Dox: set up the repo, run the tests, release packages and update the docs.

To send a change, fork the repo and open a pull request. The first part of this page is all you need for that. The release parts are for maintainers.

Setting up local development

1. Clone the repo

git clone git@github.com:dartondox/dox.git

2. Install melos

The repo is a Dart pub workspace, and melos runs the commands for all packages. Its config is in the root pubspec.yaml, under melos:. You need Dart 3.13 or newer.

dart pub global activate melos

3. Run melos bootstrap

This runs one dart pub get at the root and links all local packages, so there is one pubspec.lock for the whole repo.

melos bs

4. Run the tests and checks

Run these before you open a pull request. They are the same checks CI runs:

# Run all tests.
# Use `melos run test`. `melos test` is a built-in melos command.
melos run test

# Analyze and check format (same as CI)
melos run analyze
melos run format_check

If the project does not run

If melos bs fails or the packages do not resolve, start clean:

  1. Remove pubspec.lock and .dart_tool at the root.
  2. Remove any old pubspec_overrides.yaml and pubspec.lock in packages/*.
  3. Run melos bs again.

Release (maintainers)

The Release GitHub workflow (.github/workflows/publish.yaml) publishes one package to pub.dev. Each package has its own version and its own tag, in the form <package>-v<version>. The workflow uses pub.dev automated publishing, so it needs no token or secret.

Steps

The full guide is RELEASING.md in the repo. In short, for each package that changed:

  1. Run bin/bump.sh <package> <version>. It sets the version of that package only. If the package needs a newer sibling, raise that constraint by hand. Then close the ## Unreleased section of its CHANGELOG.md.
  2. Merge the release PR, then push the tag <package>-v<version>. This publishes that package to pub.dev. Release in dependency order: dox_annotation, dox_cache, dox_builder, dox_core.
  3. Release the matching dox-sample template.

A builder-only fix needs a dox_builder release only. It does not need a dox_core release.

The native packages (dox_http_native, dox_postgres_native, dox_mysql_native) are not in this repo. See Native packages below. dox_orm, dox_migration, dox_socketio, dox_storage, dox_queue, dox_queue_database, dox_scheduler, dox_inertia, dox_view and dox_mailer are not in this repo either. See Packages in other repos.

New package only: a new package must first exist on pub.dev, so publish its first version by hand with dart pub publish. Then turn on pub.dev automated publishing for it. See One-time setup.

What the workflow does

  1. It reads the package name and the version from the tag. It stops with an error for an unknown package or a bad version.
  2. It checks that the version in packages/<folder>/pubspec.yaml is the tag version. If not, it stops, so run bin/bump.sh <package> <version> and try again.
  3. It runs the tests, and they must pass. Then it checks that the sibling packages it needs are on pub.dev. If not, it stops with "release first".
  4. It checks that one package with a dry run, then publishes it.

A tag for a version that is already on pub.dev is skipped. So if a run fails, fix the problem and click "Re-run jobs".

To see the packages in publish order on your machine:

python3 bin/publish_order.py

Dry run

If you want to check a release without publishing, open Actions > Release > "Run workflow" and pick one package, or all. It runs dart pub publish --dry-run and publishes nothing. Warnings, like a missing CHANGELOG entry, show in yellow and do not fail the run.

One-time setup

Do this once for each published package, and for every new package before its first tag. python3 bin/publish_order.py lists the packages.

On pub.dev:

  1. Open https://pub.dev/packages/<name>/admin.
  2. Under "Automated publishing", click "Enable publishing from GitHub Actions".
  3. Repository: dartondox/dox.
  4. Tag pattern: <package>-v{{version}}, like dox_core-v{{version}}. Each package has its own pattern.
  5. Tick "Require GitHub Actions environment" and set the environment to pub.dev.
  6. Save.

On GitHub, in dartondox/dox > Settings > Environments, there must be an environment named pub.dev, because the publish job runs in it. Optional: add yourself as a required reviewer, and allow only the tags dox_annotation-v*, dox_builder-v*, dox_cache-v* and dox_core-v*.

Packages in other repos

Package Repo
dox (the CLI) dartondox/dox-cli
dox_orm, dox_migration, dox_cache_database dartondox/dox-orm
dox_auth dartondox/dox-auth
dox_openapi dartondox/dox-openapi
dox_validation dartondox/dox-validation
dox_socketio dartondox/dox-socketio
dox_storage dartondox/dox-storage
dox_queue, dox_queue_database dartondox/dox-queue
dox_scheduler dartondox/dox-scheduler
dox_inertia dartondox/dox-inertia
dox_view dartondox/dox-view
dox_mailer dartondox/dox-mailer

The packages in this repo use them from pub.dev. dox_core uses dox_openapi and dox_validation. The database tests (Postgres, MySQL, MariaDB, SQLite) run in dox-orm. CI in this repo tests against their newest code: it runs ci/clone-siblings.sh, then ci/use-siblings.sh.

To work on one of them and Dox together:

  1. Clone the repos next to the Dox repo, like ../dox-orm. ci/clone-siblings.sh clones dox-orm, dox-auth, dox-openapi, dox-validation, dox-socketio, dox-storage, dox-queue, dox-scheduler and dox-cli. Clone dox-mailer, dox-view and dox-inertia by hand when you need them.
  2. Add them to the root pubspec_overrides.yaml of the Dox repo. Git ignores this file. For dox_openapi and dox_validation, ci/use-siblings.sh writes it for you.

    dependency_overrides:
      dox_openapi:
        path: ../dox-openapi
      dox_validation:
        path: ../dox-validation
    
  3. Run dart pub get.

The apps in examples/ already use these clones (their pubspec_overrides.yaml), so clone them before you run an example. In the other repo, a pubspec_overrides.yaml that points to ../dox/packages/... uses your local Dox packages.

Each of these repos has its own version. To release one, push a v<version> tag in that repo.

Native packages

The three native packages live in their own repos:

Package Repo
dox_http_native dartondox/dox-http-native
dox_postgres_native dartondox/dox-postgres-native
dox_mysql_native dartondox/dox-mysql-native

Dox uses them from pub.dev. Their build hooks download ready-built libraries, so you do not need Rust to work on Dox. You only need these steps if you change a native package.

To work on a native package and Dox together:

  1. Clone the package next to the Dox repo, like ../dox-http-native.
  2. Add it to the root pubspec_overrides.yaml of the Dox repo. Git ignores this file.

    dependency_overrides:
      dox_http_native:
        path: ../dox-http-native
    
  3. Run dart pub get.

Each native package is released from its own repo, with its own version. Push a v<version> tag in that repo. Its CI builds the libraries, uploads them, fills the hashes and publishes the package to pub.dev. Then raise the version constraint in the Dox packages that use it.

Docs

The docs site is https://dartondox.dev. It is built with MkDocs Material and mike, which keeps one folder per version on the gh-pages branch.

URL What it is
/3.x/... 3.x docs, built from main
/latest/... a copy of the newest version (now 3.x)
/ redirects to /latest/
old links like /the-basic/routing/ redirect to /latest/the-basic/routing/

Write and preview

python3 -m venv .venv
.venv/bin/pip install -r requirements-docs.txt
.venv/bin/mkdocs serve           # live preview of this branch
.venv/bin/mkdocs build --strict  # the same build as CI. Broken links fail.

hooks/docs_hooks.py runs during the build. It makes the changelog page from packages/*/CHANGELOG.md, and writes llms.txt and llms-full.txt.

Every pull request that changes the docs runs the Docs check workflow (.github/workflows/docs-check.yaml). It has three checks:

  • mkdocs build --strict
  • a spell check: codespell docs --skip "*.svg,*.png,*.ico,*.css,*.js" --ignore-words .codespell-ignore
  • ci/check-no-tabs.sh: the docs must not use content tabs

Deploy

  • 3.x deploys with each release. The Docs workflow (.github/workflows/docs.yaml) runs on a dox_core-v<version> tag, the same tag that publishes dox_core, and runs mike deploy --update-aliases 3.x latest. So docs for a feature that is not released yet stay off the site.
  • If you want to deploy the docs only (a typo fix, or the docs of a package from another repo that was just released), push a docs-v<version> tag on main, like git tag docs-v3.0.1-1 && git push origin docs-v3.0.1-1. It publishes no package and runs no tests.
  • After each deploy, the workflow writes small redirect pages for the old root links, the root index.html, a 404.html and the CNAME file. So dartondox.dev and old links keep working.
  • The workflow pushes with the built-in GITHUB_TOKEN. This works because gh-pages is not a protected branch.

New major version

When 4.x starts, deploy it with mike deploy --update-aliases 4.x latest. Keep a v3.x branch and add 3.x to the workflow input, so 3.x can still be fixed.