First Contribution¶

Use this page when you are preparing your first code or documentation change.

Development setup¶

Read Architecture overview, Principles, and Identity and execution model.
Start backend and frontend using Local development.
Keep /admin, /manager, /portal, /browser, /ceph-admin, and /storage-ops vocabulary separate.
For UI changes, read Product design guidelines, Workspace surface separation, and UI theme guidelines.

Pull request validation¶

Open the PR checks on GitHub to follow validation, including from a fork. The CI / required result summarizes the expected checks; individual runs expose logs and downloadable reports. No access to private GitLab or Ceph credentials is needed. See CI/CD to understand selection and reproduce a command. Use the Node version in frontend/.node-version.

Change checklist¶

Change type	Read first	Minimum validation
Backend route/service	Backend architecture, identity model, API reference	Targeted pytest and explicit error-case check.
Frontend workspace page	Product design guidelines, workspace separation	Typecheck, focused Vitest, and browser smoke when route rendering matters.
Portal behavior	Workspace separation, Portal user docs	Portal tests plus storage-space permission reasoning.
Ops behavior	Ops configuration and security pages	MkDocs strict build and deployment command review.
Documentation	Docs maintenance	MkDocs strict build and screenshot check for user pages.

Local validation commands¶

Backend: cd backend && PYTHONPATH=. ./.venv/bin/pytest tests -q
Frontend: cd frontend && npm test
Browser E2E: cd frontend && npm run test:e2e
Docs: python3 doc/build_docs.py --strict
User screenshots: npm --prefix frontend run docs:screenshots:check

Common mistakes¶

Treating UI role as storage permission.
Mixing S3 accounts and S3 connections.
Adding Portal IAM concepts to user-facing Portal copy.
Changing a route without updating the docs coverage matrix.
Relying on typecheck alone for a route that can fail at runtime.