Test the latest DASCore pre-release

Try the newest DASCore pre-release on an existing project’s code and data in an isolated environment, compare it with the project’s current version, and draft reports of what breaks.

Keywords

beta, pre-release, testing, migration, bug report

This procedure tries the newest DASCore pre-release on a real project without changing the project’s environment, code, or data, and turns what breaks into reports the DASCore developers can act on. An agent can follow it directly from this page; the project does not need the pre-release installed first.

Throughout, <project-python> is the project’s existing interpreter and <beta-python> is the absolute path of the new environment’s interpreter. Use each interpreter where a step names it, even if other instructions say to use the project’s interpreter for every command, and never run an install command with <project-python> during this procedure.

Workflow

Isolate the code and data. Make a separate filesystem copy of the project’s working tree, including uncommitted and untracked files, and replace any symbolic links that point outside it with copies; a git worktree alone checks out a commit, and a new branch in the original checkout is not isolation. Copy a bounded amount of representative data, a few files or minutes, into two scratch directories, one per version, and point the project’s configuration or tests at them. Skip any test whose data paths cannot be redirected. Run every step below in the copies, and send all outputs to temporary directories: DASCore writes index files next to the data, and files written by a pre-release may not be readable by older versions.
Record the baseline. With <project-python>, first check that the project’s own modules import from the copy rather than from an editable install of the original, and that its data paths resolve to the first data copy. Then record dascore.__version__, the result of the project’s tests if it has any, and the outputs of a few representative operations (reading, spool selection, chunking, processing) on the first data copy. Save these outputs now, before any migration, since migrated code may not run on the old version.
Find the newest pre-release. List DASCore’s versions on PyPI and pick the newest pre-release (a version with a, b, or rc). If a stable release is newer, tell the user and ask which to test. Note its Requires-Python. If PyPI cannot be reached, stop and say so.
Build an isolated environment. Create a new environment with a Python version the pre-release supports, record its interpreter as <beta-python>, and install the project’s dependencies the way the project declares them (its package and test extras, a requirements file, or its lock file), together with the exact version from step 3 in one resolver call, so that only DASCore comes from a pre-release. For an installable package with a test extra:
```
<beta-python> -m pip install -e "<project-copy>[test]" "dascore[all]==<newest>"
```
For a uv environment, use uv pip install --python <beta-python> ... with the same arguments. If the resolver refuses because of the project’s own pins, report that conflict rather than relaxing them.
Confirm the install. Run <beta-python> -c "import dascore; print(dascore.__version__, dascore.__file__)" and check that it reports the version from step 3 from inside the new environment. Use <beta-python> for everything that follows.
Migrate the copy. Run <beta-python> -m dascore skills and read any migration skill covering the move from the project’s version, such as migrate-to-v1. Apply only its code changes, to the copy. Do not upgrade environments, and do not delete, rewrite, or re-index the user’s data or index files. Keep the changes minimal and separate from unrelated edits.
Run the tests. Run the project’s tests with <beta-python>, asking the user before running slow or network-dependent suites. Sort each failure into the project’s own code needing migration, a change a migration guide covers, or a likely DASCore problem.
Compare results. Run the representative operations with <beta-python> on the second data copy and compare them with the baseline from step 2: shapes, coordinates, units, attributes, and data values. A difference no migration guide explains is a finding even if nothing raised.
Reduce each finding. For each likely DASCore problem, write the smallest script that reproduces it, preferably on an example from dc.get_example_patch() or dc.get_example_spool(). Search both open and closed issues for an existing report.
Draft the reports. Draft one report per problem containing the DASCore version, Python version, operating system, the reproducing script, the expected and actual results, and the previous version’s behavior where it differs. Show the drafts to the user. Do not open issues, post, or share data without the user’s approval, and leave out paths, credentials, and data the user has not cleared for sharing.
Summarize. Report what was tested, what passed, what changed under migration, and which reports were drafted. Confirm that the project’s original environment, code, and data are as they were, and say where the copies and the new environment are so the user can remove them.

Problems with a migration guide itself, such as a missing or wrong entry, are worth reporting too. Questions and general feedback belong in the discussions.