docs: add getting-started.md, expand README#79
Conversation
- 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>
3da34b4 to
5964f44
Compare
Codecov Report✅ All modified and coverable lines are covered by tests. 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. 🚀 New features to boost your workflow:
|
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>
There was a problem hiding this comment.
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.mdwalkthrough 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.mditem fromTODO.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.
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>
There was a problem hiding this comment.
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.
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>
There was a problem hiding this comment.
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.
Summary
getting-started.md: a ten-minute walkthrough that takes a fresh MySQL database from empty to a managed schema. Covers install, DSN setup, thedump → edit → plan → apply → re-plan emptyround-trip, the--allow-dropopt-in for destructive ops, common flags, and the desired-side directives (renamed-from/convert-charset/execute).README.mdwas 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 atgetting-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-completedgetting-started.mdline.Test plan
cmd/myschema --helpandAGENTS.md"In scope (v1)".🤖 Generated with Claude Code