Skip to content

docs: add getting-started.md, expand README#79

Merged
winebarrel merged 4 commits into
mainfrom
docs-getting-started-and-readme
May 5, 2026
Merged

docs: add getting-started.md, expand README#79
winebarrel merged 4 commits into
mainfrom
docs-getting-started-and-readme

Conversation

@winebarrel

Copy link
Copy Markdown
Owner

Summary

  • New getting-started.md: a ten-minute walkthrough that takes a fresh MySQL database from empty to a managed schema. Covers install, DSN setup, the dump → edit → plan → apply → re-plan empty round-trip, the --allow-drop opt-in for destructive ops, common flags, and the desired-side directives (renamed-from / convert-charset / execute).
  • README.md was a 21-line stub; expand to a one-screen overview with a 5-line quickstart, subcommand list, feature inventory, requirements, and a docs index pointing at getting-started.md / AGENTS.md / CAVEATS.md / PARTITIONING.md. Keeps depth in the dedicated files rather than duplicating it on the front page.
  • TODO.md: drop the now-completed getting-started.md line.

Test plan

  • No code changes; doc-only edit.
  • Cross-checked feature/flag inventory in README against cmd/myschema --help and AGENTS.md "In scope (v1)".

🤖 Generated with Claude Code

Copilot AI review requested due to automatic review settings May 5, 2026 11:43
- New `getting-started.md`: ten-minute walkthrough taking a fresh
  MySQL database from empty to a managed schema. Covers install,
  DSN setup, dump → edit → plan → apply round-trip, the
  `--allow-drop` opt-in for destructive ops, common flags, and
  the desired-side directives (`renamed-from` / `convert-charset` /
  `execute`).
- `README.md` was a 21-line stub; expand to a one-screen overview
  with a 5-line quickstart, subcommand list, feature inventory,
  requirements, and a docs index pointing at getting-started /
  AGENTS / CAVEATS / PARTITIONING. Keeps depth in the dedicated
  files instead of duplicating it on the front page.
- `TODO.md`: drop the now-completed `getting-started.md` line.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@winebarrel winebarrel force-pushed the docs-getting-started-and-readme branch from 3da34b4 to 5964f44 Compare May 5, 2026 11:44
@codecov

codecov Bot commented May 5, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 86.62%. Comparing base (48b4461) to head (3399848).

Additional details and impacted files
@@           Coverage Diff           @@
##             main      #79   +/-   ##
=======================================
  Coverage   86.62%   86.62%           
=======================================
  Files          30       30           
  Lines        3237     3237           
=======================================
  Hits         2804     2804           
  Misses        267      267           
  Partials      166      166           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Replace the bare three-bullet Subcommands list with a Usage
section that shows concrete invocation examples per subcommand —
dump, plan, apply — covering the common flag combinations
(filters, drop policy, online-DDL hints, bulk-alter, pre-sql,
split). Adds the up-front DSN setup line so a reader can copy a
working command without scrolling back to the quickstart.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This doc-only PR expands the project’s onboarding and top-level documentation so new users can discover myschema’s workflow and related guides more quickly.

Changes:

  • Adds a new getting-started.md walkthrough covering install, DSN setup, the dump/plan/apply workflow, drop policies, common flags, and directives.
  • Replaces the minimal README with a fuller overview of subcommands, features, requirements, and links to deeper docs.
  • Removes the completed getting-started.md item from TODO.md.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 6 comments.

File Description
TODO.md Removes the completed getting-started documentation task.
README.md Expands the front page into a quickstart, feature summary, requirements list, and docs index.
getting-started.md Adds a step-by-step introductory guide for first-time users.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment thread README.md
Comment thread getting-started.md Outdated
Comment thread getting-started.md Outdated
Comment thread getting-started.md Outdated
Comment thread getting-started.md Outdated
Comment thread getting-started.md Outdated
Six factual errors flagged by review #4227632041; fixed all after
verifying each against the actual CLI output / source:

- README + getting-started flag table: "every flag has matching
  MYSCHEMA_* env var" was overstated. `dump.go`'s `SplitDir` has
  no env tag. Tightened to "most flags … (--split is CLI-only)".
- getting-started "dump output" section: the wording was
  "plain CREATE TABLE / CREATE VIEW", but `model.TableToSQL`
  emits standalone `CREATE INDEX` for each secondary index and
  `ALTER TABLE … ADD CONSTRAINT` for each FK — confirmed against
  `model/table.go:217-225`. Reword to describe what `dump`
  actually emits.
- Walkthrough plan header: showed "Plan: 0 → 2 table(s), 0
  view(s)", but `cmd/command/plan.go:20` formats it as
  "-- Plan for database <db> (<current-counts>)". Replace the
  fake header with the real format and re-capture the body
  (CREATE TABLE → CREATE UNIQUE INDEX → CREATE TABLE →
  CREATE INDEX → ALTER TABLE ADD CONSTRAINT) by running the
  walkthrough's desired.sql against a real MySQL 8.0.
- "-- No changes." had a stray period; the CLI prints
  "-- No changes" without one. Fixed both occurrences.
- Walkthrough drop-policy demo: previously showed both the
  unsuppressed and the `-- skipped:` form on one plan output,
  which never happens — without `--allow-drop` the unsuppressed
  line isn't emitted. Split into two plan invocations: the
  default-mode skip-only output, then the `--allow-drop=column`
  output.

Captured the actual outputs by running the walkthrough's desired
SQL against a fresh local MySQL 8.0 — the doc samples now match
what a reader will see verbatim.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 4 comments.


💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment thread README.md Outdated
Comment thread getting-started.md Outdated
Comment thread README.md Outdated
Comment thread getting-started.md
Address Copilot review on PR #79 (3 of 4 items): three sites in
README and getting-started described `--include`/`--exclude` as
table-only filters, but `diff_all.go`'s filterViews calls the same
FilterOptions.MatchName helper, so the flags scope views too.
Updated all three callsites to say "table and view names".

Skipping the source-build PATH note (#4) — install instructions
are slated to change.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated no new comments.


💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

@winebarrel winebarrel merged commit 32fd267 into main May 5, 2026
9 checks passed
@winebarrel winebarrel deleted the docs-getting-started-and-readme branch May 5, 2026 12:05
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants