Skip to content

Add ONBOARDING.md engineering onboarding guide for dotCMS core #36113

Description

@nollymar

Description

Add a single consolidated ONBOARDING.md at the repo root to serve as the Engineering department's onboarding entry point, designed to be opened in Claude Code.

It complements CLAUDE.md (does not duplicate it) and merges the still-useful content from the existing dotBackendOnboarding.md and dotFrontendOnboarding.md, while correcting stale versions to the current stack (Java 25, Node 22.15+, Angular 19+).

Covers:

  • Day-one environment setup — sdk env install / nvm use, just commands, Docker-by-default, recommended IDEs, an enterprise proxy/network section, and the Apple Silicon / Puppeteer Chromium fix
  • Codebase mental model — com.dotcms.* (modern) vs com.dotmarketing.* (legacy); backend vs frontend build worlds
  • Fast testing workflows — targeted integration tests, the IDE loop, Postman, and Spectator conventions (never run the full suite)
  • Repo landmines — BOM-only versions, auto-generated openapi.yaml, Config/Logger rules, REST @Schema
  • Local config — admin password, feature flags, JSP/Tomcat-root mounting, language overrides
  • First-PR flow, available Claude Code skills, and a people/comms section

Excludes (intentionally): dotCMS Utilities and license setup.

Acceptance Criteria

  • ONBOARDING.md exists at the repo root
  • Versions are current: Java 25, Node 22.15+, Angular 19+ (no stale 18.x / PrimeNG 17 / Nx 19 references)
  • Complements CLAUDE.md and links to /docs/ rather than duplicating content
  • Includes the enterprise proxy/network section (no secrets embedded — points to where credentials live)
  • Includes the Apple Silicon / Puppeteer Chromium troubleshooting steps
  • Does not include dotCMS Utilities or license setup
  • Team-specific placeholders (Slack channels, CODEOWNERS, doc links, CI/merge-queue rules, owning team) are clearly marked for the owning team to fill in

Additional Context

Intended to be shareable department-wide via Claude Code's onboarding-guide feature. Several <<PLACEHOLDER>> markers remain by design for org-specific values that can't be derived from the repo. Delivered as a draft PR (not ready for review) pending those fill-ins.

Metadata

Metadata

Assignees

Type

No fields configured for Task.

Projects

Status
In Progress

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions