[DREAM-821] Refresh stale frontend documentation - #25139
Open
myabc wants to merge 6 commits into
Open
Conversation
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
The updated plugin code example in frontend/doc/PLUGINS.md introduces types/decorators without showing the required imports, so the snippet still won’t type-check as written.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Pull request overview
This PR updates OpenProject’s frontend documentation to reflect the current tooling and architecture (Vitest + Playwright browser tests, Lookbook instead of the removed Living Style Guide), and removes an unused jsdom dependency and related shims from the frontend test setup.
Changes:
- Refresh
frontend/doc/(testing, plugins, directory structure, build instructions) and add cross-links intodocs/development/. - Remove
jsdomfromfrontend/package.json/package-lock.jsonand drop jsdom-targeted shims fromfrontend/src/test-setup.ts. - Delete obsolete
frontend/doc/STYLING.mdcontent tied to the removed Living Style Guide.
File summaries
| File | Description |
|---|---|
| frontend/src/turbo/dispatch-event-stream-action.spec.ts | Adjusts a comment to be environment-agnostic after dropping jsdom. |
| frontend/src/test-setup.ts | Removes jsdom-specific shims now that specs run in real browsers. |
| frontend/package.json | Drops jsdom devDependency. |
| frontend/package-lock.json | Removes jsdom and its transitive dependencies from the lockfile. |
| frontend/doc/TESTING.md | Rewrites frontend testing docs to match Vitest/Playwright and current patterns. |
| frontend/doc/STYLING.md | Removes obsolete styleguide-era documentation. |
| frontend/doc/README.md | Updates build/test/styleguide sections and adds directory structure overview. |
| frontend/doc/PLUGINS.md | Updates plugin-linking paths and corrects the hook callback example. |
| frontend/AGENTS.md | Streamlines agent-facing commands and links to canonical docs. |
| docs/development/testing/running-tests-locally/README.md | Adds a pointer to frontend spec-writing guidance in frontend/doc/TESTING.md. |
| docs/development/style-guide/frontend/README.md | Links back to frontend/doc/ for day-to-day frontend workflows. |
Review details
Files not reviewed (1)
- frontend/package-lock.json: Generated file
- Files reviewed: 10/11 changed files
- Comments generated: 1
- Review effort level: Lite
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
myabc
added
documentation
maintenance
javascript
myabc
force-pushed
the
code-maintenance/dream-821-refresh-frontend-docs
branch
3 times, most recently
from
September 5, 2026 14:00
31f5161 to
737ef3e
Compare
myabc
marked this pull request as ready for review
September 5, 2026 14:25
|
Caution The provided work package version does not match the core version Details:
Please make sure that:
|
Plugins symlink into `features/plugins/linked/` and the generated module is `linked-plugins.module.ts`; both paths still named the `modules/` tree they were moved out of. Costs is a bundled module loaded from `Gemfile.modules` rather than an external plugin to clone, and the repository it linked has been archived since 2018. The example reached for lodash, declared a `params` argument the hook never passes, set a `resource` key nothing reads, and named its types without importing them, so it could not be copied into a plugin entry point. It now compiles: extracted from the markdown and run through `tsc -p tsconfig.app.json`. https://community.openproject.org/wp/DREAM-821
The Living Styleguide is gone: no route serves it, `styleguide.html` is absent and no `.lsg` partials remain, so `STYLING.md` documented nothing that still exists. Lookbook covers components and styling now. Neither build command was valid, tests no longer run on karma-jasmine, the styles pointer named a directory that does not exist, and the lockfile claim contradicted the lockfile. The dev server is described as what it is: a proxy for two paths, not a catch-all, so contributors know to reach application pages through Rails. https://community.openproject.org/wp/DREAM-821
The guide framed Angular as the current approach and cited a spec path that moved long ago. Rails with Hotwire is current; Angular is legacy, though it still bootstraps every run. Documents what was previously only discoverable by reading the config: specs run in real browsers, the two Stimulus helpers serve different purposes, and the Node tooling suite exists. How to invoke the runner is left to the guide that already covers it. Both examples compile, checked by extracting the fenced blocks and running them through `tsc`. https://community.openproject.org/wp/DREAM-821
Frontend documentation drifted partly because it sat apart from `docs/` with no route between the two. `AGENTS.md` keeps the commands and constraints an agent needs in context and defers the prose to documents that can be opened on demand, linked within the checkout so they match the branch being worked on. `frontend/doc` links out by published URL instead, because TypeDoc renders those pages and copies relative Markdown into `media/`, landing readers on raw files. Inbound links use GitHub URLs, since `frontend/doc` is not part of the published site. https://community.openproject.org/wp/DREAM-821
No airbnb config is installed and `eslint.config.mjs` never referenced one; format comes from `@stylistic` house rules and `.editorconfig`. Pointing at the enforcement is truthful where naming an external guide was not. Also marks the Angular pattern material as legacy, since the page is now linked from `AGENTS.md` while new development uses Hotwire. https://community.openproject.org/wp/DREAM-821
Specs run in real browsers, so the CSS.escape, ResizeObserver and HTMLDialogElement shims guarding against jsdom's gaps never fired. All three are removed along with the dependency itself, which nothing else pulls in.
myabc
force-pushed
the
code-maintenance/dream-821-refresh-frontend-docs
branch
from
September 5, 2026 14:58
737ef3e to
48293c9
Compare
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.
Ticket
https://community.openproject.org/wp/DREAM-821
What are you trying to accomplish?
Refresh frontend documentation that sends contributors toward retired tooling, obsolete plugin repositories and incorrect development instructions. The guides now describe the current setup and testing approach, with Hotwire as the direction for new development and Angular identified as legacy.
What approach did you choose and why?
Keep frontend-specific guidance here and link to existing application documentation for shared topics, reducing duplication and future drift. Agent instructions retain essential commands and point to guidance in the checkout; human-facing links work in both GitHub and the generated TypeDoc reference.
The testing guide explains how to test Stimulus controllers through markup or in isolation, including the Angular bootstrap dependency. Examples were checked against the implementation and type-checked.
The documentation audit also identified unused jsdom dependencies and shims, which are removed because application specs run in real browsers.
Rewriting the broader frontend style guide for Hotwire remains in DREAM-823; this PR marks its existing Angular guidance as legacy.
Screenshots
Merge checklist