Repository navigation
docs(cssholmes): document the alpha 1 workflows - #8
Merged
mambax7 merged 3 commits intoOct 27, 2026
Merged
Conversation
Reviewer's GuideThis documentation-focused release slice replaces the legacy project overview with Alpha 1 release, compatibility, and operational guidance, adds extensive illustrated designer/xStyles/theme-set workflows and schema documentation, and clearly records the current XOOPS 4 migration boundary and validation evidence. File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
|
Important Review skippedAuto reviews are disabled on base/target branches other than the default branch. Please check the settings in the CodeRabbit UI or the
 |
There was a problem hiding this comment.
Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota.
An organization owner can choose the repository organization as the billing source for reviews requested by members with a paid Copilot license. Learn about Copilot code review billing.
Closed
![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 5 issues
Prompt for AI Agents
Please address the comments from this code review:
## Individual Comments
### Comment 1
<location path="README.md" line_range="23" />
<code_context>
+Back up the site's files and database before an installed-module upgrade.
-Please visit us on https://xoops.org
+From an installed module directory, `php tests/run.php` runs the isolated PHP
+regressions plus the analyzer, CLI and diagnostic PHPUnit tests using shared
+`xoops_lib/vendor/bin/phpunit`. For a separate checkout, set `XOOPS_VENDOR_PATH`
</code_context>
<issue_to_address>
**Documented test commands cannot run**
When a contributor follows the README or visual designer verification instructions, the documented `tests/run.php`, `tests/designer-*.php`, `tests/designer-client.cjs` and related test scripts are absent, so the PHP and Node commands fail with missing-file errors instead of running the advertised checks.
Add the referenced test scripts or update both guides to document verification commands that exist in the repository.
Also at `docs/compatibility.md:17-20`, `docs/visual-designer.md:138-143`, `docs/xoops4-migration.md:63-67`.
</issue_to_address>
### Comment 2
<location path="README.md" line_range="30-31" />
<code_context>
-Current and upcoming "next generation" versions of XOOPS CMS are crafted on GitHub at: https://github.com/XOOPS
+Source and issues: [mambax7/cssholmes](https://github.com/mambax7/cssholmes).
+The repository's CI checks PHP 8.4/8.5; release tags run CI before creating a
+clean module ZIP. Qodana is optional and explicitly skips its scan when
+`QODANA_TOKEN` is unavailable. A skipped scan is not a quality result.
+
</code_context>
<issue_to_address>
**Release automation is absent**
When a maintainer relies on the checked-in repository configuration to run CI or package a release, the repository contains no GitHub Actions workflows or `qodana.yaml`, so pushes and release tags cannot run the promised PHP CI, create a clean module ZIP, or execute the documented Qodana workflow.
Add the described workflow and Qodana configuration files, or revise the documentation to match the automation actually present.
Also at `docs/compatibility.md:61-62`.
</issue_to_address>
### Comment 3
<location path="docs/TUTORIAL-cssholmes-XTF-XMF-v2.md" line_range="127-129" />
<code_context>
+Activate with a query parameter:
+
+```
+/?holmes=xtf-theme,xtf-widget
+/?holmes=all
+/modules/cssholmes/admin/index.php?holmes=xtf-theme,a11y
+```
+
</code_context>
<issue_to_address>
**Tutorial overlay examples do not activate**
When the site's `holmes_query_key` preference is not `holmes`, the tutorial URLs use `holmes` literally, but `preloads/core.php` reads the configured `holmes_query_key`, so the overlay stays inactive and the documented diagnostics are unavailable.
Use the configured query key in the examples, or explain how to substitute it.
Also at `docs/TUTORIAL-cssholmes-XTF-XMF-v2.md:91`, `docs/TUTORIAL-cssholmes-XTF-XMF-v2.md:212-218`, `docs/TUTORIAL-cssholmes-XTF-XMF-v2.md:317-326`, `docs/TUTORIAL-cssholmes-XTF-XMF-v2.md:365`, `docs/TUTORIAL-cssholmes-XTF-XMF-v2.md:530`, `docs/TUTORIAL-cssholmes-XTF-XMF-v2.md:619`.
</issue_to_address>
### Comment 4
<location path="docs/TUTORIAL-cssholmes-XTF-XMF-v2.md" line_range="1" />
<code_context>
+# cssHolmes Tutorial — XTF Themes and XMF Widgets
+
+**Audience:** XOOPS designers, theme builders, theme editors, widget developers
</code_context>
<issue_to_address>
**In-module tutorial pointer stays broken**
When a user follows the tutorial pointer in the module help, the module help still names `docs/TUTORIAL-cssholmes-XTF-XMF.md`, which is absent; users following that pointer cannot reach this newly added tutorial.
Update the help template to point to the new tutorial filename.
</issue_to_address>
### Comment 5
<location path="docs/TUTORIAL-cssholmes-XTF-XMF-v2.md" line_range="32" />
<code_context>
+If no `theme.json` manifest is detected, cssHolmes switches to generic mode.
+HTML5, accessibility, layout, inspection, measurement, copy, and export still
+work. Only the XTF-specific tools (token matching, slot jumping, theme
+scanning) stay disabled.
+
+
</code_context>
<issue_to_address>
**Generic themes said to lack scanning**
When the site has a generic XOOPS theme without `theme.json`, the tutorial says theme scanning is disabled without `theme.json`, but `ThemeCatalog` also discovers generic themes containing `theme.tpl` or `theme.html`; users following the guide skip a scan the workbench supports.
Clarify that XTF-specific checks are unavailable but generic theme scanning remains available, with manifest-dependent checks skipped.
</issue_to_address>Sourcery assessment
Approval pending. 3 findings to address first.
Blocking findings: README.md:23, README.md:31, docs/TUTORIAL-cssholmes-XTF-XMF-v2.md:129
| Back up the site's files and database before an installed-module upgrade. | ||
|
|
||
| Please visit us on https://xoops.org | ||
| From an installed module directory, `php tests/run.php` runs the isolated PHP |
There was a problem hiding this comment.
🟡 Medium · Documented test commands cannot run
When a contributor follows the README or visual designer verification instructions, the documented tests/run.php, tests/designer-*.php, tests/designer-client.cjs and related test scripts are absent, so the PHP and Node commands fail with missing-file errors instead of running the advertised checks.
Add the referenced test scripts or update both guides to document verification commands that exist in the repository.
Also at docs/compatibility.md:17-20, docs/visual-designer.md:138-143, docs/xoops4-migration.md:63-67.
Prompt for AI agents
In `README.md` at line 23:
**Documented test commands cannot run**
When a contributor follows the README or visual designer verification instructions, the documented `tests/run.php`, `tests/designer-*.php`, `tests/designer-client.cjs` and related test scripts are absent, so the PHP and Node commands fail with missing-file errors instead of running the advertised checks.
Add the referenced test scripts or update both guides to document verification commands that exist in the repository.
Also at `docs/compatibility.md:17-20`, `docs/visual-designer.md:138-143`, `docs/xoops4-migration.md:63-67`.| @@ -0,0 +1,694 @@ | |||
| # cssHolmes Tutorial — XTF Themes and XMF Widgets | |||
There was a problem hiding this comment.
⚪ Low · In-module tutorial pointer stays broken
When a user follows the tutorial pointer in the module help, the module help still names docs/TUTORIAL-cssholmes-XTF-XMF.md, which is absent; users following that pointer cannot reach this newly added tutorial.
Update the help template to point to the new tutorial filename.
Prompt for AI agents
In `docs/TUTORIAL-cssholmes-XTF-XMF-v2.md` at line 1:
**In-module tutorial pointer stays broken**
When a user follows the tutorial pointer in the module help, the module help still names `docs/TUTORIAL-cssholmes-XTF-XMF.md`, which is absent; users following that pointer cannot reach this newly added tutorial.
Update the help template to point to the new tutorial filename.
| "color": {"$ref": "#/$defs/cssColor"}, "background-color": {"$ref": "#/$defs/cssColor"}, "border-color": {"$ref": "#/$defs/cssColor"}, | ||
| "font-size": {"$ref": "#/$defs/cssLength"}, "gap": {"$ref": "#/$defs/cssLength"}, | ||
| "border-width": {"$ref": "#/$defs/cssLength"}, "border-radius": {"$ref": "#/$defs/cssLength"}, | ||
| "width": {"anyOf": [{"$ref": "#/$defs/cssLength"}, {"const": "auto"}]}, "height": {"$ref": "#/$defs/cssLength"}, |
| # cssHolmes Tutorial — XTF Themes and XMF Widgets | ||
|
|
||
| **Audience:** XOOPS designers, theme builders, theme editors, widget developers | ||
| **Requires:** XOOPS 2.5.12+, cssHolmes installed and activated |
Comment on lines
+74
to
+76
| When cssHolmes inspects an element, it can tell you which slot it belongs to, | ||
| which widget rendered it, and which token (if any) controls its color. That | ||
| is the information browser devtools cannot provide. |
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
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.
Summary
Part 3 of the cssHolmes 3.3.0 Alpha 1 release, split from #5 to keep automated reviews below 100 files. This PR changes 48 files.
Illustrated tutorial, release notes, compatibility evidence and module documentation.
Review and merge order
Runtime → presentation → documentation → quality. Base:
review/alpha1-2-presentation. These are dependent review slices; the complete fourth branch is the release candidate. Do not deploy an intermediate slice.The combined tree exactly matches release candidate
9b75e84ea2839b96dba219f80d531513ce34a9fa; splitting introduces no source changes.Validation
The complete candidate passed local PHP 8.4/8.5 checks and browser regressions. A clean package was installed and upgraded from 3.0.0 on a disposable XOOPS 2.7.4-RC2 site, including normal login, editor save/reload, anonymous published CSS, CSRF checks and restore. Hosted CI passed on the complete candidate. The final upstream branch will also run CI before release.
No module-local vendor dependencies are added. PHP 8.4+ is required. Admin-theme publishing and native XOOPS 4 installation remain outside this alpha.
Summary by Sourcery
Document the cssHolmes Alpha 1 workflows, release boundaries, compatibility evidence, and theme-design capabilities for users and maintainers.
Enhancements:
Documentation: