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
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.
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.
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:
- Remove
pubspec.lockand.dart_toolat the root. - Remove any old
pubspec_overrides.yamlandpubspec.lockinpackages/*. - Run
melos bsagain.
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:
- 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## Unreleasedsection of itsCHANGELOG.md. - 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. - Release the matching
dox-sampletemplate.
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
- It reads the package name and the version from the tag. It stops with an error for an unknown package or a bad version.
- It checks that the version in
packages/<folder>/pubspec.yamlis the tag version. If not, it stops, so runbin/bump.sh <package> <version>and try again. - 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". - 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:
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:
- Open
https://pub.dev/packages/<name>/admin. - Under "Automated publishing", click "Enable publishing from GitHub Actions".
- Repository:
dartondox/dox. - Tag pattern:
<package>-v{{version}}, likedox_core-v{{version}}. Each package has its own pattern. - Tick "Require GitHub Actions environment" and set the environment to
pub.dev. - 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:
- Clone the repos next to the Dox repo, like
../dox-orm.ci/clone-siblings.shclonesdox-orm,dox-auth,dox-openapi,dox-validation,dox-socketio,dox-storage,dox-queue,dox-scheduleranddox-cli. Clonedox-mailer,dox-viewanddox-inertiaby hand when you need them. -
Add them to the root
pubspec_overrides.yamlof the Dox repo. Git ignores this file. Fordox_openapianddox_validation,ci/use-siblings.shwrites it for you. -
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:
- Clone the package next to the Dox repo, like
../dox-http-native. -
Add it to the root
pubspec_overrides.yamlof the Dox repo. Git ignores this file. -
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
Docsworkflow (.github/workflows/docs.yaml) runs on adox_core-v<version>tag, the same tag that publishesdox_core, and runsmike 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 onmain, likegit 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, a404.htmland theCNAMEfile. Sodartondox.devand old links keep working. - The workflow pushes with the built-in
GITHUB_TOKEN. This works becausegh-pagesis 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.