docs: fix and refactor README#2197
Open
Dugowitch wants to merge 1 commit into
Open
Conversation
Reviewer's GuideRefactors and expands the README to better describe local development, testing, Kafka control, OpenAPI generation, VMaaS usage, monitoring, SonarQube analysis, Grafana configuration, and pprof profiling, while fixing wording, headings, and consistency issues. File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
Dugowitch
commented
May 15, 2026
|
|
||
| ### Running locally | ||
| Uses `podman-compose` to deploy the individual project components and supporting containers, which simulate the CMSfR platform and database: | ||
| Use `podman-compose` to deploy the individual project components and supporting containers that simulate the CMSfR platform and database: |
Contributor
Author
There was a problem hiding this comment.
BTW, what is CMSfR?
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## master #2197 +/- ##
=======================================
Coverage 59.06% 59.06%
=======================================
Files 136 136
Lines 8761 8761
=======================================
Hits 5175 5175
Misses 3040 3040
Partials 546 546
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
There was a problem hiding this comment.
Hey - I've found 3 issues, and left some high level feedback:
- In the OpenAPI docs section, consider replacing
go get -u github.com/swaggo/swag/cmd/swagwith ago installcommand including a version (per current Go tooling best practices) to avoid installing an unpinned, possibly incompatible version. - There are still references to
docker-composeanddocker-compose.yml(e.g., in the Monitoring section); since the rest of the README standardizes onpodman-compose, consider either updating these references or explicitly calling out both options for consistency.
Prompt for AI Agents
Please address the comments from this code review:
## Overall Comments
- In the OpenAPI docs section, consider replacing `go get -u github.com/swaggo/swag/cmd/swag` with a `go install` command including a version (per current Go tooling best practices) to avoid installing an unpinned, possibly incompatible version.
- There are still references to `docker-compose` and `docker-compose.yml` (e.g., in the Monitoring section); since the rest of the README standardizes on `podman-compose`, consider either updating these references or explicitly calling out both options for consistency.
## Individual Comments
### Comment 1
<location path="README.md" line_range="113" />
<code_context>
+The REST API is documented using OpenAPI v3. On a local instance, it can be accessed at <http://localhost:8080/openapi/index.html>.
-To update/regenerate OpenAPI sources run:
+First time, ensure that you have `swaggo/swag` binary installed:
+~~~bash
+go get -u github.com/swaggo/swag/cmd/swag
</code_context>
<issue_to_address>
**nitpick (typo):** Rephrase "First time" for smoother grammar
You could change this to either “For the first time, ensure that you have the `swaggo/swag` binary installed:” or simply “First, ensure that you have the `swaggo/swag` binary installed:” to improve the phrasing.
```suggestion
First, ensure that you have the `swaggo/swag` binary installed:
```
</issue_to_address>
### Comment 2
<location path="README.md" line_range="38-44" />
<code_context>
+Grafana is available at <http://localhost:3000> and Prometheus at <http://localhost:9090>.
+#### Run a component in the host OS
+Run a single component in the host OS, the rest in podman-compose:
+~~~bash
+podman-compose stop evaluator_upload # stop a single component using podman-compose
</code_context>
<issue_to_address>
**suggestion (typo):** Avoid comma splice in this sentence
Consider rephrasing to avoid the comma splice, for example:
- "Run a single component in the host OS while running the rest in podman-compose:"
- "Run a single component in the host OS and run the rest in podman-compose:"
```suggestion
#### Run a component in the host OS
Run a single component in the host OS while running the rest in podman-compose:
~~~bash
podman-compose stop evaluator_upload # stop a single component using podman-compose
export $(xargs < conf/local.env)
./scripts/entrypoint.sh evaluator # (or listener, or manager) run the component in the host OS</issue_to_address>
### Comment 3
<location path="README.md" line_range="167" />
<code_context>
+
+### Using Admin API
+1. Set `ENABLE_PROFILE_{container_name}=true` in the ClowdApp.
+2. Download the profile file using internal api `/api/patch/admin/pprof/{manager|listener|evaluator_upload|evaluator_recalc}/{heap|profile|block|mutex|trace}`.
+3. Run `go tool pprof <saved.file>`.
</code_context>
<issue_to_address>
**nitpick (typo):** Capitalize "API" consistently
For consistency with common usage and the rest of the document, please capitalize "api" as "API" in this sentence.
```suggestion
2. Download the profile file using internal API `/api/patch/admin/pprof/{manager|listener|evaluator_upload|evaluator_recalc}/{heap|profile|block|mutex|trace}`.
</issue_to_address>
</details>
***
<details>
<summary>Sourcery is free for open source - if you like our reviews please consider sharing them ✨</summary>
- [X](https://twitter.com/intent/tweet?text=I%20just%20got%20an%20instant%20code%20review%20from%20%40SourceryAI%2C%20and%20it%20was%20brilliant%21%20It%27s%20free%20for%20open%20source%20and%20has%20a%20free%20trial%20for%20private%20code.%20Check%20it%20out%20https%3A//sourcery.ai)
- [Mastodon](https://mastodon.social/share?text=I%20just%20got%20an%20instant%20code%20review%20from%20%40SourceryAI%2C%20and%20it%20was%20brilliant%21%20It%27s%20free%20for%20open%20source%20and%20has%20a%20free%20trial%20for%20private%20code.%20Check%20it%20out%20https%3A//sourcery.ai)
- [LinkedIn](https://www.linkedin.com/sharing/share-offsite/?url=https://sourcery.ai)
- [Facebook](https://www.facebook.com/sharer/sharer.php?u=https://sourcery.ai)
</details>
<sub>
Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
</sub>
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.
Secure Coding Practices Checklist GitHub Link
Secure Coding Checklist
Summary by Sourcery
Update and expand README guidance for developing, testing, and profiling the patchman-engine service.
Documentation: