Improve README with comprehensive project documentation#1168
Open
chris1984 wants to merge 1 commit intotheforeman:developfrom
Open
Improve README with comprehensive project documentation#1168chris1984 wants to merge 1 commit intotheforeman:developfrom
chris1984 wants to merge 1 commit intotheforeman:developfrom
Conversation
Add proper project description, requirements, operating modes, development setup, testing instructions, and contributing guidelines. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Reviewer's GuideREADME.md is overhauled into a full project guide, adding detailed feature description, operating modes, usage examples, cloud endpoint documentation, development and testing workflows, and contributing instructions, while cleaning up outdated sections and fixing minor formatting and copyright details. Flow diagram for development and testing workflow from READMEflowchart TD
A[Start working on foreman_rh_cloud] --> B[Clone Foreman repository]
B --> C[Clone foreman_rh_cloud plugin]
C --> D[Install Ruby dependencies in Foreman root using bundle install]
D --> E[Install JavaScript dependencies in plugin directory using npm install]
E --> F[Run Ruby plugin test suite from Foreman root using bundle exec rake test:foreman_rh_cloud]
F --> G[Optionally run a single Ruby test file with bundle exec rake test TEST=path]
E --> H[Run JavaScript tests in plugin directory using npm test]
H --> I[Optionally use npm run test:watch]
H --> J[Optionally use npm run test:current]
F --> K[Run Ruby linter in Foreman root using bundle exec rubocop --parallel]
H --> L[Run JavaScript linter in plugin directory using npm run lint]
K --> M[Optionally start development server from Foreman root using bundle exec foreman start]
L --> M
M --> N[Open UI and exercise Inventory Upload, Insights Recommendations, and Inventory Status Sync]
Flow diagram for contributing process from READMEflowchart TD
A[Decide to contribute to foreman_rh_cloud] --> B[Fork the repository]
B --> C[Create a feature branch]
C --> D[Make code or documentation changes]
D --> E[Run Ruby and JavaScript tests]
E --> F[Run Ruby and JavaScript linters]
F --> G[Ensure all checks pass]
G --> H[Submit a Pull Request]
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
![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 1 issue, and left some high level feedback:
- In the Cloud Endpoints table, consider aligning the descriptions with the previous design section by either including or explicitly omitting query parameters so it’s clear whether the base URL or a fully parameterized endpoint is expected.
- The README now mixes generic
/path/to/foremaninstructions with concrete system locations used earlier (/usr/sbin/foreman-rake); it may help readers if you briefly note when distro-specific paths (e.g., Satellite packages) differ from development setups and how to adapt the commands.
Prompt for AI Agents
Please address the comments from this code review:
## Overall Comments
- In the Cloud Endpoints table, consider aligning the descriptions with the previous design section by either including or explicitly omitting query parameters so it’s clear whether the base URL or a fully parameterized endpoint is expected.
- The README now mixes generic `/path/to/foreman` instructions with concrete system locations used earlier (`/usr/sbin/foreman-rake`); it may help readers if you briefly note when distro-specific paths (e.g., Satellite packages) differ from development setups and how to adapt the commands.
## Individual Comments
### Comment 1
<location path="README.md" line_range="35-37" />
<code_context>
+
+The default mode. Communicates directly with Red Hat cloud services to upload inventory, download recommendations, and forward client requests.
+
+### IoP Mode (On-Premise)
+
+When an Insights on Premise (IoP) Smart Proxy is configured, all cloud communication is routed through the local proxy instead. HTTP proxy settings are disabled, and scheduled sync tasks are skipped.
+
+Check the current mode: `ForemanRhCloud.with_iop_smart_proxy?`
</code_context>
<issue_to_address>
**suggestion (typo):** Use the standard term "on-premises" instead of "on-premise/on Premise" for accuracy and consistency.
For example, update the heading to `IoP Mode (On-Premises)` and the sentence to `When an Insights on-premises (IoP) Smart Proxy is configured, ...` for consistent terminology.
```suggestion
### IoP Mode (On-Premises)
When an Insights on-premises (IoP) Smart Proxy is configured, all cloud communication is routed through the local proxy instead. HTTP proxy settings are disabled, and scheduled sync tasks are skipped.
```
</issue_to_address>Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
Comment on lines
+35
to
+37
| ### IoP Mode (On-Premise) | ||
|
|
||
| When an Insights on Premise (IoP) Smart Proxy is configured, all cloud communication is routed through the local proxy instead. HTTP proxy settings are disabled, and scheduled sync tasks are skipped. |
There was a problem hiding this comment.
suggestion (typo): Use the standard term "on-premises" instead of "on-premise/on Premise" for accuracy and consistency.
For example, update the heading to IoP Mode (On-Premises) and the sentence to When an Insights on-premises (IoP) Smart Proxy is configured, ... for consistent terminology.
Suggested change
| ### IoP Mode (On-Premise) | |
| When an Insights on Premise (IoP) Smart Proxy is configured, all cloud communication is routed through the local proxy instead. HTTP proxy settings are disabled, and scheduled sync tasks are skipped. | |
| ### IoP Mode (On-Premises) | |
| When an Insights on-premises (IoP) Smart Proxy is configured, all cloud communication is routed through the local proxy instead. HTTP proxy settings are disabled, and scheduled sync tasks are skipped. |
jeremylenz
reviewed
Mar 5, 2026
| - **Insights Recommendations** — Sync security, performance, and stability recommendations from Red Hat Insights | ||
| - **Remediations** — Apply Insights remediation playbooks via Remote Execution (Ansible) | ||
| - **Cloud Connector** — Enable cloud-initiated remediations through `rhcd` | ||
| - **Client Tools Forwarding** — Proxy `insights-client` requests from managed hosts that lack direct internet access |
Collaborator
There was a problem hiding this comment.
It's for any hosts registered to Foreman, not just those that lack internet access.
Suggested change
| - **Client Tools Forwarding** — Proxy `insights-client` requests from managed hosts that lack direct internet access | |
| - **Client Tools Forwarding** — Proxy `insights-client` requests from managed hosts |
Comment on lines
+18
to
+20
| - [Katello](https://github.com/Katello/katello) >= 4.18 | ||
| - [foreman_ansible](https://github.com/theforeman/foreman_ansible) >= 15.0.0 | ||
| - [foreman-tasks](https://github.com/theforeman/foreman-tasks) >= 10.0.0 |
Collaborator
There was a problem hiding this comment.
I would leave the version numbers out here - just another thing to keep up to date.
Comment on lines
+35
to
+37
| ### IoP Mode (On-Premise) | ||
|
|
||
| When an Insights on Premise (IoP) Smart Proxy is configured, all cloud communication is routed through the local proxy instead. HTTP proxy settings are disabled, and scheduled sync tasks are skipped. |
Collaborator
There was a problem hiding this comment.
Could highlight here that IoP is a technical abbreviation, but it doesn't officially stand for anything.
|
|
||
| ### Inventory Upload | ||
|
|
||
| **UI:** Insights → Inventory Upload → select the organization → Generate and upload report |
Collaborator
There was a problem hiding this comment.
Suggested change
| **UI:** Insights → Inventory Upload → select the organization → Generate and upload report | |
| **UI (cloud):** Insights → Inventory Upload → select the organization → Generate and upload report | |
| **UI (IoP):** Administer → Inventory Upload → select the organization → Generate and upload report |
| foreman-rake rh_cloud_inventory:report:generate_upload | ||
|
|
||
| # Generate and upload report for specific organization | ||
| organization_id=1 foreman-rake rh_cloud_inventory:report:generate_upload |
Collaborator
There was a problem hiding this comment.
this will not work with env var in front
| organization_id=1 foreman-rake rh_cloud_inventory:report:generate_upload | ||
|
|
||
| # Generate report without uploading | ||
| organization_id=1 target=/var/lib/foreman/red_hat_inventory/generated_reports/ \ |
| foreman-rake rh_cloud_inventory:report:generate | ||
|
|
||
| # Upload a previously generated report | ||
| organization_id=1 target=/var/lib/foreman/red_hat_inventory/generated_reports/ \ |
| ## Project overview | ||
| See our [wiki](https://deepwiki.com/theforeman/foreman_rh_cloud) | ||
| # Specific organization | ||
| organization_id=1 foreman-rake rh_cloud_inventory:sync |
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.
Add proper project description, requirements, operating modes, development setup, testing instructions, and contributing guidelines.
Summary by Sourcery
Update the README with comprehensive user and contributor documentation for the ForemanRhCloud plugin, including usage, development, and architecture references.
Documentation:
Chores: