Add release notes for 5.0.0 #1978
Conversation
|
|
|
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings. WalkthroughBumps documentation to 5.0.0: adds 5.0.0 release notes and 5.x breaking-changes, removes many 4.x release-note files, updates Sphinx metadata and support matrix, converts publishing blacklist to git pathspecs, renames publish-related permissions/APIs, and simplifies upgrade guidance and script references. Changes
Sequence Diagram(s)sequenceDiagram
participant Admin as System Admin
participant Archive as New Binary Archive
participant Install as Current Install
participant Scripts as Upgrade Scripts
participant Services as Server/Services
Admin->>Archive: optionally extract new binaries
Admin->>Install: stop services (Tomcat / Deployer)
Admin->>Scripts: run `upgrade-target.sh`
Scripts->>Install: migrate binaries and configs
Scripts->>Services: invoke `start-upgrade.sh` to start upgrade mode
Services->>Scripts: perform upgrade tasks (rebuild indices, DB/migration hooks)
Scripts->>Services: run `post-upgrade.sh` to finalize
Services->>Admin: report completion (logs reference StudioUpgradeManagerImpl)
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Suggested reviewers
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. 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: 3
🧹 Nitpick comments (6)
source/support.rst (1)
25-29: Replace TBDs with actual release info before merge.
Fill “Released” and “Latest” cells once finalized to avoid publishing placeholders.If helpful, I can wire these values to a single place (e.g., conf.py) to avoid future drift. Want me to propose that change?
source/conf.py (1)
154-154: Add 5 to the versions switcher.To surface 5.x explicitly in the footer menu, include “5” alongside “current.”
- 'versions': ['current', '4', '4.1', '4.0', '3.1'], + 'versions': ['current', '5', '4', '4.1', '4.0', '3.1'],source/release-notes/5-x-breaking-changes.rst (2)
20-21: Call out migration guidance for removed Spring profile.Add a short note on what replaces
crafter_studio_externalDbor link to the setup page for external DB configuration in 5.x.
56-73: Cross-link to the authoritative configuration section.Add a reference to the “Publishing Blacklist” section so readers can jump to details.
- - Publishing blacklist configuration has been changed. |br| + - Publishing blacklist configuration has been changed. See :ref:`publishing-blacklist`. |br|source/release-notes/5-0-0.rst (1)
124-128: Deduplicate entry for PackageDetailsDialog packageId type.The same change is listed twice.
- - ``PackageDetailsDialog``: Updated ``packageId`` prop to be of type ``number``. ... - - ``PackageDetailsDialog``: Update ``packageId`` prop to be of type ``number``. + - ``PackageDetailsDialog``: Updated ``packageId`` prop to be of type ``number``.source/release-notes/index.rst (1)
9-15: Include a pointer to 5.x breaking changes.Add a short line under the intro or right after the 5.0.0 include to guide readers to the breaking changes page.
.. include:: /release-notes/5-0-0.rst + +.. note:: See also :ref:`breaking-changes-5-x` for 5.x breaking changes.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (20)
source/by-role/system-admin/upgrade/upgrading-server.rst(1 hunks)source/conf.py(3 hunks)source/contribute/acknowledgements.rst(1 hunks)source/index.rst(2 hunks)source/reference/modules/studio.rst(2 hunks)source/release-notes/4-2-0.rst(0 hunks)source/release-notes/4-2-2.rst(0 hunks)source/release-notes/4-3-0.rst(0 hunks)source/release-notes/4-3-1.rst(0 hunks)source/release-notes/4-3-2.rst(0 hunks)source/release-notes/4-4-0.rst(0 hunks)source/release-notes/4-4-1.rst(0 hunks)source/release-notes/4-4-2.rst(0 hunks)source/release-notes/4-4-3.rst(0 hunks)source/release-notes/4-4-4.rst(0 hunks)source/release-notes/4-x-breaking-changes.rst(0 hunks)source/release-notes/5-0-0.rst(1 hunks)source/release-notes/5-x-breaking-changes.rst(1 hunks)source/release-notes/index.rst(1 hunks)source/support.rst(2 hunks)
💤 Files with no reviewable changes (11)
- source/release-notes/4-3-0.rst
- source/release-notes/4-4-1.rst
- source/release-notes/4-4-2.rst
- source/release-notes/4-3-1.rst
- source/release-notes/4-2-2.rst
- source/release-notes/4-4-3.rst
- source/release-notes/4-4-4.rst
- source/release-notes/4-3-2.rst
- source/release-notes/4-4-0.rst
- source/release-notes/4-2-0.rst
- source/release-notes/4-x-breaking-changes.rst
🔇 Additional comments (11)
source/contribute/acknowledgements.rst (1)
2-2: LGTM on metadata bump to 5.0.0.
Matches the 5.0.0 docs alignment.source/by-role/system-admin/upgrade/upgrading-server.rst (1)
68-68: Tighten wording; anchor verified
Avoid the duplicated "to" — apply the suggested rephrase. The :ref:breaking changes <breaking-changes-5-x>anchor exists at source/release-notes/5-x-breaking-changes.rst:5.source/support.rst (1)
2-2: LGTM on last-updated 5.0.0.
Consistent with the 5.0.0 docs update.source/reference/modules/studio.rst (1)
2-2: Version bump looks good.No further action.
source/conf.py (2)
32-32: Release set to 5.0.0 — OK.Matches the PR intent and extlinks usage.
296-303: Javadoc base/version linkage — OK.
extlinks['javadoc_base_url']correctly derives fromrelease.source/release-notes/5-0-0.rst (2)
7-7: Replace “Released TBD” with the actual release date before publishing.This blocks release.
171-173: Verify replacement endpoints (duplicated target).“Removed
workflow/publishandworkflow/requestPublish, replaced bypublishing/publishandpublishing/publish” has a duplicated replacement. Confirm the second should be a different endpoint (e.g.,publishing/calculateorworkflow/approve), then correct.source/index.rst (1)
78-78: Release blurb OK.Matches the 5.0.0 update elsewhere.
source/release-notes/index.rst (2)
2-2: Version stamp OK.No issues.
18-21: Cross-version link looks good.Linking to “4 Release Notes” via docs_base_url is consistent with extlinks config.
There was a problem hiding this comment.
Actionable comments posted: 3
♻️ Duplicate comments (1)
source/index.rst (1)
2-2: Front-matter version bump looks correct; prior merge conflict resolved.
Last-updated now reads 5.0.0 and no conflict markers remain.
🧹 Nitpick comments (1)
source/index.rst (1)
80-80: Pin Docker tag to 5.0.0 for reproducibility.
Using :latest can drift after future releases.- docker run -p 8080:8080 craftercms/authoring_local:latest + docker run -p 8080:8080 craftercms/authoring_local:5.0.0
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (4)
source/index.rst(2 hunks)source/release-notes/5-0-0.rst(1 hunks)source/release-notes/5-x-breaking-changes.rst(1 hunks)source/support.rst(2 hunks)
🚧 Files skipped from review as they are similar to previous changes (2)
- source/support.rst
- source/release-notes/5-x-breaking-changes.rst
🔇 Additional comments (4)
source/release-notes/5-0-0.rst (4)
7-7: Replace “Released TBD” with the actual release date before merging.
Avoid shipping placeholders in published docs.-Released *TBD* +Released *YYYY-MM-DD* <!-- replace with the actual 5.0.0 release date -->
23-44: Validate API doc anchors/links resolve.
Several :base_url: links depend on generated anchors; case or path mismatches will 404 in built docs. Please run link checks before merging.Would you confirm these with your Sphinx linkcheck job (or locally with “make linkcheck”) and fix any broken anchors?
171-171: Double-check replacement services text.
Both removed endpoints are listed as replaced by the samepublishing/publish. If that’s intentional, add a brief note; if not, correct the second replacement (perhapspublishing/requestPublish?).
220-225: Sanity-check external references before publishing.
Verify the GitHub project link for “5.0.0” and the cross-refcompatibility-with-3.1.xstill exist after the 5.x doc reorg.
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (3)
source/release-notes/5-0-0.rst (3)
117-117: Typo: "by" → "with" for consistency with correct prop replacement.The sentence mentions replacing the
stylesprop "Replaced bysxsprop." but this should be "Replaced withsxsprop." for grammatical consistency.- - Removed ``styles`` prop from ``ErrorState``, ``ApiResponseErrorState``, ``BlueprintForm``, ``LoadingState``, ``ConfirmDialog``, ``AlertDialog``, ``LauncherSection``, ``AceEditor``, ``ItemDisplay``, ``PasswordRequirementsDisplay``, ``PublishDialogForm``, ``ItemStateIcon``, ``ResizeableDrawer``, ``GlobalAppToolbar``, ``ViewToolbar``, ``PublishingStatusAvatar``, ``ItemPublishingTargetIcon`` and ``EmptyState``. Replaced by ``sxs`` prop. + - Removed ``styles`` prop from ``ErrorState``, ``ApiResponseErrorState``, ``BlueprintForm``, ``LoadingState``, ``ConfirmDialog``, ``AlertDialog``, ``LauncherSection``, ``AceEditor``, ``ItemDisplay``, ``PasswordRequirementsDisplay``, ``PublishDialogForm``, ``ItemStateIcon``, ``ResizeableDrawer``, ``GlobalAppToolbar``, ``ViewToolbar``, ``PublishingStatusAvatar``, ``ItemPublishingTargetIcon`` and ``EmptyState``. Replaced with ``sxs`` prop.
137-137: Missing closing backticks for prop name formatting.The prop name
onContentTypeSelectedis missing proper RST inline code formatting with closing backticks.- - Prop ``onContentTypeSelected`` changed its signature from sending an object with ``authoringBase``, ``path``, ``isNewContent``, ``contentTypeId``, ``onSaveSuccess`` to ``{ path: string; contentType: ContentType }`` + - Prop ``onContentTypeSelected`` changed its signature from sending an object with ``authoringBase``, ``path``, ``isNewContent``, ``contentTypeId``, ``onSaveSuccess`` to ``{ path: string; contentType: ContentType }``
189-189: Fix unbalanced backticks for inline code formatting.The
itemsproperty has unbalanced backticks that will render incorrectly in RST.- - ``items`` is now of type ``PublishingItem[]``. + - ``items`` is now of type ``PublishingItem[]``.
🧹 Nitpick comments (1)
source/release-notes/5-0-0.rst (1)
7-7: Update TBD placeholder with actual release date.The release date is marked as "TBD" (To Be Determined). Since this is a release notes document, consider updating this with the actual release date when available.
-Released *TBD* +Released *[ACTUAL_RELEASE_DATE]*
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
source/release-notes/5-0-0.rst(1 hunks)
🔇 Additional comments (1)
source/release-notes/5-0-0.rst (1)
1-228: Overall document structure and content are comprehensive.The release notes document is well-structured and comprehensive, covering all major areas including new features, enhancements, UI changes, and bug fixes. The categorization is clear and the technical details are appropriately detailed for a major version release.
| - Renamed ``fetchSandboxItems`` to ``fetchContentItems``. Action string changed from FETCH_SANDBOX_ITEMS to FETCH_CONTENT_ITEMS. | ||
| - Renamed ``fetchSandboxItemsComplete`` to ``fetchContentItemsComplete``. Action string changed from FETCH_SANDBOX_ITEMS_COMPLETE to FETCH_CONTENT_ITEMS_COMPLETE. | ||
| - Removed ``fetchSandboxItem`` action. Replaced by ``fetchContentItem``. | ||
| - Removed ``fetchContentItemComplete`` action. Replaced by ``fetchContentItemComplete``. |
There was a problem hiding this comment.
Duplicate action name in removal description.
Line 208 mentions removing fetchContentItemComplete action and replacing it with fetchContentItemComplete, which appears to be a copy-paste error since it's the same action name.
- - Removed ``fetchContentItemComplete`` action. Replaced by ``fetchContentItemComplete``.
+ - Removed ``fetchSandboxItemComplete`` action. Replaced by ``fetchContentItemComplete``.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| - Removed ``fetchContentItemComplete`` action. Replaced by ``fetchContentItemComplete``. | |
| - Removed ``fetchSandboxItemComplete`` action. Replaced by ``fetchContentItemComplete``. |
🤖 Prompt for AI Agents
In source/release-notes/5-0-0.rst around line 208, the release note erroneously
says "Removed ``fetchContentItemComplete`` action. Replaced by
``fetchContentItemComplete``" (duplicate name); update this line to either (a)
replace the second occurrence with the correct replacement action name if known,
or (b) remove the "Replaced by ..." clause if there is no replacement; if
unsure, consult the commit history or author and correct the text accordingly.
There was a problem hiding this comment.
Waiting for fix in https://github.com/craftercms/studio-ui/blob/df9578dcd269197c50e7fe97fe799360ff334233/ui/app/src/CHANGELOG.md?plain=1#L123 before updating docs
There was a problem hiding this comment.
🧩 Analysis chain
I'll check the referenced changelog to see what fix is being implemented.
@alhambrav, that's a sensible approach! Waiting for the upstream fix in the studio-ui repository will ensure the documentation accurately reflects the correct action names rather than making assumptions. Once the fix is merged and you have the correct information, we can update the release notes accordingly.
🐰📚
/| /|
( ✌️ )
|_/|
🏁 Script executed:
#!/bin/bash
# Check the studio-ui changelog at the specific commit and line 123 to understand the fix
curl -s "https://raw.githubusercontent.com/craftercms/studio-ui/df9578dcd269197c50e7fe97fe799360ff334233/ui/app/src/CHANGELOG.md" | sed -n '115,130p'
Length of output: 1484
@alhambrav, I checked the referenced changelog and it appears to contain the same duplicate error on line 123:
* Removed `fetchContentItemComplete` action. Replaced by `fetchContentItemComplete`.
This suggests that the fix may not have been applied yet to the studio-ui changelog, or the same correction needs to be made in both repositories. You might want to check if the fix is still in progress or if it needs to be applied to both the studio-ui changelog and these release notes.
Based on the surrounding context in the changelog, it looks like this line should probably be:
* Removed `fetchSandboxItemComplete` action. Replaced by `fetchContentItemComplete`.
This would align with the pattern of other items being renamed from "sandbox" to "content" terminology.
🐰🔍
/| /|
( ._. )
|_/|
🧠 Learnings used
Learnt from: alhambrav
PR: craftercms/docs#2042
File: source/reference/modules/studio.rst:0-0
Timestamp: 2025-09-02T20:40:32.613Z
Learning: When reviewing CrafterCMS Studio documentation, property names in configuration examples should match the actual Studio source code implementation, even if the underlying Git config keys are different. Studio may have a translation layer that maps Studio property names to actual Git configuration keys.
|
Update new APIs in list and removed APIs commits: 880fc37 3a64d54 76c14de |
There was a problem hiding this comment.
Actionable comments posted: 1
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
source/release-notes/5-x-breaking-changes.rst(1 hunks)
🔇 Additional comments (8)
source/release-notes/5-x-breaking-changes.rst (8)
1-3: Verify orphan directive placement and purpose.The
:orphan:directive on line 3 marks this document as intentionally excluded from table-of-contents. Confirm this is the intended behavior—if this document should be discoverable from a parent toc tree, this directive should be removed.
134-134: Future dates in example outputs should be reviewed.Lines 134 and 184 contain timestamps set in the future (2025-10-16 and 2025-10-17). If these are intended as generated/example timestamps, confirm they are appropriate. If they are placeholders, consider updating them to realistic dates or making them clearly generic.
Also applies to: 184-184
20-55: Document API removal comprehensively.The list of removed APIs (lines 24-55) is comprehensive and well-organized. The formatting and organization are clear and easy to parse.
57-75: Publishing blacklist migration example is clear.The before/after YAML examples (lines 60-73) effectively communicate the configuration change from regex to git pathspecs. The reference to git pathspec documentation is helpful.
77-139: Content type controller migration guidance is thorough.The breaking change for content type controllers is well-documented with clear upgrade behavior (auto-delete on match, comment-out on mismatch), realistic code examples, and logger output. The guidance directs users to appropriate documentation sections.
141-149: Permission removals are clearly listed.The permissions removal list (lines 141-149) includes helpful context showing what replaces each removed permission, making migration straightforward.
151-196: Deprecated API removal guidance includes migration path.The removal of the Engine REST API Get Descriptor is clearly explained with a migration path to the Get Item API. The example GET request and detailed XML output with highlighted content effectively illustrate the replacement endpoint behavior.
152-152: The:base_url:role is properly defined—no action needed.The verification confirms that
:base_url:is correctly defined insource/conf.py(line 301) within theextlinksdictionary:'base_url': ('/docs/' + version + '/%s', None). This is the standard Sphinx mechanism for custom roles, and the link will render correctly.Likely an incorrect or invalid review comment.
There was a problem hiding this comment.
Actionable comments posted: 2
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (4)
source/reference/modules/engine.rst (3)
893-899: Fix XML closing tag in example.In the Cache-Control example, the closing tag is incorrect.
- <headers> + </headers>
847-849: Backticks and stray character in bullet.Balance the inline code for header/value and remove the trailing backtick.
-- Configure the ``<header>`` element and the `<value>`` element ` with your desired values under **headerMappings.mapping.headers**. +- Configure the ``<header>`` element and the ``<value>`` element with your desired values under **headerMappings.mapping.headers**.
2541-2547: Typo: “biding” → “binding”.Fix spelling in SAML config comment.
- # SAML relying party (SP) assertion consumer service biding (POST or REDIRECT) + # SAML relying party (SP) assertion consumer service binding (POST or REDIRECT)source/by-role/system-admin/upgrade/upgrading-server.rst (1)
162-169: Inconsistent sync paths in example output.Log shows 4.1.0 → 4.1.1 despite the example being 4.4.4 → 5.0.0. Update for coherence.
-Synching files from /Users/myuser/crafter-4.1.0/bin to /Users/myuser/crafter-4.1.1/bin... +Synching files from /Users/myuser/crafter-5.0.0/bin to /Users/myuser/crafter-4-4-4/bin...
♻️ Duplicate comments (2)
source/release-notes/5-x-breaking-changes.rst (1)
138-139: Cross-reference ‘content-processors-configuration’.Known pending anchor added via another PR; just ensure it’s merged before publishing.
source/release-notes/5-0-0.rst (1)
228-231: Duplicate action name in removal/replacement.Likely meant to remove fetchSandboxItemComplete and replace with fetchContentItemComplete (matches surrounding renames).
- - Removed ``fetchContentItemComplete`` action. Replaced by ``fetchContentItemComplete``. + - Removed ``fetchSandboxItemComplete`` action. Replaced by ``fetchContentItemComplete``.
🧹 Nitpick comments (4)
source/reference/modules/engine.rst (2)
1624-1639: Section title/content mismatch (ETag vs Content-Length).The section is titled “Content-Length Headers” but shows ETag properties. Either retitle the section or swap the example to actual Content-Length settings (if any). Suggest retitle for accuracy.
-.. _engine-content-length-headers: +.. _engine-content-length-headers: -"""""""""""""""""""""" -Content-Length Headers -"""""""""""""""""""""" -The following allows you to configure the content-length header sent for responses. -The content-length header is sent for all responses by default. +""""""""""" +ETag Header +""""""""""" +Configure the ETag header in responses. Disabled by default.
1074-1079: Remote includes point to 4.x branch. Verify intended version.The sample URLRewrite and Proxy Config use rli links under studio/support/4.x. If 5.x samples exist, consider updating; otherwise, add a short note that the 4.x samples remain valid.
Also applies to: 938-944
source/conf.py (1)
125-126: Duplicate templates_path assignment.Remove the second assignment to avoid confusion.
-html_js_files = ['js/custom.js'] -templates_path = ["_templates"] +html_js_files = ['js/custom.js']source/by-role/system-admin/upgrade/upgrading-server.rst (1)
20-21: Minor grammar: double space.Single-space “After running”.
-After running the upgrade script +After running the upgrade script
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (11)
source/by-role/developer/upgrade/index.rst(0 hunks)source/by-role/system-admin/upgrade/index.rst(0 hunks)source/by-role/system-admin/upgrade/upgrading-cluster.rst(0 hunks)source/by-role/system-admin/upgrade/upgrading-search.rst(3 hunks)source/by-role/system-admin/upgrade/upgrading-server.rst(16 hunks)source/conf.py(3 hunks)source/reference/modules/engine.rst(1 hunks)source/release-notes/5-0-0.rst(1 hunks)source/release-notes/5-x-breaking-changes.rst(1 hunks)source/release-notes/index.rst(1 hunks)source/support.rst(2 hunks)
💤 Files with no reviewable changes (3)
- source/by-role/system-admin/upgrade/index.rst
- source/by-role/developer/upgrade/index.rst
- source/by-role/system-admin/upgrade/upgrading-cluster.rst
🚧 Files skipped from review as they are similar to previous changes (1)
- source/support.rst
🧰 Additional context used
🧠 Learnings (7)
📓 Common learnings
Learnt from: alhambrav
Repo: craftercms/docs PR: 2062
File: source/release-notes/4-5-0.rst:7-7
Timestamp: 2025-09-23T14:20:52.728Z
Learning: In CrafterCMS release notes files, "Released *TBD, 2025*" placeholders are intentionally used during release preparation phase. The actual release date is only set once the product is officially released, not during the preparation phase.
📚 Learning: 2025-09-11T14:05:10.616Z
Learnt from: alhambrav
Repo: craftercms/docs PR: 1978
File: source/reference/modules/studio.rst:3370-3378
Timestamp: 2025-09-11T14:05:10.616Z
Learning: When reviewing CrafterCMS documentation, code blocks and configuration examples must accurately reflect the actual source code implementation, even if there appear to be inconsistencies in naming or approaches. The documentation should not be "cleaned up" to show ideal consistency if that would make it inaccurate relative to what the source code actually provides.
Applied to files:
source/reference/modules/engine.rstsource/release-notes/5-0-0.rst
📚 Learning: 2025-09-23T14:38:36.051Z
Learnt from: alhambrav
Repo: craftercms/docs PR: 2062
File: source/reference/modules/studio.rst:3205-3205
Timestamp: 2025-09-23T14:38:36.051Z
Learning: The CrafterCMS documentation team maintains fidelity with source code - sample code in documentation reflects the actual source code implementation, and documentation updates are synchronized with source code changes rather than being updated independently.
Applied to files:
source/reference/modules/engine.rstsource/release-notes/index.rstsource/release-notes/5-0-0.rst
📚 Learning: 2025-09-23T14:20:52.728Z
Learnt from: alhambrav
Repo: craftercms/docs PR: 2062
File: source/release-notes/4-5-0.rst:7-7
Timestamp: 2025-09-23T14:20:52.728Z
Learning: In CrafterCMS release notes files, "Released *TBD, 2025*" placeholders are intentionally used during release preparation phase. The actual release date is only set once the product is officially released, not during the preparation phase.
Applied to files:
source/release-notes/index.rstsource/release-notes/5-0-0.rstsource/by-role/system-admin/upgrade/upgrading-server.rst
📚 Learning: 2025-08-08T14:42:29.830Z
Learnt from: alhambrav
Repo: craftercms/docs PR: 2044
File: source/by-role/developer/common/content-modeling/content-modeling.rst:699-704
Timestamp: 2025-08-08T14:42:29.830Z
Learning: In docs file source/by-role/developer/common/content-modeling/content-modeling.rst, the team wants to keep a reminder about the upcoming “Form Engine Controller” docs (tracked in GitHub issue #8313). For future reviews, avoid blocking on a TODO placeholder; suggest a non-breaking rst comment or a note admonition instead of an rst `.. todo` directive.
Applied to files:
source/release-notes/5-x-breaking-changes.rstsource/release-notes/5-0-0.rst
📚 Learning: 2025-08-21T14:50:04.744Z
Learnt from: alhambrav
Repo: craftercms/docs PR: 2049
File: source/by-role/system-admin/configuration.rst:671-673
Timestamp: 2025-08-21T14:50:04.744Z
Learning: In RST/Sphinx documentation, anchor tags usually appear before section marker characters (like `-----`), and explicit `.. _<label>:` declarations are not always required for section references to resolve correctly. References can resolve across multiple files in a documentation project based on section titles and implicit referencing.
Applied to files:
source/release-notes/5-x-breaking-changes.rst
📚 Learning: 2025-09-02T20:40:32.613Z
Learnt from: alhambrav
Repo: craftercms/docs PR: 2042
File: source/reference/modules/studio.rst:0-0
Timestamp: 2025-09-02T20:40:32.613Z
Learning: When reviewing CrafterCMS Studio documentation, property names in configuration examples should match the actual Studio source code implementation, even if the underlying Git config keys are different. Studio may have a translation layer that maps Studio property names to actual Git configuration keys.
Applied to files:
source/release-notes/5-0-0.rst
🔇 Additional comments (3)
source/by-role/system-admin/upgrade/upgrading-search.rst (1)
20-51: LGTM (clear 4.0.x → OpenSearch path).The flow aligns with the server upgrade guide and JDK 21 requirement. No issues.
source/release-notes/index.rst (1)
9-15: LGTM (5.0.0 index and “Released TBD” placeholder).Placeholder is acceptable pre‑release; links look consistent.
source/release-notes/5-0-0.rst (1)
137-141: Prop rename summary reads well.The sxs/sx changes look consistent with component list; nice cleanup.
If you want, I can scan Studio UI CHANGELOG to confirm any lingering mismatches.
|
Update upgrading sections, commit: b399ebe for craftercms/craftercms#8326 |
|
Add updated dependencies and update breaking changes for removed OpenSearch method |
|
Commit ab19ea9 and 0a7b1e7 Add note that getDescriptor is now removed craftercms/craftercms#8294 |
There was a problem hiding this comment.
Actionable comments posted: 2
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
source/reference/modules/studio.rst (1)
3356-3433: Update publishing blacklist section to consistently use pathspecs (not regex).The example and surrounding prose reference the deprecated
studio.configuration.publishing.blacklist.regexproperty, which was replaced bystudio.configuration.publishing.blacklist.pathspecsin CrafterCMS 5.0.0 (see breaking changes documentation). The main configuration block correctly shows the new property, but the example code uses the old property—users copying the example will get non-functional configuration.Update all references across the section:
- Replace "regex" terminology with "pathspecs" in prose and comments
- Change
studio.configuration.publishing.blacklist.regextostudio.configuration.publishing.blacklist.pathspecsin the example- Update log messages to reference "pathspecs" instead of "regex patterns"
- Convert the example regex pattern to git pathspec syntax
Proposed diff
-A comma-separated list of regexes is used to configure items that should not be published. +A list of git pathspecs is used to configure items that should not be published. -Add the following lines with the regex for the item you wish not to be published. By default, ``.keep`` files are not published by CrafterCMS. Just add a ``,`` then your regex after ``.*/\.keep``: +Add the following line(s) with the pathspec(s) for the items you wish not to be published. By default, ``.keep`` files are not published by CrafterCMS. -[DEBUG] 2021-04-22T08:16:01,023 [studio.clockTaskExecutor-42] [deployment.PublishingManagerImpl] | File /static-assets/css/.keep of the site mysite will not be published because it matches the configured publishing blacklist regex patterns. +[DEBUG] 2021-04-22T08:16:01,023 [studio.clockTaskExecutor-42] [deployment.PublishingManagerImpl] | File /static-assets/css/.keep of the site mysite will not be published because it matches the configured publishing blacklist pathspecs. -Say, you do not want files under ``/static-assets/images/mytempimages`` to be published when a user performs a bulk publish or *Approve & Publish* of multiple items from the dashboard. We'll add to the ``studio.configuration.publishing.blacklist.regex`` the regex for items under ``/static-assets/images/mytempimages`` +Say, you do not want files under ``/static-assets/images/mytempimages`` to be published when a user performs a bulk publish or *Approve & Publish* of multiple items from the dashboard. We'll add a pathspec for items under ``/static-assets/images/mytempimages`` -.. code-block:: yaml - :caption: *studio-config-override.yaml* - - # Publishing blacklist configuration, items matching regexes on this list will never be published - studio.configuration.publishing.blacklist.regex: >- - .*/\.keep,\/static-assets\/images\/mytempimages\/.* +.. code-block:: yaml + :caption: *studio-config-override.yaml* + + # Publishing blacklist configuration, items matching pathspecs on this list will never be published + studio.configuration.publishing.blacklist.pathspecs: "/static-assets/images/mytempimages/**" -[DEBUG] 2021-04-22T12:48:28,992 [studio.clockTaskExecutor-36] [deployment.PublishingManagerImpl] | File /static-assets/images/mytempimages/26072150271_848c0008f0_o.jpg of the site mysite will not be published because it matches the configured publishing blacklist regex patterns. +[DEBUG] 2021-04-22T12:48:28,992 [studio.clockTaskExecutor-36] [deployment.PublishingManagerImpl] | File /static-assets/images/mytempimages/26072150271_848c0008f0_o.jpg of the site mysite will not be published because it matches the configured publishing blacklist pathspecs.
🤖 Fix all issues with AI agents
In `@source/release-notes/5-x-breaking-changes.rst`:
- Around line 79-86: The wording claiming "the entire file will be commented
out" is misleading; update the documentation around controller.groovy and the
Upgrade Manager to state that the script's original body will be commented out
but an active logger.error(...) statement will be left at top-level so the
script still runs and logs an error; adjust the paragraph in the 79-86 section
(and the similar wording in 91-128) to match the example by explicitly
describing that only the original controller body is commented while a
logger.error line remains active for administrators to notice.
- Around line 59-77: The YAML example for the new publishing blacklist property
has an extra leading space on the line with
studio.configuration.publishing.blacklist.pathspecs which makes it misaligned
with the previous YAML block; fix it by removing the extra indentation so the
property line aligns exactly like the earlier code-block example (ensure the
line containing studio.configuration.publishing.blacklist.pathspecs: "" has the
same indentation level as the other top-level YAML keys in that section).
♻️ Duplicate comments (1)
source/release-notes/5-x-breaking-changes.rst (1)
140-141: Cross-ref depends on label existing at release time (content-processors-configuration).If that label isn’t in the same release-doc set at merge time, Sphinx will fail with an unresolved
:ref:. Please ensure the label lands before the 5.0.0 docs ship (or adjust the link to an existing target).
🧹 Nitpick comments (1)
source/support.rst (1)
24-28: LGTM! New 5.0 version entry is well-structured.The new table row for version 5.0 is correctly formatted with appropriate TBD placeholders (expected during release preparation) and proper RST link syntax.
Optional observation: The Version column includes a download link for 5.0 but not for other active versions like 4.4. If this is intentional to highlight the latest release, no change is needed. Otherwise, consider adding download links for other active versions for consistency.
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (5)
source/index.rstsource/reference/modules/engine.rstsource/reference/modules/studio.rstsource/release-notes/5-x-breaking-changes.rstsource/support.rst
🚧 Files skipped from review as they are similar to previous changes (2)
- source/index.rst
- source/reference/modules/engine.rst
🧰 Additional context used
🧠 Learnings (5)
📚 Learning: 2025-08-08T14:42:29.830Z
Learnt from: alhambrav
Repo: craftercms/docs PR: 2044
File: source/by-role/developer/common/content-modeling/content-modeling.rst:699-704
Timestamp: 2025-08-08T14:42:29.830Z
Learning: In docs file source/by-role/developer/common/content-modeling/content-modeling.rst, the team wants to keep a reminder about the upcoming “Form Engine Controller” docs (tracked in GitHub issue `#8313`). For future reviews, avoid blocking on a TODO placeholder; suggest a non-breaking rst comment or a note admonition instead of an rst `.. todo` directive.
Applied to files:
source/support.rstsource/release-notes/5-x-breaking-changes.rst
📚 Learning: 2025-09-23T14:20:52.728Z
Learnt from: alhambrav
Repo: craftercms/docs PR: 2062
File: source/release-notes/4-5-0.rst:7-7
Timestamp: 2025-09-23T14:20:52.728Z
Learning: In CrafterCMS release notes files, "Released *TBD, 2025*" placeholders are intentionally used during release preparation phase. The actual release date is only set once the product is officially released, not during the preparation phase.
Applied to files:
source/support.rst
📚 Learning: 2025-08-21T14:50:04.744Z
Learnt from: alhambrav
Repo: craftercms/docs PR: 2049
File: source/by-role/system-admin/configuration.rst:671-673
Timestamp: 2025-08-21T14:50:04.744Z
Learning: In RST/Sphinx documentation, anchor tags usually appear before section marker characters (like `-----`), and explicit `.. _<label>:` declarations are not always required for section references to resolve correctly. References can resolve across multiple files in a documentation project based on section titles and implicit referencing.
Applied to files:
source/release-notes/5-x-breaking-changes.rst
📚 Learning: 2025-09-11T14:05:10.616Z
Learnt from: alhambrav
Repo: craftercms/docs PR: 1978
File: source/reference/modules/studio.rst:3370-3378
Timestamp: 2025-09-11T14:05:10.616Z
Learning: When reviewing CrafterCMS documentation, code blocks and configuration examples must accurately reflect the actual source code implementation, even if there appear to be inconsistencies in naming or approaches. The documentation should not be "cleaned up" to show ideal consistency if that would make it inaccurate relative to what the source code actually provides.
Applied to files:
source/release-notes/5-x-breaking-changes.rstsource/reference/modules/studio.rst
📚 Learning: 2025-09-02T20:40:32.613Z
Learnt from: alhambrav
Repo: craftercms/docs PR: 2042
File: source/reference/modules/studio.rst:0-0
Timestamp: 2025-09-02T20:40:32.613Z
Learning: When reviewing CrafterCMS Studio documentation, property names in configuration examples should match the actual Studio source code implementation, even if the underlying Git config keys are different. Studio may have a translation layer that maps Studio property names to actual Git configuration keys.
Applied to files:
source/reference/modules/studio.rst
🔇 Additional comments (1)
source/support.rst (1)
2-2: LGTM!The
last-updatedversion bump to 5.0.0 aligns with the PR objective of adding 5.0.0 release notes.
✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.
| - Publishing blacklist configuration has been changed. |br| | ||
| From a regex: | ||
|
|
||
| .. code-block:: yaml | ||
| :caption: *Old property for the publishing blacklist* | ||
| studio.configuration.publishing.blacklist.regex: >- | ||
| .*/\.keep | ||
| To a git `pathspec <https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefpathspecapathspec>`__ | ||
| that is empty by default because ``.keep`` files are always excluded: | ||
|
|
||
| .. code-block:: yaml | ||
| :caption: *New property for the publishing blacklist* | ||
| :emphasize-lines: 1 | ||
| studio.configuration.publishing.blacklist.pathspecs: "" | ||
| See :ref:`publishing-blacklist` for more information. |
There was a problem hiding this comment.
YAML snippet indentation: keep consistent to avoid confusing rendered examples.
Line 75 is indented one space more than necessary vs the earlier YAML example; it’ll still render, but consistency helps copy/paste.
Proposed diff
- studio.configuration.publishing.blacklist.pathspecs: ""
+ studio.configuration.publishing.blacklist.pathspecs: ""📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| - Publishing blacklist configuration has been changed. |br| | |
| From a regex: | |
| .. code-block:: yaml | |
| :caption: *Old property for the publishing blacklist* | |
| studio.configuration.publishing.blacklist.regex: >- | |
| .*/\.keep | |
| To a git `pathspec <https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefpathspecapathspec>`__ | |
| that is empty by default because ``.keep`` files are always excluded: | |
| .. code-block:: yaml | |
| :caption: *New property for the publishing blacklist* | |
| :emphasize-lines: 1 | |
| studio.configuration.publishing.blacklist.pathspecs: "" | |
| See :ref:`publishing-blacklist` for more information. | |
| - Publishing blacklist configuration has been changed. |br| | |
| From a regex: | |
| .. code-block:: yaml | |
| :caption: *Old property for the publishing blacklist* | |
| studio.configuration.publishing.blacklist.regex: >- | |
| .*/\.keep | |
| To a git `pathspec <https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefpathspecapathspec>`__ | |
| that is empty by default because ``.keep`` files are always excluded: | |
| .. code-block:: yaml | |
| :caption: *New property for the publishing blacklist* | |
| :emphasize-lines: 1 | |
| studio.configuration.publishing.blacklist.pathspecs: "" | |
| See :ref:`publishing-blacklist` for more information. |
🤖 Prompt for AI Agents
In `@source/release-notes/5-x-breaking-changes.rst` around lines 59 - 77, The YAML
example for the new publishing blacklist property has an extra leading space on
the line with studio.configuration.publishing.blacklist.pathspecs which makes it
misaligned with the previous YAML block; fix it by removing the extra
indentation so the property line aligns exactly like the earlier code-block
example (ensure the line containing
studio.configuration.publishing.blacklist.pathspecs: "" has the same indentation
level as the other top-level YAML keys in that section).
| - Content type controllers now use the new content lifecycle API |br| | ||
| When upgrading to CrafterCMS version 5.0.0, the Upgrade Manager will compare ``controller.groovy`` to the | ||
| default script from built-in blueprints. If they match, the script will be deleted. | ||
|
|
||
| If they don't match, the entire file will be commented out and a ``logger.error`` statement will be added so admins | ||
| can manually check and fix as required. Below is an example of a commented out controller script after upgrading to | ||
| version 5.0. Notice the ``logger.error`` statement added: | ||
|
|
There was a problem hiding this comment.
Clarify “commented out controller” behavior (example doesn’t match the wording).
The text says “the entire file will be commented out”, but the example shows the original body commented out while leaving an active logger.error(...) so the script still executes and logs an error. Suggest rewording to match the shown behavior.
Proposed diff
- If they don't match, the entire file will be commented out and a ``logger.error`` statement will be added so admins
+ If they don't match, the original file contents will be commented out and replaced with an active ``logger.error`` statement so admins
can manually check and fix as required. Below is an example of a commented out controller script after upgrading to
version 5.0. Notice the ``logger.error`` statement added:Also applies to: 91-128
🤖 Prompt for AI Agents
In `@source/release-notes/5-x-breaking-changes.rst` around lines 79 - 86, The
wording claiming "the entire file will be commented out" is misleading; update
the documentation around controller.groovy and the Upgrade Manager to state that
the script's original body will be commented out but an active logger.error(...)
statement will be left at top-level so the script still runs and logs an error;
adjust the paragraph in the 79-86 section (and the similar wording in 91-128) to
match the example by explicitly describing that only the original controller
body is commented while a logger.error line remains active for administrators to
notice.
2 participants
Ticket reference or full description of what's in the PR
Add release notes for 5.0.0