Repository navigation
📝 improve project documentation and user guidance - #132
Merged
Merged
Conversation
…instructions and examples
… README with migration planning details
…r improved accessibility
WalkthroughAdds and expands contributor and user documentation (README, docs/*, AGENTS.md), updates Changes
Sequence Diagram(s)sequenceDiagram
participant User as User
participant Assistant as Assistant (uses SKILL)
participant CLI as mysql2sqlite CLI
participant DBs as MySQL/MariaDB & SQLite
User->>Assistant: Request transfer (intent, constraints)
Assistant->>Assistant: Apply skills/mysql-to-sqlite3/SKILL.md
Assistant-->>User: Assumptions + single command + caveats
User->>CLI: Run generated command (local or Docker)
CLI->>DBs: Connect to source (MySQL/MariaDB) and target (SQLite)
DBs-->>CLI: Schema/data transfer
CLI-->>User: Exit status and verification suggestions
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Suggested labels
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## master #132 +/- ##
=======================================
Coverage 98.83% 98.83%
=======================================
Files 8 8
Lines 946 946
=======================================
Hits 935 935
Misses 11 11 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@AGENTS.md`:
- Around line 21-23: Update the guidance in AGENTS.md to remove the mandatory
`_cmd` suffix rule and instead instruct contributors to follow the repository's
existing CLI naming convention (use the same entrypoint name used elsewhere,
e.g., the top-level `cli` function) and keep names consistent across commands;
specifically, replace the `_cmd` suffix recommendation with text that prefers
reusing the established `cli` entrypoint or a single consistent descriptive name
for command callbacks and ensure examples/reference points to the project’s
existing `cli` symbol so contributors avoid mixed conventions.
- Line 28: The sentence "Write `pytest` unit tests using alongside the feature
under `tests/unit/` and integration cases under `tests/func/`." is grammatically
broken—update the guidance in AGENTS.md to a clear sentence such as: "Write
`pytest` unit tests for the feature under `tests/unit/` and integration tests
under `tests/func/`." Replace the existing phrase "using alongside" with this
corrected wording to make the testing instructions unambiguous.
In `@skills/mysql-to-sqlite3/SKILL.md`:
- Line 58: Update the phrasing in the sentence that currently reads "give the
install command" to instead read "give the installation command" in the SKILL.md
content so the wording is clearer and more natural (replace the exact fragment
"give the install command" with "give the installation command").
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI
Review profile: CHILL
Plan: Pro
Run ID: 01aef4c5-6f97-4fe5-85ee-a96d079f16e0
📒 Files selected for processing (7)
.github/copilot-instructions.md.gitignoreAGENTS.mdREADME.mddocs/README.rstdocs/index.rstskills/mysql-to-sqlite3/SKILL.md
There was a problem hiding this comment.
Pull request overview
This PR focuses on improving end-user and contributor documentation for mysql2sqlite, aligning README/Sphinx docs and adding agent/contributor guidance to make onboarding and common workflows clearer.
Changes:
- Rewrites/expands
README.mdand Sphinx docs with prerequisites, installation methods, quick start, recipes, and an options reference. - Adds a new contributor guidelines document (
AGENTS.md) and a user-facing agent skill (skills/mysql-to-sqlite3/SKILL.md). - Updates internal Copilot instructions and
.gitignoreto reflect new docs/process guidance and local tooling artifacts.
Reviewed changes
Copilot reviewed 6 out of 7 changed files in this pull request and generated 8 comments.
Show a summary per file
| File | Description |
|---|---|
| skills/mysql-to-sqlite3/SKILL.md | Adds a user-facing “transfer assistant” skill with command templates and caveats. |
| docs/index.rst | Refreshes Sphinx landing page text, adds common tasks, and updates badges/links. |
| docs/README.rst | Major expansion of Sphinx usage docs with recipes and an option summary table. |
| README.md | Major rewrite for clearer onboarding, recipes, and a consolidated option table. |
| AGENTS.md | Adds contributor workflow/coding/testing guidelines. |
| .gitignore | Ignores new local tool/editor artifacts. |
| .github/copilot-instructions.md | Updates internal guidance to keep user-facing docs consistent when adding CLI options. |
…d collation options
There was a problem hiding this comment.
🧹 Nitpick comments (1)
README.md (1)
33-35: Consider reducing version-list drift risk in docs.Line 33 hard-codes tested server versions; this can age quickly. Consider linking this statement to the CI workflow matrix (or adding a “check CI matrix for latest” note) to reduce maintenance churn.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@README.md` around lines 33 - 35, Replace the hard-coded server-version sentence ("The project CI tests MySQL 5.5, 5.6, 5.7, 8.0, and 8.4, plus MariaDB …") with a pointer to the source of truth for tested versions: either a direct link to the CI workflow matrix (the GitHub Actions matrix) or a short note like "see CI matrix for current tested versions"; update the README section containing that sentence so it dynamically references the CI matrix instead of enumerating versions to avoid drift.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In `@README.md`:
- Around line 33-35: Replace the hard-coded server-version sentence ("The
project CI tests MySQL 5.5, 5.6, 5.7, 8.0, and 8.4, plus MariaDB …") with a
pointer to the source of truth for tested versions: either a direct link to the
CI workflow matrix (the GitHub Actions matrix) or a short note like "see CI
matrix for current tested versions"; update the README section containing that
sentence so it dynamically references the CI matrix instead of enumerating
versions to avoid drift.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI
Review profile: CHILL
Plan: Pro
Run ID: c8c614b0-0aac-40ba-901a-8cd1a80e861b
📒 Files selected for processing (4)
AGENTS.mdREADME.mddocs/README.rstskills/mysql-to-sqlite3/SKILL.md
✅ Files skipped from review due to trivial changes (1)
- docs/README.rst
…ed MySQL and MariaDB versions
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/README.rst`:
- Around line 277-278: Update the README.rst sentence about ``--strict`` to
state the actual fallback behavior: mention that ``--strict`` requires SQLite
3.37+ but when running on older SQLite the tool logs a warning and automatically
falls back to creating non-STRICT tables (rather than hard-failing), and
indicate the user can rerun on a newer SQLite to get STRICT schemas or
explicitly request failure if available.
- Around line 212-215: Update the option metavars for the CLI flags
-t/--mysql-tables and -e/--exclude-mysql-tables to match Click's repeated-value
convention: replace the displayed `TUPLE` metavars with `TEXT` (or `TEXT...` /
`TEXT [TEXT ...]`) so the docs show the same repeated-TEXT semantics Click
exposes; adjust the two option lines for ``-t, --mysql-tables`` and ``-e,
--exclude-mysql-tables`` in docs/README.rst to use that metavariable and keep
the existing descriptions about transfer/inheritance of foreign keys.
In `@README.md`:
- Line 240: Update the README sentence about `--strict`/STRICT to reflect actual
runtime behavior: instead of saying "`--strict` requires SQLite 3.37 or newer.
If SQLite rejects a STRICT schema, rerun without `--strict`," document that the
program will auto-disable strict mode and emit a warning on older SQLite
versions (so users do not need to manually rerun without `--strict`); mention
the `--strict` flag and the STRICT schema behavior to make the change clear.
- Around line 204-205: Update the README entries for the flags to match the CLI
behavior: change the metavar from `TUPLE` to `TEXT` (or otherwise indicate
repeated TEXT values) for `--mysql-tables` and `--exclude-mysql-tables` so docs
reflect that these options accept multiple `TEXT` values (per the CLI
`multiple=True`, `metavar="TEXT"`), and add a short note that using multiple
occurrences is supported and implies no foreign key transfer.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI
Review profile: CHILL
Plan: Pro
Run ID: 6d1ab494-247f-4aa6-8407-6091d7814637
📒 Files selected for processing (5)
AGENTS.mdREADME.mddocs/README.rstdocs/index.rstskills/mysql-to-sqlite3/SKILL.md
…bility with older versions
Owner
Author
|
@coderabbitai resume |
✅ Actions performedReviews resumed. |
There was a problem hiding this comment.
♻️ Duplicate comments (2)
docs/README.rst (1)
212-215:⚠️ Potential issue | 🟡 MinorUse CLI-accurate metavars for table selection options.
The past review comment on these lines remains unaddressed.
TUPLEdoes not reflect how Click exposes these options (TEXTwith repeated values). Align the terminology to avoid user confusion.📝 Suggested documentation fix
- * - ``-t``, ``--mysql-tables TUPLE`` - - Transfer only the listed tables. Implies no foreign key transfer. - * - ``-e``, ``--exclude-mysql-tables TUPLE`` - - Transfer every table except the listed tables. Implies no foreign key transfer. + * - ``-t``, ``--mysql-tables TEXT`` + - Transfer only the listed tables (repeat values after the flag). Implies no foreign key transfer. + * - ``-e``, ``--exclude-mysql-tables TEXT`` + - Transfer every table except the listed tables (repeat values after the flag). Implies no foreign key transfer.As per coding guidelines, "Update
README.md,docs/README.rst, anddocs/index.rstwhenever user-facing flags or caveats change".🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/README.rst` around lines 212 - 215, The docs currently show the metavars for the table-selection flags as "TUPLE", which is incorrect for how Click exposes these options; update the descriptions for the -t/--mysql-tables and -e/--exclude-mysql-tables options to use the CLI-accurate metavar "TEXT" (or a clear phrase like "TABLE_NAME") and add a short note that the flag accepts repeated occurrences (i.e., multiple instances of -t/--mysql-tables or -e/--exclude-mysql-tables) rather than a single tuple argument so users aren’t misled.README.md (1)
204-205:⚠️ Potential issue | 🟡 MinorAlign option metavars with actual CLI behaviour.
The past review comment on these lines remains unaddressed.
--mysql-tablesand--exclude-mysql-tablesare documented asTUPLE, but the CLI defines repeatedTEXTvalues (multiple=True,metavar="TEXT"). This mismatch can mislead users copying syntax from the documentation.📝 Suggested documentation fix
-| `-t`, `--mysql-tables TUPLE` | Transfer only the listed tables. Implies no foreign key transfer. | -| `-e`, `--exclude-mysql-tables TUPLE` | Transfer every table except the listed tables. Implies no foreign key transfer. | +| `-t`, `--mysql-tables TEXT` | Transfer only the listed tables (repeat values after the flag). Implies no foreign key transfer. | +| `-e`, `--exclude-mysql-tables TEXT` | Transfer every table except the listed tables (repeat values after the flag). Implies no foreign key transfer. |As per coding guidelines, "Update
README.md,docs/README.rst, anddocs/index.rstwhenever user-facing flags or caveats change".🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@README.md` around lines 204 - 205, The README currently documents `--mysql-tables` and `--exclude-mysql-tables` with metavar `TUPLE` which mismatches the CLI (these options use multiple=True and metavar="TEXT"); update those entries to reflect the actual CLI syntax (use `TEXT` or `TEXT [TEXT ...]` to indicate repetition) and make the same change in docs/README.rst and docs/index.rst so the user-facing docs match the option definitions (`--mysql-tables`, `--exclude-mysql-tables`, multiple=True, metavar="TEXT`).
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Duplicate comments:
In `@docs/README.rst`:
- Around line 212-215: The docs currently show the metavars for the
table-selection flags as "TUPLE", which is incorrect for how Click exposes these
options; update the descriptions for the -t/--mysql-tables and
-e/--exclude-mysql-tables options to use the CLI-accurate metavar "TEXT" (or a
clear phrase like "TABLE_NAME") and add a short note that the flag accepts
repeated occurrences (i.e., multiple instances of -t/--mysql-tables or
-e/--exclude-mysql-tables) rather than a single tuple argument so users aren’t
misled.
In `@README.md`:
- Around line 204-205: The README currently documents `--mysql-tables` and
`--exclude-mysql-tables` with metavar `TUPLE` which mismatches the CLI (these
options use multiple=True and metavar="TEXT"); update those entries to reflect
the actual CLI syntax (use `TEXT` or `TEXT [TEXT ...]` to indicate repetition)
and make the same change in docs/README.rst and docs/index.rst so the
user-facing docs match the option definitions (`--mysql-tables`,
`--exclude-mysql-tables`, multiple=True, metavar="TEXT`).
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI
Review profile: CHILL
Plan: Pro
Run ID: 2287eb0b-3c3d-4a98-8562-6b23d08d1ca3
📒 Files selected for processing (3)
README.mddocs/README.rstskills/mysql-to-sqlite3/SKILL.md
techouse
enabled auto-merge (squash)
April 26, 2026 16:42
techouse
disabled auto-merge
April 26, 2026 16:42
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This pull request makes substantial improvements to documentation, project guidelines, and the user experience for the MySQL-to-SQLite3 transfer tool. The main focus is on enhancing clarity and completeness of the
README.md, adding a new contributor guide, and updating internal documentation to reflect best practices and recent changes. These updates make it easier for both users and contributors to understand, install, and use the tool effectively.Documentation and User Experience Improvements:
README.mdto provide a clearer project overview, prerequisites, installation steps (including Homebrew and Docker), agent skill usage, and detailed usage recipes. Added a comprehensive options table, clarified option combinations and caveats, and included notes on MySQL/MariaDB/SQLite differences.README.mdfor accuracy and consistency (e.g., correct PyPI project link, improved MySQL/MariaDB badge URLs).Contributor and Project Guidelines:
AGENTS.mdfile describing repository structure, development and testing commands, coding style, naming conventions, testing guidelines, commit/PR expectations, and database/security notes. This makes onboarding and contribution much easier.Internal Documentation Updates:
.github/copilot-instructions.mdto clarify which documentation files should be updated when CLI options change, including the newdocs/README.rst. Also improved wording and examples for chunked transfers and documentation updates. [1] [2] [3]These changes collectively improve the accessibility, maintainability, and professionalism of the project for both users and contributors.