Skip to content

docs: normalize Rails 7 migration pattern docs (WA-DOC-018)#1125

Open
kitcommerce wants to merge 1 commit intonextfrom
issue-909-doc-018-normalize-migration-docs
Open

docs: normalize Rails 7 migration pattern docs (WA-DOC-018)#1125
kitcommerce wants to merge 1 commit intonextfrom
issue-909-doc-018-normalize-migration-docs

Conversation

@kitcommerce
Copy link
Contributor

Summary

Normalizes all docs in docs/rails7-migration-patterns/ to a consistent five-section structure and updates the README index.

Closes #909 (WA-DOC-018)


Changes

Section normalization (all 11 pattern docs)

Each pattern doc now has these canonical ## sections in order:

  1. Symptom — observable problem
  2. Root cause — why it happens
  3. Detection — how to identify if you're affected
  4. Fix — how to resolve it
  5. References / Links — upstream docs, related issues

Heading renames

  • Root CauseRoot cause (assets-pipeline, bigdecimal, sprockets-manifest)
  • See AlsoReferences (assets-pipeline)
  • Workarea PR (or Issue)References / Links (url-routing-helpers)
  • Workarea PR / IssueReferences (middleware-stack-ordering, sprockets-manifest)
  • Migration StepsFix (webpacker-to-sprockets-4)

New sections added

Docs that were status reports / audit notes rather than structured patterns received
the full Symptom/Root cause/Detection/Fix preamble:

  • webpacker-to-sprockets-4.md
  • jsbundling-rails-esbuild.md
  • deprecation-sweep-results.md
  • error-reporting.md
  • load-defaults-7-2.md
  • rails-7-2-notes.md
  • zeitwerk-notes.md

README index

Replaced the partial bullet list with a full Markdown table linking all 11 pattern docs
with one-line descriptions.


Client impact

None — documentation changes only.


Verification Plan

  1. Confirm each of the 11 pattern docs has all five required ## sections:

    for f in docs/rails7-migration-patterns/*.md; do
      echo "=== $(basename $f) ==="
      grep "^## " "$f" | grep -iE "symptom|root cause|detection|fix|references"
    done

    Expected: each non-README file prints all five sections.

  2. Confirm README links resolve — all filenames in the table exist:

    ls docs/rails7-migration-patterns/
  3. Confirm no hardcoded local paths remain:

    grep -rn 'Users/Shared/openclaw' docs/rails7-migration-patterns/

    Expected: no output.

…e (WA-DOC-018)

- Ensure all 11 pattern docs have: Symptom, Root cause, Detection, Fix,
  and References/Links sections
- Normalize heading casing (e.g. 'Root Cause' → 'Root cause', 'See Also' → 'References')
- Rename section aliases to canonical names:
  - 'Workarea PR (or Issue)' → 'References / Links'
  - 'See Also' → 'References'
  - 'Migration Steps' → 'Fix'
- Add missing Symptom/Root cause/Detection/Fix/References sections to:
  - webpacker-to-sprockets-4.md
  - jsbundling-rails-esbuild.md
  - deprecation-sweep-results.md
  - error-reporting.md
  - load-defaults-7-2.md
  - rails-7-2-notes.md
  - zeitwerk-notes.md
- Replace hardcoded local paths with generic placeholders (none found)
- Update README.md with full index table linking all pattern docs
  with one-line descriptions

Closes #909 (WA-DOC-018)
@kitcommerce kitcommerce added gate:build-passed Build gate passed review:architecture-pending Review in progress review:simplicity-pending Review in progress review:security-pending Review in progress review:rails-conventions-pending Rails conventions review in progress labels Mar 17, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

gate:build-passed Build gate passed review:architecture-pending Review in progress review:rails-conventions-pending Rails conventions review in progress review:security-pending Review in progress review:simplicity-pending Review in progress

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant