docs(api): fix mass upgrade / batch upgrade terminology inconsistency #345#392
docs(api): fix mass upgrade / batch upgrade terminology inconsistency #345#392tomsebastian10 wants to merge 6 commits into
Conversation
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughDocumentation in docs/user/rest-api.rst, docs/user/upgrade-status.rst, and docs/user/websocket-api.rst was updated to standardize terminology from "batch upgrade" to "mass upgrade". Changes include headings, parameter descriptions, examples, and explanatory notes (one note preserves the existing URL path for backward compatibility). No code, public declarations, control flow, or runtime behavior were modified. (≈40 words) Estimated code review effort🎯 1 (Trivial) | ⏱️ ~3 minutes 🚥 Pre-merge checks | ✅ 3 | ❌ 1❌ Failed checks (1 inconclusive)
✅ 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 |
Code Review SummaryStatus: No Issues Found | Recommendation: Merge The changes standardize terminology from "Batch Upgrade" to "Mass Upgrade" for consistency across the documentation. These are purely documentation updates with no code changes. Files Reviewed (3 files)
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
docs/user/websocket-api.rst (1)
116-116: 🧹 Nitpick | 🔵 TrivialConsider completing the terminology update for full consistency.
Line 111 was updated to "A mass upgrade containing multiple operations," but line 116 still uses "current state of the batch." For complete consistency, consider:
-To request the current state of the batch: +To request the current state of the mass upgrade:This would fully align the descriptive text with the terminology standardization, while the technical parameter name
batch_id(line 122) correctly remains unchanged.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/user/websocket-api.rst` at line 116, Update the documentation phrase to match the new terminology: replace "current state of the batch" with "current state of the mass upgrade" (or similar wording consistent with "A mass upgrade containing multiple operations") so the descriptive sentence aligns with the terminology change already applied on line 111; leave the technical parameter name `batch_id` unchanged.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Outside diff comments:
In `@docs/user/websocket-api.rst`:
- Line 116: Update the documentation phrase to match the new terminology:
replace "current state of the batch" with "current state of the mass upgrade"
(or similar wording consistent with "A mass upgrade containing multiple
operations") so the descriptive sentence aligns with the terminology change
already applied on line 111; leave the technical parameter name `batch_id`
unchanged.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 6755f698-410b-4439-bb60-36aa1f0605e2
📒 Files selected for processing (3)
docs/user/rest-api.rstdocs/user/upgrade-status.rstdocs/user/websocket-api.rst
📜 Review details
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (6)
- GitHub Check: Python==3.13 | django~=4.2.0
- GitHub Check: Python==3.10 | django~=5.1.0
- GitHub Check: Python==3.10 | django~=5.2.0
- GitHub Check: Python==3.11 | django~=5.2.0
- GitHub Check: Python==3.11 | django~=4.2.0
- GitHub Check: Python==3.10 | django~=4.2.0
🧰 Additional context used
🧠 Learnings (2)
📚 Learning: 2026-02-23T21:44:41.470Z
Learnt from: nemesifier
Repo: openwisp/openwisp-firmware-upgrader PR: 377
File: openwisp_firmware_upgrader/websockets.py:233-246
Timestamp: 2026-02-23T21:44:41.470Z
Learning: In openwisp-firmware-upgrader, the `upgrade_operations` attribute on `BatchUpgradeOperation` is a cached property that returns a queryset, so it should be accessed as `batch_operation.upgrade_operations.all()` rather than being called as a method.
Applied to files:
docs/user/websocket-api.rstdocs/user/rest-api.rst
📚 Learning: 2026-03-07T01:16:24.447Z
Learnt from: atif09
Repo: openwisp/openwisp-firmware-upgrader PR: 387
File: openwisp_firmware_upgrader/admin.py:420-423
Timestamp: 2026-03-07T01:16:24.447Z
Learning: In openwisp-firmware-upgrader, UpgradeOperation and BatchUpgradeOperation always share the same organization (BatchUpgradeOperation.build.category.organization). A user who can view an UpgradeOperation can always view its related BatchUpgradeOperation. Model-level has_view_permission(request) is sufficient for batch breadcrumb visibility in UpgradeOperationAdmin.change_view; object-level permission checks are not needed.
Applied to files:
docs/user/websocket-api.rstdocs/user/upgrade-status.rstdocs/user/rest-api.rst
🔇 Additional comments (5)
docs/user/upgrade-status.rst (1)
184-185: LGTM! Terminology updated consistently.The update from "Batch Operations" to "Mass Upgrade Operations" successfully standardizes the user-facing terminology while maintaining clear, readable documentation.
docs/user/rest-api.rst (3)
74-93: LGTM! Section heading and descriptive text updated consistently.The terminology changes successfully standardize "mass upgrade" in user-facing documentation while appropriately preserving the API endpoint path
/batch-upgrade-operation/for backward compatibility.
204-230: LGTM! Clear and consistent terminology.The section heading and parameter description correctly use "mass upgrade" terminology, improving documentation consistency.
232-262: LGTM! Dry-run section terminology aligned.Both the heading and operation description properly updated to use "mass upgrade" terminology, maintaining consistency with the rest of the documentation.
docs/user/websocket-api.rst (1)
99-111: LGTM! Section heading and scope description updated correctly.The terminology changes from "Batch Upgrade Operation" to "Mass Upgrade Operation" successfully align this section with the standardized documentation terminology.
tomsebastian10
force-pushed
the
fix-mass-upgrade-docs
branch
from
7e56063 to
5b4d032
Compare
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
docs/user/websocket-api.rst (1)
99-111:⚠️ Potential issue | 🟡 MinorCall out that the wire format still uses
batch.This heading now says “Mass Upgrade Operation”, but the URL and message fields below still use
batch_*. Add a brief note here so readers do not go looking for/mass-upgrade-operation/or renamed payload fields.Proposed doc tweak
A mass upgrade containing multiple operations. + +.. note:: + + This documentation uses "mass upgrade" as the descriptive term, but + the current WebSocket route and payload fields still use ``batch`` for + backward compatibility, e.g. ``batch-upgrade-operation/`` and + ``batch_id``.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/user/websocket-api.rst` around lines 99 - 111, Update the "Mass Upgrade Operation" section to explicitly state that the wire format and URL still use the term "batch" (e.g., the connection URL wss://<host>/ws/firmware-upgrader/batch-upgrade-operation/<batch_id>/ and payload fields prefixed with batch_*), and add a short clarifying note under the heading (one sentence) instructing readers not to search for /mass-upgrade-operation/ or renamed payload fields because the protocol and field names remain "batch".
🤖 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/user/rest-api.rst`:
- Line 83: Add a short clarifying note near the first "mass upgrade" section
stating that the public REST API still exposes identifiers named "batch" (e.g.,
the /batch-upgrade-operation/ endpoint and the create response body
{"batch":"<uuid>"}), so users should expect "batch" in URLs and response fields;
update the same clarification at the other occurrences of "mass upgrade" in the
doc where the API is described. Locate references to the
/batch-upgrade-operation/ endpoint and the view that returns the create response
(the create method in the API views) and add the one-line note there to avoid
confusion.
---
Outside diff comments:
In `@docs/user/websocket-api.rst`:
- Around line 99-111: Update the "Mass Upgrade Operation" section to explicitly
state that the wire format and URL still use the term "batch" (e.g., the
connection URL
wss://<host>/ws/firmware-upgrader/batch-upgrade-operation/<batch_id>/ and
payload fields prefixed with batch_*), and add a short clarifying note under the
heading (one sentence) instructing readers not to search for
/mass-upgrade-operation/ or renamed payload fields because the protocol and
field names remain "batch".
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 73c3190f-bf5f-49ec-8406-49f363e9c8c4
📒 Files selected for processing (3)
docs/user/rest-api.rstdocs/user/upgrade-status.rstdocs/user/websocket-api.rst
📜 Review details
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (12)
- GitHub Check: Python==3.13 | django~=5.1.0
- GitHub Check: Python==3.11 | django~=5.2.0
- GitHub Check: Python==3.12 | django~=5.2.0
- GitHub Check: Python==3.10 | django~=4.2.0
- GitHub Check: Python==3.10 | django~=5.1.0
- GitHub Check: Python==3.11 | django~=4.2.0
- GitHub Check: Python==3.12 | django~=4.2.0
- GitHub Check: Python==3.13 | django~=5.2.0
- GitHub Check: Python==3.10 | django~=5.2.0
- GitHub Check: Python==3.13 | django~=4.2.0
- GitHub Check: Python==3.11 | django~=5.1.0
- GitHub Check: Python==3.12 | django~=5.1.0
🧰 Additional context used
🧠 Learnings (3)
📓 Common learnings
Learnt from: nemesifier
Repo: openwisp/openwisp-firmware-upgrader PR: 377
File: openwisp_firmware_upgrader/static/firmware-upgrader/js/upgrade-progress.js:458-463
Timestamp: 2026-02-25T00:17:23.479Z
Learning: In the openwisp/openwisp-firmware-upgrader repository, focus review comments on real, actionable issues rather than theoretical edge cases, trivialities, or potential future problems. Avoid flagging issues that are functionally correct but could theoretically become problems only if the code were significantly refactored or used in different contexts.
📚 Learning: 2026-03-07T01:16:24.447Z
Learnt from: atif09
Repo: openwisp/openwisp-firmware-upgrader PR: 387
File: openwisp_firmware_upgrader/admin.py:420-423
Timestamp: 2026-03-07T01:16:24.447Z
Learning: In openwisp-firmware-upgrader, UpgradeOperation and BatchUpgradeOperation always share the same organization (BatchUpgradeOperation.build.category.organization). A user who can view an UpgradeOperation can always view its related BatchUpgradeOperation. Model-level has_view_permission(request) is sufficient for batch breadcrumb visibility in UpgradeOperationAdmin.change_view; object-level permission checks are not needed.
Applied to files:
docs/user/upgrade-status.rstdocs/user/websocket-api.rstdocs/user/rest-api.rst
📚 Learning: 2026-02-23T21:44:41.470Z
Learnt from: nemesifier
Repo: openwisp/openwisp-firmware-upgrader PR: 377
File: openwisp_firmware_upgrader/websockets.py:233-246
Timestamp: 2026-02-23T21:44:41.470Z
Learning: In openwisp-firmware-upgrader, the `upgrade_operations` attribute on `BatchUpgradeOperation` is a cached property that returns a queryset, so it should be accessed as `batch_operation.upgrade_operations.all()` rather than being called as a method.
Applied to files:
docs/user/websocket-api.rstdocs/user/rest-api.rst
🔇 Additional comments (1)
docs/user/upgrade-status.rst (1)
184-186: Looks good.This keeps the monitoring docs aligned with the new user-facing terminology without changing the meaning of the section.
Standardized wording in REST API documentation where "batch upgrade" and "mass upgrade" were used inconsistentlly. Fixes openwisp#345
tomsebastian10
force-pushed
the
fix-mass-upgrade-docs
branch
from
5b4d032 to
50d8393
Compare
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
docs/user/websocket-api.rst (1)
99-111:⚠️ Potential issue | 🟡 MinorClarify that the WebSocket URL still uses
batch-upgrade-operation.The heading and scope description now refer to "Mass Upgrade Operation," but the actual WebSocket URL shown on line 106 is
wss://<host>/ws/firmware-upgrader/batch-upgrade-operation/<batch_id>/. This mismatch between the descriptive terminology and the actual identifier may confuse users.📝 Suggested clarification
Add a note near the heading to clarify that while the documentation uses "mass upgrade" as the descriptive term, the WebSocket path retains
batch-upgrade-operationfor backward compatibility:2. Mass Upgrade Operation ~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. note:: + + This documentation uses "mass upgrade" as the descriptive term, but + the WebSocket URL path uses ``batch-upgrade-operation`` for backward + compatibility. Connection URL:🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/user/websocket-api.rst` around lines 99 - 111, The heading "Mass Upgrade Operation" and the scope text should clarify that the WebSocket endpoint path remains "batch-upgrade-operation"; update the docs near the heading (the "Mass Upgrade Operation" section) to add a brief note stating that although the documentation uses the term "mass upgrade", the connection URL path is wss://<host>/ws/firmware-upgrader/batch-upgrade-operation/<batch_id>/ (retain the literal segment batch-upgrade-operation for backward compatibility) so readers aren’t confused by the mismatch.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Outside diff comments:
In `@docs/user/websocket-api.rst`:
- Around line 99-111: The heading "Mass Upgrade Operation" and the scope text
should clarify that the WebSocket endpoint path remains
"batch-upgrade-operation"; update the docs near the heading (the "Mass Upgrade
Operation" section) to add a brief note stating that although the documentation
uses the term "mass upgrade", the connection URL path is
wss://<host>/ws/firmware-upgrader/batch-upgrade-operation/<batch_id>/ (retain
the literal segment batch-upgrade-operation for backward compatibility) so
readers aren’t confused by the mismatch.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 54606d60-4f45-454f-8bd5-8134c1874aa9
📒 Files selected for processing (3)
docs/user/rest-api.rstdocs/user/upgrade-status.rstdocs/user/websocket-api.rst
📜 Review details
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (12)
- GitHub Check: Python==3.10 | django~=5.2.0
- GitHub Check: Python==3.11 | django~=5.1.0
- GitHub Check: Python==3.12 | django~=4.2.0
- GitHub Check: Python==3.13 | django~=4.2.0
- GitHub Check: Python==3.13 | django~=5.2.0
- GitHub Check: Python==3.13 | django~=5.1.0
- GitHub Check: Python==3.12 | django~=5.1.0
- GitHub Check: Python==3.11 | django~=5.2.0
- GitHub Check: Python==3.10 | django~=5.1.0
- GitHub Check: Python==3.11 | django~=4.2.0
- GitHub Check: Python==3.12 | django~=5.2.0
- GitHub Check: Python==3.10 | django~=4.2.0
🧰 Additional context used
🧠 Learnings (3)
📓 Common learnings
Learnt from: nemesifier
Repo: openwisp/openwisp-firmware-upgrader PR: 377
File: openwisp_firmware_upgrader/static/firmware-upgrader/js/upgrade-progress.js:458-463
Timestamp: 2026-02-25T00:17:23.479Z
Learning: In the openwisp/openwisp-firmware-upgrader repository, focus review comments on real, actionable issues rather than theoretical edge cases, trivialities, or potential future problems. Avoid flagging issues that are functionally correct but could theoretically become problems only if the code were significantly refactored or used in different contexts.
📚 Learning: 2026-03-07T01:16:24.447Z
Learnt from: atif09
Repo: openwisp/openwisp-firmware-upgrader PR: 387
File: openwisp_firmware_upgrader/admin.py:420-423
Timestamp: 2026-03-07T01:16:24.447Z
Learning: In openwisp-firmware-upgrader, UpgradeOperation and BatchUpgradeOperation always share the same organization (BatchUpgradeOperation.build.category.organization). A user who can view an UpgradeOperation can always view its related BatchUpgradeOperation. Model-level has_view_permission(request) is sufficient for batch breadcrumb visibility in UpgradeOperationAdmin.change_view; object-level permission checks are not needed.
Applied to files:
docs/user/upgrade-status.rstdocs/user/websocket-api.rstdocs/user/rest-api.rst
📚 Learning: 2026-02-23T21:44:41.470Z
Learnt from: nemesifier
Repo: openwisp/openwisp-firmware-upgrader PR: 377
File: openwisp_firmware_upgrader/websockets.py:233-246
Timestamp: 2026-02-23T21:44:41.470Z
Learning: In openwisp-firmware-upgrader, the `upgrade_operations` attribute on `BatchUpgradeOperation` is a cached property that returns a queryset, so it should be accessed as `batch_operation.upgrade_operations.all()` rather than being called as a method.
Applied to files:
docs/user/upgrade-status.rstdocs/user/websocket-api.rstdocs/user/rest-api.rst
🔇 Additional comments (3)
docs/user/rest-api.rst (2)
74-83: Terminology mismatch between documentation and API identifiers.The documentation now uses "mass upgrade" terminology, but the actual REST API endpoints, URLs, and response fields still use
batch(e.g.,/batch-upgrade-operation/and{"batch": "<uuid>"}). This has already been flagged in a previous review.
204-215: Terminology mismatch between documentation and API identifiers.The heading and description use "mass upgrade" but the actual endpoint path shown on line 211 is
/api/v1/firmware-upgrader/build/{id}/upgrade/, which returns a response containing{"batch": "<uuid>"}. This inconsistency was flagged in a previous review.docs/user/upgrade-status.rst (1)
184-186: LGTM! Terminology update is clear and consistent.This change appropriately updates the monitoring section to use "mass upgrade" terminology, aligning with the overall documentation standardization. Since this section describes monitoring workflows rather than specific API identifiers, the terminology change enhances clarity without introducing confusion.
Added note explaining that the websocket URL keeps the batch-upgrade-operation path for backward compatibility while the documentation uses mass upgrade terminology. Fixes openwisp#345
tomsebastian10
force-pushed
the
fix-mass-upgrade-docs
branch
from
4461135 to
eb33e59
Compare
tomsebastian10
changed the title
1 participant
Checklist
Reference to Existing Issue
Closes #345
Description of Changes
This PR fixes inconsistent terminology in the REST API documentation.
Some sections referred to firmware upgrade operations as "batch upgrade"
while others used "mass upgrade". This change standardizes the wording
in descriptive text while keeping API endpoints and identifiers unchanged.