view release on metacpan or  search on metacpan

doc/testing.md  view on Meta::CPAN

reads the built `Developer-Dashboard-X.XX.tar.gz` through
`Module::CPANTS::Analyse` and fails unless every kwalitee indicator passes.
Use that tarball-focused check for CPANTS drift; the source tree itself is not
the right surface for this analyzer.
The post-build `t/44-smart-router-two-stage.t` Docker guard now retries one
transient `cpanm` fetch or unpack failure inside its container, so a single
corrupt upstream CPAN download does not fail the repository gate as if it were
deterministic project breakage.
The JavaScript fast-check wrapper is a source-tree fuzz gate. It runs when
`node`, `npm`, `package.json`, and `package-lock.json` are all available, and
it skips in packaged install-test trees that do not ship those checkout-only
JavaScript manifests.
The contributor contract now lives here plus `AGENTS.override.md` and
`agents.md`, not in the top-level product manual in `README.md` or
`Developer::Dashboard.pm`. Those two files stay synced as user-facing product
documentation instead of repeating repo-process rules.
When editing `Developer::Dashboard.pm`, audit the whole shipped manual, not
just the paragraph you touched. In particular, the FAQ wording must describe
real product behavior rather than contributor-only framing, and the `SEE ALSO`
section must use stable local section links instead of brittle private-module
targets that can degrade into broken rendered links. The rest of the top-level
manual should also stay self-contained: prefer plain code references such as
`Developer::Dashboard::PathRegistry` over POD links to private modules, so the
main product guide does not depend on MetaCPAN cross-linking to remain usable.
The same boundary applies to repo-internal Markdown filenames: user-facing
manuals and shipped Perl POD must not send readers to `*.md` files by name.
If a product guide needs to refer to one of those internal documents, describe
it conceptually instead of exposing the repository filename.
When changing startup-path behavior, keep the thin-switchboard performance
contract explicit in tests: `PathRegistry` must reuse a precomputed cwd when
one is supplied, and `EnvLoader` plain-directory traversal must read that same
invocation-scoped cwd from the registry instead of re-running `cwd()` itself.
Markdown files themselves are also checkout-only documentation and must not be
released in the CPAN tarball. Keep the `dist.ini` Markdown exclusion in place,
and treat any shipped `*.md` file as a release-gate failure.
The built distribution should still ship a plain top-level `README`, so CPAN
and kwalitee consumers receive a readme without reopening the checkout-only
documentation set.
The repository root `LICENSE` should stay a single canonical MIT text that
GitHub can classify cleanly.
The same release boundary applies to repo-only verification and bootstrap
folders: `integration/` and the top-level `updates/` checkout helpers are not
installed runtime assets and must stay out of the release tarball. The shipped
runtime contract for `dashboard update` is the user-provided layered command
under `.developer-dashboard/cli/update` or `.developer-dashboard/cli/update.d`,
not the repository's checkout-only `updates/` folder.
Shipped library modules must also load correctly from an installed tarball.
Do not use `FindBin` or source-tree-relative `use lib` bootstrapping inside
repo-owned `.pm` files that are meant to run from the installed distribution.
Keep checkout-only bootstrap logic in entrypoints or tests, then prove the
built distribution with the packaged-tree and blank-environment gates.
The installer guardrails in `t/40-install-bootstrap.t` also treat the Unix
bootstrap target as a compatibility contract: checkout or extracted-tarball
runs must install `.` locally, streamed `curl ... | sh` runs with no checkout
must clone the current GitHub `master` checkout instead of silently falling
back to a stale CPAN release, and the shipped bootstrap package manifests must
carry `tmux` because `dashboard workspace` is a first-party tmux workflow.

Branch and condition reports are still generated and should be used to drive new edge-case tests, especially when adding new runtime modules.

Frontend editor changes should also be checked in a real browser route, not just from HTML output. In particular, the split bookmark editor must load one visible block per section while still recomposing the canonical separator-based source into the ...

JSON behavior is exercised through the shared `Developer::Dashboard::JSON` wrapper, which now uses `JSON::XS`.
Release metadata checks also verify that built tarball runtime prerequisites
explicitly include `JSON::XS`.
When a code change introduces a new runtime Perl module, declare it in all
three release metadata sources in the same change: `Makefile.PL`, `cpanfile`,
and `dist.ini`. The release metadata guardrail fails if a required non-core
runtime module is missing from one of those files, so dependency drift is
caught before `dzil build`, blank-environment installs, or CI releases.
The blank-container `cpanm` gate is an install-verification pass against the
built versioned tarball, so the scripted harness still uses `--notest` there
after the source-tree suite and numeric coverage gates have already exercised
the distribution tests. The gate is still allowed to reject an upstream
dependency whose own test suite no longer passes on the target Perl version.
When that
happens, replace or rework the dependency instead of downgrading the gate.
The current TOML query path uses `TOML::Parser` with explicit boolean
inflation to plain Perl `1` and `0`, because `TOML::Tiny 0.21` no longer
passes its own clean-install test suite on Perl 5.38.
The shell bootstrap regression coverage also checks that the POSIX `cdr` and
`which_dir` helpers decode their JSON payloads through the same Perl
interpreter that generated the shell fragment, which prevents macOS
`JSON::XS` ABI mismatches when `/usr/bin/perl` and `~/perl5` belong to
different Perl builds.
That same shell-bootstrap coverage now also checks the tmux prompt split:
when the shell is inside a `dashboard workspace` tmux session, generated bash,
zsh, POSIX sh, and PowerShell bootstraps must recognize either the explicit
`DEVELOPER_DASHBOARD_TMUX_STATUS=1` flag, the seeded `WORKSPACE_REF`, or the
older compatibility `TICKET_REF`, program a session-local two-line bottom tmux
status block, keep the normal indexed session/window row visible beneath the
dashboard indicator row, suppress inline prompt indicators with
`dashboard ps1 --no-indicators`, and leave ordinary tmux sessions on the
normal inline prompt path.
That helper-staging coverage also executes the staged home-runtime `shell`
helper itself and verifies it emits the same tmux bootstrap, while rerunning
helper staging removes dashboard-managed older flat helpers from
`~/.developer-dashboard/cli/` so upgraded homes converge on the active
`~/.developer-dashboard/cli/dd/` helper tree.
Those shell-helper regression assertions also normalize printed path identity,
so macOS `/var/...` versus `/private/var/...` aliases do not fail otherwise
equivalent `pwd` or `which_dir` output checks.

## README Sync

The canonical product manual lives in the POD inside
`lib/Developer/Dashboard.pm`.

Do not hand-edit `README.md` as a second copy of the same manual. Regenerate
it from the canonical POD with:

```bash
script/sync-readme-from-pod
```

The release metadata gate compares the tracked `README.md` to the generated
output from that helper whenever `pod2markdown` is available on the checkout
PATH. Treat any mismatch as a stop-and-fix release error instead of updating
only one side of the manual.

Command execution paths are exercised through `Capture::Tiny` `capture` wrappers that return exit codes from the capture block itself rather than reading `$?` afterward.