docs: add ONBOARDING.md engineering onboarding guide by nollymar · Pull Request #36114 · dotCMS/core

nollymar · 2026-06-10T23:18:27Z

What

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

Closes #36113

Why

We had two partially-overlapping, stale onboarding docs (dotBackendOnboarding.md, dotFrontendOnboarding.md) pinned to old versions (Node 18, Angular 18, PrimeNG 17, Nx 19). This consolidates the still-useful content into one current guide that complements CLAUDE.md instead of duplicating it, and links back to the two discipline-specific guides for deeper detail.

What's in it

Day-one setup — sdk env install / nvm use, just commands, Docker-by-default, recommended IDEs, and the Apple Silicon / Puppeteer Chromium fix
Codebase mental model — com.dotcms.* (modern) vs com.dotmarketing.* (legacy); backend vs frontend build worlds
Fast testing — targeted integration tests, IDE loop, Postman, Spectator conventions (never the full suite)
Repo landmines — BOM-only versions, auto-generated openapi.yaml, Config/Logger, REST @Schema
Local config — admin password, feature flags (on-by-default, DOT_ prefix, FeatureFlagName.java reference), JSP/Tomcat mounting, language overrides
First-PR flow — including how the GitHub native merge queue works (merge_group branch, required checks: tests + security + 1 approval, ~1h average to merge)
Claude Code skills available in the repo
People & comms — Slack channels (#eng, #eng-adrs, #be-code-review, #guild-*, #feat-*, #team-*); everything else points to the How we do Engineering doc

Versions corrected throughout to Java 25, Node 22.15+, Angular 19+.

Also links to the discipline-specific dotFrontendOnboarding.md and dotBackendOnboarding.md guides.

Intentionally excluded

dotCMS Utilities
License setup
Enterprise proxy / network setup (removed — not needed)

Status

All team-specific placeholders have been filled in — no <<PLACEHOLDER>> values remain. Ready for review.

Remaining follow-up (not blocking):

Decide whether to delete/redirect the old dotBackendOnboarding.md / dotFrontendOnboarding.md

🤖 Generated with Claude Code

Add a consolidated ONBOARDING.md at the repo root as the Engineering department's onboarding entry point, designed to be opened in Claude Code. Complements CLAUDE.md and merges still-useful content from dotBackendOnboarding.md and dotFrontendOnboarding.md, correcting stale versions to the current stack (Java 25, Node 22.15+, Angular 19+). Excludes dotCMS Utilities and license setup. Team-specific values (Slack channels, CODEOWNERS, doc links, CI/merge-queue rules) remain as placeholders for the owning team to fill in. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

claude · 2026-06-10T23:19:31Z

Claude finished @nollymar's task in 46s —— View job

Rollback Safety Analysis

Read rollback-unsafe categories reference
Get full PR diff
Analyze changes against unsafe categories
Apply appropriate label

Result: ✅ Safe to Roll Back

All three changed files are pure documentation:

File	Change
`CLAUDE.md`	1-line version bump: Angular 19+ → 21+
`ONBOARDING.md`	New file — 296 lines of onboarding docs
`dotFrontendOnboarding.md`	Tech stack version numbers updated (Angular, PrimeNG, Nx, Node)

None of the changes touch any rollback-unsafe category:

No database migrations / runonce tasks
No Elasticsearch mapping changes
No contentlet_as_json model version bump
No DROP TABLE / DROP COLUMN / RENAME
No REST/GraphQL API contract changes
No OSGi interface changes
No binary storage provider changes

The label AI: Safe To Rollback has been applied.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

github-actions · 2026-06-24T20:52:32Z

🤖 Bedrock Review — `qwen.qwen3-next-80b-a3b`

No issues found.

_{Run: #28128759972 · tokens: in: 4764 · out: 14 · total: 4778}

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

github-actions · 2026-06-24T21:01:35Z

🤖 Bedrock Review — `qwen.qwen3-next-80b-a3b`

New Issues

🟡 Medium: ONBOARDING.md:288 — Suggests using export DOT_INITIAL_ADMIN_PASSWORD=admin without warning that this password is stored in shell history and may be logged in CI/CD environments; no guidance on secure secret handling (e.g., vaults, encrypted env vars). Assumption: This value is used in production-like environments. What to verify: Whether DOT_INITIAL_ADMIN_PASSWORD is ever used outside dev/local setup, and if so, whether it's being passed via insecure channels in CI.

Existing

No prior findings to recheck.

Resolved

No resolved items.

_{Run: #28129231461 · tokens: in: 4749 · out: 188 · total: 4937}

… 21, Nx 22) Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

github-actions · 2026-06-24T21:19:17Z

🤖 Bedrock Review — `qwen.qwen3-next-80b-a3b`

New Issues

🟡 Medium: ONBOARDING.md:288 — Suggests using DOT_INITIAL_ADMIN_PASSWORD without warning about insecure storage in shell history or CI/CD environments (repeats prior finding)

Existing

🟡 Medium: ONBOARDING.md:288 — Suggests using DOT_INITIAL_ADMIN_PASSWORD without warning about insecure storage in shell history or CI/CD environments

Resolved

✅ dotFrontendOnboarding.md:7-11 — Angular/Node/Nx version updates are accurate and aligned with .nvmrc and repo requirements; no convention violation introduced.

_{Run: #28130244057 · tokens: in: 5139 · out: 191 · total: 5330}

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

github-actions · 2026-06-24T21:34:09Z

🤖 Bedrock Review — `qwen.qwen3-next-80b-a3b`

New Issues

🟡 Medium: ONBOARDING.md:288 — Suggests using DOT_INITIAL_ADMIN_PASSWORD without warning about insecure storage in shell history or CI/CD environments

Existing

🟡 Medium: ONBOARDING.md:288 — Prior finding still present (unchanged or incomplete fix)

Resolved

✅ CLAUDE.md:87 — Frontend Angular version update from 19+ to 21+ is intentional and aligned with dotFrontendOnboarding.md

_{Run: #28131029699 · tokens: in: 5358 · out: 171 · total: 5529}

mergify · 2026-06-24T21:38:39Z

Tick the box to add this pull request to the merge queue (same as @mergifyio queue).

Queue this pull request

fabrizzio-dotCMS · 2026-06-24T21:41:20Z

+     validation (test run green), security checks for code vulnerabilities, and at
+     least **1 reviewer approval**.
+   - **Typical wait:** ~1 hour average to merge.
+   - Pipeline reference: [`docs/core/CICD_PIPELINE.md`](docs/core/CICD_PIPELINE.md).


Shouldn't this also include the setup of PGP for verified commits?

good point! yes!

fabrizzio-dotCMS · 2026-06-24T21:49:37Z

+│       └── dotmarketing/   # Legacy (15+ yrs), still very much alive
+├── core-web/               # Frontend: Angular 21+ / Nx monorepo (see core-web/CLAUDE.md)
+├── dotcms-integration/     # Integration tests (DB + Elasticsearch)
+├── dotcms-postman/         # Postman API tests


test-karate ?

fabrizzio-dotCMS · 2026-06-24T21:51:41Z

+// ✅ test user-visible behavior, not implementation details
+spectator.click(byTestId('save-button'));
+expect(spectator.query(byTestId('success-message'))).toBeVisible();
+```


Perhaps a section explaining what a starter is
Where and how it gets deployed
and a link to our artifactory

github-project-automation Bot added this to dotCMS - Product Planning Jun 10, 2026

github-actions Bot mentioned this pull request Jun 10, 2026

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

Open

7 tasks

github-actions Bot added the Area : Documentation PR changes documentation files label Jun 10, 2026

claude Bot added the AI: Safe To Rollback label Jun 10, 2026

docs: refine ONBOARDING.md (merge queue, feature flags, Slack, cleanup)

90c5b13

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

github-actions Bot removed the AI: Safe To Rollback label Jun 24, 2026

claude Bot added the AI: Safe To Rollback label Jun 24, 2026

docs: link discipline-specific onboarding guides, drop fill-in note

e654547

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

github-actions Bot removed the AI: Safe To Rollback label Jun 24, 2026

claude Bot added the AI: Safe To Rollback label Jun 24, 2026

nollymar marked this pull request as ready for review June 24, 2026 21:02

docs: sync onboarding versions with current repo (Angular 21, PrimeNG…

56bb249

… 21, Nx 22) Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

github-actions Bot removed the AI: Safe To Rollback label Jun 24, 2026

claude Bot added the AI: Safe To Rollback label Jun 24, 2026

docs: bump CLAUDE.md frontend version to Angular 21+

bf1dfd9

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

github-actions Bot removed the AI: Safe To Rollback label Jun 24, 2026

claude Bot added the AI: Safe To Rollback label Jun 24, 2026

jcastro-dotcms approved these changes Jun 24, 2026

View reviewed changes

fabrizzio-dotCMS reviewed Jun 24, 2026

View reviewed changes

erickgonzalez approved these changes Jun 25, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs: add ONBOARDING.md engineering onboarding guide#36114

docs: add ONBOARDING.md engineering onboarding guide#36114
nollymar wants to merge 5 commits into
mainfrom
docs/team-onboarding-guide

nollymar commented Jun 10, 2026 •

edited

Loading

Uh oh!

claude Bot commented Jun 10, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jun 24, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jun 24, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jun 24, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jun 24, 2026 •

edited

Loading

Uh oh!

mergify Bot commented Jun 24, 2026

Uh oh!

fabrizzio-dotCMS Jun 24, 2026

Uh oh!

nollymar Jun 24, 2026

Uh oh!

fabrizzio-dotCMS Jun 24, 2026

Uh oh!

fabrizzio-dotCMS Jun 24, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Uh oh!

Conversation

nollymar commented Jun 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What

Why

What's in it

Intentionally excluded

Status

Uh oh!

claude Bot commented Jun 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Rollback Safety Analysis

Result: ✅ Safe to Roll Back

Uh oh!

github-actions Bot commented Jun 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🤖 Bedrock Review — qwen.qwen3-next-80b-a3b

Uh oh!

github-actions Bot commented Jun 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🤖 Bedrock Review — qwen.qwen3-next-80b-a3b

New Issues

Existing

Resolved

Uh oh!

github-actions Bot commented Jun 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🤖 Bedrock Review — qwen.qwen3-next-80b-a3b

New Issues

Existing

Resolved

Uh oh!

github-actions Bot commented Jun 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🤖 Bedrock Review — qwen.qwen3-next-80b-a3b

New Issues

Existing

Resolved

Uh oh!

mergify Bot commented Jun 24, 2026

Uh oh!

fabrizzio-dotCMS Jun 24, 2026

Choose a reason for hiding this comment

Uh oh!

nollymar Jun 24, 2026

Choose a reason for hiding this comment

Uh oh!

fabrizzio-dotCMS Jun 24, 2026

Choose a reason for hiding this comment

Uh oh!

fabrizzio-dotCMS Jun 24, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

nollymar commented Jun 10, 2026 •

edited

Loading

claude Bot commented Jun 10, 2026 •

edited

Loading

github-actions Bot commented Jun 24, 2026 •

edited

Loading

🤖 Bedrock Review — `qwen.qwen3-next-80b-a3b`

github-actions Bot commented Jun 24, 2026 •

edited

Loading

🤖 Bedrock Review — `qwen.qwen3-next-80b-a3b`

github-actions Bot commented Jun 24, 2026 •

edited

Loading

🤖 Bedrock Review — `qwen.qwen3-next-80b-a3b`

github-actions Bot commented Jun 24, 2026 •

edited

Loading

🤖 Bedrock Review — `qwen.qwen3-next-80b-a3b`