Update README to clarify usage of --model option#442
Merged
TharmiganK merged 4 commits intomainfrom Feb 24, 2026
Merged
Conversation
…ure for persist command
TharmiganK
requested review from
daneshk,
lnash94 and
shafreenAnfar
as code owners
|
No actionable comments were generated in the recent review. 🎉 📝 WalkthroughWalkthroughDocumentation updated to add a new Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~8 minutes Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 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 |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 6
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@persist-tool/README.md`:
- Line 106: Update the README option description for the --module flag to
hyphenate "persist-enabled" (change "persist enabled module" to "persist-enabled
module") so the table cell reads: "Used to indicate the persist-enabled module
in which the files are generated."; target the README entry for the --module
option.
- Line 204: The fenced code block in README.md is missing a language identifier
which triggers markdownlint MD040; edit the opening fence for the relevant code
block (the triple backticks shown) and add the appropriate language token (e.g.,
```bash, ```json, ```js, etc.) to the opening fence so the block is
language-marked and the linter passes.
- Line 195: The README example uses a leading "$" prompt without showing command
output which triggers MD014; update the migration example in README.md by either
removing the leading "$" so the command reads "bal persist migrate add_employee"
or keep the "$" and add the expected output lines beneath it, ensuring the
example shows output or omits the prompt to satisfy markdownlint.
- Line 194: The fenced code block currently uses plain ``` with no language tag;
update that code fence to include a language identifier (e.g., ```bash or
```text) so Markdownlint MD040 is satisfied—locate the triple-backtick code
block in README.md and replace ``` with the appropriate ```bash or ```text
depending on whether the snippet is shell commands or plain text.
- Line 56: The fenced code block in README uses a bare opening fence "```" which
triggers MD040; update the opening fence to include a language tag (for example
change "```" to "```text" or "```bash") so the block is language-specified;
locate the triple-backtick fence in the README (the "```" token) and add the
appropriate language identifier for the snippet content.
- Line 219: The fenced code block in README.md is missing a language identifier
(MD040); update the triple-backtick fence near the shown closing backticks to
include the appropriate language tag (for example ```bash, ```json, or ```text)
that matches the snippet content so the block has a language specifier and
satisfies Markdownlint MD040.
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #442 +/- ##
=======================================
Coverage 85.04% 85.04%
=======================================
Files 68 68
Lines 6808 6808
Branches 921 921
=======================================
Hits 5790 5790
Misses 730 730
Partials 288 288 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
There was a problem hiding this comment.
🧹 Nitpick comments (3)
persist-tool/README.md (3)
186-186: Minor style improvement: simplify "in order to".The phrase "in order to use" can be simplified to "to use" for more concise documentation.
✏️ Suggested edit
-The user must execute the `generate` command to generate the derived types and client API after running the `pull` command in order to use the client API in the project. +The user must execute the `generate` command to generate the derived types and client API after running the `pull` command to use the client API in the project.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@persist-tool/README.md` at line 186, Update the sentence that currently reads "The user must execute the `generate` command to generate the derived types and client API after running the `pull` command in order to use the client API in the project." by removing "in order to" and replacing it with "to" so it reads: "The user must execute the `generate` command to generate the derived types and client API after running the `pull` command to use the client API in the project."
37-44: Consider clarifying the<package_name>placeholder.The
targetModulevalue uses<package_name>.storeas a template. While technically correct, it might be helpful to add a brief note explaining that<package_name>should be replaced with the actual package name from the project. This would make the example clearer for users unfamiliar with Ballerina's fully-qualified module naming convention.📝 Suggested clarification
After line 44, you could add a brief note:
filePath = "persist/model.bal" ``` + + > **Note:** Replace `<package_name>` with your project's package name. For example, if your package is named `rainier`, the targetModule would be `rainier.store`.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@persist-tool/README.md` around lines 37 - 44, The README example uses the placeholder "<package_name>.store" in the targetModule setting which may confuse users; update the README near the shown snippet to add a brief note explaining that "<package_name>" must be replaced with the actual project package name (e.g., if your package is "rainier" then targetModule becomes "rainier.store") and include that clarification adjacent to the snippet referencing targetModule so readers know to substitute their real package name.
236-240: Consider varying sentence structure to improve readability.Three consecutive bullet points begin with "You should" / "You can", which creates repetitive phrasing. While the content is accurate, varying the sentence structure would improve readability.
✏️ Suggested edit
The behaviour of the `migrate` command will be as follows. -- You should invoke the command within a Ballerina project. -- You should provide a valid label for the migration. -- You should have `bal persist` initiated in the project and the model definition file updated. +- Invoke the command from within a Ballerina project. +- Provide a valid label for the migration. +- Ensure `bal persist` has been initiated in the project and the model definition file is updated. - You can use `--model` to work with a subdirectory model. Migrations will be stored in `persist/<model-name>/migrations/` for subdirectory models. - You can execute the command multiple times. It will generate the migration scripts based on the changes in the model definition file.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@persist-tool/README.md` around lines 236 - 240, The three consecutive bullets that start with "You should"/"You can" in the README need varied sentence openings to improve readability: rewrite the five bullets so they use a mix of imperative verbs and varied constructions (e.g., "Invoke the command within a Ballerina project", "Provide a valid label for the migration", "Ensure `bal persist` is initiated in the project and the model definition file is updated", "Use `--model` to target a subdirectory model; migrations will be stored in `persist/<model-name>/migrations/`", and "Run the command multiple times to generate migration scripts based on model changes"), replacing the repetitive "You should/You can" phrasing in the block shown.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In `@persist-tool/README.md`:
- Line 186: Update the sentence that currently reads "The user must execute the
`generate` command to generate the derived types and client API after running
the `pull` command in order to use the client API in the project." by removing
"in order to" and replacing it with "to" so it reads: "The user must execute the
`generate` command to generate the derived types and client API after running
the `pull` command to use the client API in the project."
- Around line 37-44: The README example uses the placeholder
"<package_name>.store" in the targetModule setting which may confuse users;
update the README near the shown snippet to add a brief note explaining that
"<package_name>" must be replaced with the actual project package name (e.g., if
your package is "rainier" then targetModule becomes "rainier.store") and include
that clarification adjacent to the snippet referencing targetModule so readers
know to substitute their real package name.
- Around line 236-240: The three consecutive bullets that start with "You
should"/"You can" in the README need varied sentence openings to improve
readability: rewrite the five bullets so they use a mix of imperative verbs and
varied constructions (e.g., "Invoke the command within a Ballerina project",
"Provide a valid label for the migration", "Ensure `bal persist` is initiated in
the project and the model definition file is updated", "Use `--model` to target
a subdirectory model; migrations will be stored in
`persist/<model-name>/migrations/`", and "Run the command multiple times to
generate migration scripts based on model changes"), replacing the repetitive
"You should/You can" phrasing in the block shown.
|
daneshk
approved these changes
Feb 24, 2026
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
2 participants
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.
Purpose
Examples
N/A
Checklist
Summary
This pull request updates documentation and build properties to clarify and standardize usage of the --model option across the persist tool, and bumps persist-related dependency properties. The changes improve guidance and examples for multi-model projects, clarify where model and migration files are created, and document command behaviors for subdirectory models to improve usability.
Key changes
Documentation (persist-tool/README.md)
Build properties (gradle.properties)
Test fixture change
Impact