Skip to content

Parallel Tests 5.7 Prepare Documentation Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Align parallel RSpec database preparation documentation with parallel_tests 5.7 behavior.

Architecture: Keep upstream parallel:prepare behavior unchanged. Update maintenance guidance to make db/schema.rb freshness an explicit precondition and distinguish schema loading from schema dumping.

Tech Stack: Markdown, Rails rake tasks, parallel_tests 5.7

Task 1: Correct Parallel Database Preparation Guidance

Files: - Modify: docs/backend_tutorials/parallel-rspec-setup.md:97-117

  • [ ] Step 1: Confirm outdated wording exists

Run:

rg -n "After running any database migration|equivalent to running.*schema:load" docs/backend_tutorials/parallel-rspec-setup.md

Expected: matches identify migration guidance and schema-load equivalence in the Maintenance section.

  • [ ] Step 2: Update migration guidance

Replace the Maintenance subsection with:

### Update All Test Databases After Migration

Run the normal migration or Easy8 installation workflow first so that `db/schema.rb` contains the current schema. Then load that schema into all parallel test databases:

```bash
bundle exec rake parallel:prepare
```

`parallel_tests` 5.7 does not run `db:schema:dump` during `parallel:prepare`. The command purges and loads each parallel test database from the existing `db/schema.rb`, so the schema file must already be current.

Keep the following Reset All Test Databases subsection and its commands unchanged.

  • [ ] Step 3: Verify obsolete claim is gone

Run:

rg -n "db:schema:dump|schema file must already be current|parallel:prepare" docs/backend_tutorials/parallel-rspec-setup.md

Expected: output states that parallel:prepare does not run db:schema:dump, requires a current schema file, and retains prepare/reset commands.

  • [ ] Step 4: Review documentation diff

Run:

git diff --check && git diff -- docs/backend_tutorials/parallel-rspec-setup.md

Expected: git diff --check exits successfully; diff changes only Maintenance wording and keeps reset commands intact.

  • [ ] Step 5: Commit documentation update
git add docs/backend_tutorials/parallel-rspec-setup.md
git commit -m "docs(gems): clarify parallel database preparation (refs #683236)"