docs: comprehensive documentation overhaul — verified guides, user guide with screenshots, ADR record, agent rules#494
Merged
Merged
Conversation
Captured at 1440x900 from the seeded e2e stack with demo data: login, worklog grid (view + inline edit), bulk entry, month overview, evaluation (filters + breakdowns), billing export, three admin panels, settings, help, shortcut overlay and command palette. Signed-off-by: Sebastian Mendel <info@sebastianmendel.de>
…md symlinks - PHPStan level 9 -> 10 and PSR-12 -> PER-CS + Symfony in root/src/tests files - new scoped AGENTS.md for the SolidJS frontend and the Playwright e2e suite - CLAUDE.md symlinks next to every AGENTS.md so Claude picks up scoped rules Signed-off-by: Sebastian Mendel <info@sebastianmendel.de>
The Help page only explained the Worklog. It now opens with a 'The pages' section describing Worklog, Overview, Evaluation, Billing, Administration and Settings (with the role hint for the last three's visibility), and the links section points to the new online user guide. Messages added in both locales. Signed-off-by: Sebastian Mendel <info@sebastianmendel.de>
…n the current UI - new docs/user-guide.md walks through every feature with screenshots: login, worklog grid, bulk entry, overview calendar, evaluation, billing, all ten admin panels, settings, shortcuts, command palette, Jira sync - features.md: correct the role model (USER/DEV/PL/ADMIN — CTL never existed in v5), drop the unimplemented Timalytics claim, link the guide - FAQ.md: remove ExtJS-era answers (a/d/e shortcuts, context menus, per-entry sync checkboxes) and answer only what the current app does Signed-off-by: Sebastian Mendel <info@sebastianmendel.de>
… verified reality The previous versions described infrastructure this app never had (doctrine fixtures, Husky, ParaTest, Panther, MySQL 8.0 CI, ~50 invented env vars and app:* console commands). Replaced with lean guides derived from Makefile, composer.json, compose.yml, .env*, phpunit.xml.dist and the real CI workflows; configuration.md now documents the ticket-system admin fields (SERVER OAuth 1.0a vs CLOUD OAuth 2.0) and the internal-Jira ticket mirroring instead of fictional JIRA_* variables. Signed-off-by: Sebastian Mendel <info@sebastianmendel.de>
… security doc - DEPLOYMENT_GUIDE.md (2118 -> 288 lines): real prod stack from compose.yml and docker-bake.hcl, GHCR image tags, auto-migration entrypoint, /status/check health endpoint, mariadb-dump backup/restore and a production checklist — no more Redis/JWT/K8s/Prometheus fiction - TROUBLESHOOTING.md: only failure modes and commands that exist, incl. var/cache permissions, DATABASE_URL service-name pitfalls, LDAP dev fixtures, e2e stack readiness and Jira OAuth errors - security.md: role table matches UserType, CSRF description matches the stateless authenticate/logout token setup Signed-off-by: Sebastian Mendel <info@sebastianmendel.de>
- README index now lists all 17 ADRs (009-013 were missing) with honest statuses; never-implemented 'architectural themes' dropped - dated reality notes on ADRs whose bodies describe infrastructure that was never built (JWT, Redis layers, ParaTest, /api/v1, partitioning); bodies kept intact as historical records - ADR-001 superseded by ADR-015 (PHP 8.5 / Symfony 8 upgrade, d2e3c91) - ADR-016 documents the ExtJS -> SolidJS rewrite (#470, #490) - ADR-017 documents dual-mode Jira auth (Server OAuth 1.0a / Cloud OAuth 2.0 data model, #416) and amends ADR-003 - internal title/numbering fixes in ADR-009..013 Signed-off-by: Sebastian Mendel <info@sebastianmendel.de>
…files - README.md: hero screenshot, User Guide link, PHPUnit 13, PER-CS style, correct role model and .env/.env.local guidance, honest Jira OAuth claim - delete README.rst (stale duplicate of README.md: ExtJS shortcuts, compose.dev.yml, sentry.yml.dist, SERVICE_USERS — none exist), TASKS.md (abandoned 2025 upgrade notes) and docs/CODE_EXAMPLES.md (68 KB of examples for services this codebase never contained); all references updated (.envrc, copilot-instructions) - SECURITY.md: real tooling (Dependabot, CodeQL — not Snyk), v4 marked EOL - CONTRIBUTING.md: MariaDB not MySQL/Redis, attribute-based PHPUnit examples, PER-CS, working commands Signed-off-by: Sebastian Mendel <info@sebastianmendel.de>
- api.md: every endpoint heading now maps to a real route (fixed /getSummary POST, removed nonexistent /getProjectStructure, added missing real endpoints); auth section describes the actual LdapAuthenticator + stateless CSRF setup and the USER/DEV/PL/ADMIN role model - DTO doc: real routes per DTO and missing fields added - event doc: events ARE dispatched (after flush in the tracking actions); real subscriber constructor, priorities and context keys - repository doc: fabricated methods removed, real ones added Signed-off-by: Sebastian Mendel <info@sebastianmendel.de>
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request extensively updates the project's documentation, architecture decision records (ADRs), and guides to reflect the transition from PHP 8.4 / Symfony 7.3 to PHP 8.5 / Symfony 8.1, the replacement of ExtJS with a SolidJS frontend, and the addition of Jira Cloud support via OAuth 2.0. It also aligns the coding standards documentation with PER-CS and Symfony style guidelines, adds localized help content to the frontend, and introduces a comprehensive user guide. There are no review comments to assess, so I have no feedback to provide.
Important
The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #494 +/- ##
=========================================
Coverage 84.15% 84.15%
Complexity 2814 2814
=========================================
Files 187 187
Lines 7588 7588
=========================================
Hits 6386 6386
Misses 1202 1202
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
There was a problem hiding this comment.
Pull request overview
This pull request performs a large-scale documentation realignment to the repository’s current Symfony/SolidJS implementation, adds an illustrated end-user guide, updates/annotates ADRs for historical accuracy, and refreshes Copilot/agent guidance—plus a small in-app Help page update to link to the new guide.
Changes:
- Rewrites core docs (development/config/testing/deployment/troubleshooting/security/API) to match the actual codebase, commands, services, and infrastructure.
- Adds a comprehensive
docs/user-guide.md(with screenshots) and links it from the SPA Help page (EN/DE). - Corrects/extends ADR indexing and adds new ADRs (PHP 8.5/Symfony 8, SolidJS rewrite, Jira Cloud OAuth2), including “reality notes” on historically inaccurate ADRs.
Reviewed changes
Copilot reviewed 53 out of 68 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| tests/AGENTS.md | Updates testing agent rules to reflect current code style guidance. |
| TASKS.md | Removes stale, abandoned task tracking document. |
| src/AGENTS.md | Updates backend agent rules (PHPStan level/style guidance). |
| SECURITY.md | Refreshes supported versions and security tooling references. |
| README.rst | Removes stale duplicate README (legacy content). |
| README.md | Updates project overview, stack info, and adds link/image for the new user guide. |
| frontend/src/pages/Help.tsx | Adds “The pages” section and a link to the user guide in the in-app Help page. |
| frontend/messages/en.json | Adds EN i18n strings for the new Help sections/link. |
| frontend/messages/de.json | Adds DE i18n strings for the new Help sections/link. |
| frontend/AGENTS.md | Adds scoped frontend agent rules (bun/Solid/i18n/a11y conventions). |
| e2e/AGENTS.md | Adds scoped e2e agent rules (Playwright stack, users, frozen clock). |
| docs/xdebug-setup.md | Rewrites Xdebug setup docs to match current Docker images and make targets. |
| docs/user-guide.md | Adds a new comprehensive end-user guide with screenshots. |
| docs/TROUBLESHOOTING.md | Replaces fictional troubleshooting content with verified commands and real failure modes. |
| docs/techstack.md | Updates infra specifics (nginx tag) to match compose.yml. |
| docs/security.md | Aligns security documentation with implemented auth/roles/CSRF/encryption behavior. |
| docs/REPOSITORY_DOCUMENTATION.md | Updates repository-layer docs to match current repository methods and behaviors. |
| docs/features.md | Rewrites feature overview to match the SolidJS UI and current capabilities. |
| docs/FAQ.md | Replaces outdated FAQ with verified, current UI/workflow answers. |
| docs/EVENT_SYSTEM_DOCUMENTATION.md | Corrects event system documentation to match actual dispatch/subscriber wiring. |
| docs/DTO_DOCUMENTATION.md | Aligns DTO docs with current controllers/routes and mapping mechanisms. |
| docs/development.md | Rewrites development guide around Docker/make/bun workflows used by this repo. |
| docs/DEVELOPER_PHPUNIT_CUSTOMIZATION.md | Updates PHPUnit customization guidance for PHPUnit 13 and current test setup. |
| docs/configuration.md | Replaces fictional config with verified app + compose env vars and admin-managed settings. |
| docs/api.md | Aligns API documentation with current routing/authz model and endpoint reality. |
| docs/adr/README.md | Corrects ADR index and explains “reality note” policy for historical ADRs. |
| docs/adr/ADR-017-jira-cloud-oauth2.md | Adds ADR documenting Jira Cloud OAuth2 direction and current implementation state. |
| docs/adr/ADR-016-solidjs-frontend-rewrite.md | Adds ADR documenting ExtJS→SolidJS rewrite and verified stack. |
| docs/adr/ADR-015-php-8-5-symfony-8-upgrade.md | Adds ADR documenting PHP 8.5/Symfony 8 upgrade decision and current constraints. |
| docs/adr/ADR-013-testing-strategy.md | Renames/corrects ADR header and adds reality note about removed/nonexistent infra. |
| docs/adr/ADR-012-performance-optimization-strategy.md | Renames/corrects ADR header and adds reality note about nonexistent infra. |
| docs/adr/ADR-011-security-architecture.md | Renames/corrects ADR header references. |
| docs/adr/ADR-010-repository-pattern-refactoring.md | Renames/corrects ADR header references. |
| docs/adr/ADR-009-service-layer-pattern.md | Renames/corrects ADR header references and PHPStan level. |
| docs/adr/ADR-008-database-performance-optimization.md | Adds reality note clarifying unsupported/nonexistent infra claims. |
| docs/adr/ADR-007-api-design-patterns.md | Adds reality note clarifying JWT/versioned API claims were never implemented. |
| docs/adr/ADR-006-testing-philosophy.md | Adds reality note and marks superseded by ADR-013. |
| docs/adr/ADR-005-caching-strategy.md | Adds reality note clarifying Redis layer never existed (APCu-only). |
| docs/adr/ADR-004-authentication-strategy-ldap-local.md | Adds reality note clarifying local/JWT auth fallback never existed. |
| docs/adr/ADR-003-jira-integration-architecture.md | Marks ADR as amended by ADR-017. |
| docs/adr/ADR-001-php-8-4-symfony-7-3-selection.md | Marks ADR as superseded by ADR-015. |
| CONTRIBUTING.md | Updates contribution docs to reflect current stack, standards, and examples. |
| AGENTS.md | Updates root agent rules and adds pointers to new scoped agent docs. |
| .github/copilot-instructions.md | Updates Copilot instructions to reference README.md and removes TASKS.md mention. |
| .envrc | Updates docs pointers to README.md instead of removed README.rst. |
…ag link - src/AGENTS.md overview still said PSR-12 while the conventions section was already updated to PER-CS + Symfony - v4_EOL is a tag without a GitHub release, so /releases/tag/ 404s; link the tag tree instead Signed-off-by: Sebastian Mendel <info@sebastianmendel.de>
…, Alt badges The theme/density/layout section and the Alt-badge shortcut discovery were text-only; each now has a screenshot. Signed-off-by: Sebastian Mendel <info@sebastianmendel.de>
Adds the structure users expect from a GitHub project page: table of contents, About section, grouped feature list, screenshot gallery, first-login credentials for the dev stack, key-config table, a mermaid architecture diagram, and Usage/Testing/Deployment/Contributing/Security sections linking into docs/. Also documents the DCO sign-off requirement in CONTRIBUTING.md (the check was enforced but undocumented). Signed-off-by: Sebastian Mendel <info@sebastianmendel.de>
|
This was referenced Jul 2, 2026
CybotTM
added a commit
that referenced
this pull request
Jul 2, 2026
## Summary The Administration → Users form offered a **CTL** user type that the backend removed in v5: `User::setType()` runs the value through `UserType::from()` ([src/Enum/UserType.php](src/Enum/UserType.php) knows only `USER/DEV/PL/ADMIN`), so saving a user as CTL threw a `ValueError` and the save failed without a usable error message. Meanwhile `USER` and `ADMIN` — which the enum does support — were not selectable at all. The select now lists exactly the enum's assignable cases (USER/DEV/PL/ADMIN). The orphaned `admin_type_ctl` message is replaced by `admin_type_user`/`admin_type_admin` in both locales. Found while verifying the documentation in #494 (the user guide documents the USER/DEV/PL/ADMIN model). ## Verification - `bun run typecheck` (paraglide compile confirms no dangling message reference) - `bun run lint` - `bun run test` — 346 passing
CybotTM
added a commit
that referenced
this pull request
Jul 2, 2026
## Summary `COMPOSE_PROFILES=prod docker compose up -d` never served a page. Three stacked defects, found while verifying the deployment guide in #494: 1. **nginx upstream mismatch** — [`docker/nginx/default.conf`](docker/nginx/default.conf) forwards FastCGI to `phpfpm:9000`, but no service or network alias with that name existed → 502 for every PHP request. The `app` service now carries a `phpfpm` network alias. 2. **Missing `.env` in the production image** — `bin/console` / `public/index.php` boot Symfony Dotenv unconditionally and it throws when the file is absent → the auto-migration entrypoint died before PHP-FPM ever started (`[entrypoint] ERROR: database not reachable after 60s`). The image now ships an empty `.env`; all runtime configuration comes from real environment variables. 3. **Compose interpolation leak** — `APP_ENV=${APP_ENV:-prod}` picked up `dev` from the repository's committed Symfony `.env`, overriding the image's `ENV APP_ENV=prod`. Those lines are removed (image defaults rule) and the variables the app actually needs (`DATABASE_URL`, `APP_SECRET`, `LDAP_*`, branding, `SENTRY_DSN`) are passed through explicitly, with defaults matching the bundled `db` service. `APP_ENCRYPTION_KEY` is a bare passthrough because an empty string would defeat its `env(default:secret:…)` fallback. The deployment guide's workaround note is replaced by the actual behavior. ## Verification Rebuilt the production image (`docker buildx bake app`) and booted the prod profile without the dev override: - before: `502` on /login, entrypoint loop `database not reachable after 60s` - after: `/login` → **200**, `/status/check` → `{"loginStatus":false}`, FPM up, auto-migration completed
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
Full documentation overhaul: a verified-facts rewrite of the guides, a new illustrated user guide, a corrected ADR record, refreshed agent rules, an extended in-app Help page, and a full-structure README.
A 5-domain audit against the actual code found that, beyond routine drift, several large docs (DEPLOYMENT_GUIDE, CODE_EXAMPLES, TROUBLESHOOTING, configuration, development, testing, and ADRs 003–013) described infrastructure this application never had — Redis layers, JWT auth,
/api/v1, ParaTest/Panther suites, ~50 invented env vars andapp:*console commands. Everything replaced here was re-derived fromMakefile,composer.json,compose.yml,.env*,config/,src/and the real CI workflows; every command, route, env var and version in the new docs was verified to exist.What's in here
compose.yml/docker-bake.hcl/ the publish workflowfrontend/ande2e/,CLAUDE.mdsymlinks restored at all five levels/ui/help): new "The pages" section (EN+DE) and a link to the user guide — lint/typecheck/346 Vitest tests greenREADME.rst(stale duplicate),TASKS.md(abandoned 2025 notes),docs/CODE_EXAMPLES.md(68 KB of examples for services that never existed); all references updatedReview
Copilot raised 2 inline comments (PER-CS leftover in src/AGENTS.md, 404ing v4_EOL release link) — both fixed in 41fee70, threads replied to and resolved. Gemini reviewed with no findings.
Verification
make/composer/bin/consolecommand checked againstMakefile,composer.jsonscripts andsrc/Command/bun run lint,bun run typecheck,bun run test(346 passing), page visually verified in the running e2e stackFollow-ups (out of scope, found during verification)
docker/nginx/default.confforwards tophpfpm:9000but the prod compose service is namedapp— the deployment guide documents the alias workaround; compose.yml should probably gain aphpfpmnetwork aliasCTLuser type (frontend/src/admin/entities.ts) thatUserType::from()rejectsJiraAuthenticationServiceis OAuth1-only) — ADR-017 records this honestly