Skip to content

Restructure CONTRIBUTING.md around the route to a first pull request - #2076

Merged
Kevinjohn merged 43 commits into
mainfrom
issue/1983-contributing-route
Nov 16, 2026
Merged

Kevinjohn merged 43 commits into
mainfrom
issue/1983-contributing-route

Conversation

@Kevinjohn

@Kevinjohn Kevinjohn commented Nov 16, 2026 •

Copy link
Copy Markdown
Owner

What and why

CONTRIBUTING.md put a historical review, Lucid soft-delete notes and the beta transfer contract between setup and the pre-PR checks. It now follows the route from clone to first pull request (389 → 342 lines):

  • Two entry points at the top: Making your first change? and Back for another pull request?
  • Your first change: clone, set up, try pnpm run dev:demo, find the code with the README's Where do I edit? map (Add a “Where do I edit?” map to the README #1982), make one focused edit, prove it with a failing test, run the checks, commit with -s, open the pull request. The mutation-check instruction stays at step 6, which docs-src/reference/how-it-is-tested.md:18 cites.
  • Set up, Daily development (dev, dev:demo, check:changed), Checks by change type (a table for docs, frontend, backend, shared and dependency changes), Before opening a pull request (the gate:all + e2e gate, cross-browser suites and the CI summary as it stands after Restructure CI around pull requests, merges to main, weekly checks and tagged releases #1970), then Pull requests.
  • Formatting, engineering standards, documentation publishing, runtime upgrades, packaged-dialog acceptance, reference records and releases follow, unchanged.
  • The specialist sections move unchanged to the documentation site and are linked from a Reference records list:
    • AdonisJS review record → docs-src/security/reviews.md#adonisjs-review-record
    • Lucid soft-delete integration → docs-src/reference/architecture.md#lucid-soft-delete-integration
    • Beta transfer contract → docs-src/reference/architecture.md#beta-transfer-implementation, linked from the reader-facing rules in Settings.
  • Existing inbound anchors (#your-first-change, #documentation-and-github-pages, used by README.md) still resolve. docs/ is regenerated.

Checked: every command in the table exists in package.json (dev, dev:demo, check:changed, format, docs:build, gate:all, e2e); check:changed runs related frontend tests (scripts/check-changed.mjs:438) and importing backend specs; a first-time docs edit can go from a clean clone to a signed-off PR following only the guide.

Decisions made without the owner

  • Release and Pages publication instructions stay in CONTRIBUTING.md (at the end), because the repository has no separate maintainer guide to move them to.

Closes #1983

Gate evidence

  • pnpm run check:changed <predecessor branch>: passed (format, lint, documentation policy and the docs build and comparison where docs changed)
  • Pre-push check:push (format, type-check, lint): passed.
  • Validation workflow on this head: run 43858689207
  • Stack tip gate on issue/2029-move-review-evidence, which contains this branch: gate:all passed (560 backend tests) and e2e passed (309 tests).

Merge order

#2060 → #2061 → #2062 → #2063 → #2064 → #2065 → #2066 → #2067 → #2068 → #2069 → #2070 → #2071 → #2072 → #2073 → #2074 → #2075 → #2076 → #2077 → #2078 → #2079 → #2080 → #2081 → #2082 → #2083 → #2084 → #2085 → #2086

Merge predecessor for this PR: #2075.

Conflicts:

Step 2.1 of #2031. The 23 restoration tests move unchanged into four
files beside each other in tests/functional/planning/:
- restoration_allocations.spec.ts: the delete and restore cycle;
- restoration_sessions.spec.ts: session, actor and company binding;
- restoration_catalogue.spec.ts: catalogue, time-off and closure rows;
- restoration_pending_groups.spec.ts: changes that clear pending groups.
Each keeps its group title and setup. The shared request helpers move
to restoration_helpers.ts. The architecture reference names the new
files.

Signed-off-by: Kevinjohn Gallagher <kevinjohngallagher@hotmail.com>
Step 2.2 of #2031. The 57 AppShell tests move unchanged into six files:
- AppShell.memberView.test.tsx: member-view projection states;
- AppShell.companyEntry.test.tsx: joined-account handoff and the sole
  company the directory opens;
- AppShell.navigation.test.tsx: navigation links, titles and order;
- AppShell.sidebar.test.tsx: collapse, icons and Cmd/Ctrl+B;
- AppShell.keyboard.test.tsx: undo/redo and command palette shortcuts;
- AppShell.test.tsx: hydration, planning problems, the write guard and
  transient notices.
The shared hooks, fetch stub and render helpers move to
AppShell.testSupport.tsx; each file keeps its own @/i18n mock, because
vi.mock is hoisted per file. The three account-directory variables
become properties of one exported object, the only change to any test
body. LocationProbe moves to src/test/LocationProbe.tsx.

Signed-off-by: Kevinjohn Gallagher <kevinjohngallagher@hotmail.com>
Step 2.3 of #2031, continuing the schedulerModel.*.test.ts split. The 56
tests move unchanged; the 640-line buildSchedulerModel group is divided
by behaviour, each part keeping its describe title:
- schedulerModel.filters.test.ts: tentative, project, activity,
  discipline, unmatched and search filters;
- schedulerModel.placeholders.test.ts: placeholder rows and ordering;
- schedulerModel.visibleWindow.test.ts: utilisation over the visible
  window and the fixed overSoon window;
- schedulerModel.grouping.test.ts: engagement bands, the external band
  and Disciplines off;
- schedulerModel.internal.test.ts: the Internal client and repeatable
  allocations;
- schedulerModel.test.ts keeps the core build, corrupt ranges, the
  company working week and non-active resources.
makeDisciplines and barIds move to schedulerModel.testSupport.ts.

Signed-off-by: Kevinjohn Gallagher <kevinjohngallagher@hotmail.com>
Step 2.4 of #2031. The 67 capacity tests move unchanged:
- capacity/availability.test.ts: availability boundaries, the
  availability and allocatedHoursOnDay groups and isHalfDay;
- capacity/advisory.test.ts: capacityAdvisory;
- capacity/advisoryCopy.test.ts: formatCapacityAdvisory;
- capacity/primitives.test.ts gains capacityAllocationsForMode and the
  devAssertFinite group;
- capacity.test.ts keeps the effective-week characterisation, the
  semantics table, dayCapacity, utilisation and the window checks,
  which exercise the composed functions in capacity.ts.
The shared wrappers, factories and makeProposal move to
capacity/capacityTestSupport.ts.

Signed-off-by: Kevinjohn Gallagher <kevinjohngallagher@hotmail.com>
Step 2.5 of #2031. mutations.ts only re-exports the assertion modules,
so its 74 message tests move unchanged next to the code they cover:
- assertions/refs.messages.test.ts: getOwned, assertScopedRefs and
  assertAllocationRefs;
- assertions/dependents.messages.test.ts: assertDateRange,
  assertResourceExists, the resource-kind guard and the placeholder
  project rebinding checks.
They import from refs.ts and dependents.ts directly. The fixtures move
to assertions/assertionMessagesTestSupport.ts. The message checks stay
in their own files, apart from the error-code checks in refs.test.ts
and dependents.test.ts, whose header comments now name the new files.

Signed-off-by: Kevinjohn Gallagher <kevinjohngallagher@hotmail.com>
For #1984. AGENTS.md repeated the scheduling invariants and the
admission and first-company rules. It now links to the Scheduling
invariants and Accounts, admission and security sections for anyone
changing allocations or admission, and keeps the config path.

Four first-company constraints were stated only in AGENTS.md; they move
into DECISIONS.md: the signup refusal is rechecked under the identity
creation lock, the controlled first identity can still finish setup,
the configured signup policy applies once the first company exists, and
the stopped-server initializer is never the normal install path and,
like the browser path, creates no credentials and changes no admission.

Signed-off-by: Kevinjohn Gallagher <kevinjohngallagher@hotmail.com>
For #1991. The quick start, both install guides and the Owner guide now
say, at the end of the terminal step, that the installer prints a
one-time setup link after "Open this setup link at https://DOMAIN:"
(packaging/release/install.sh:86), and that the operator opens it when
they are the Owner or sends it privately to the Owner otherwise. The
browser step names the Accept invite page, its Name and Password fields
and Accept invitation. The quick start no longer repeats the
link-opening instruction. docs/ is regenerated.

Signed-off-by: Kevinjohn Gallagher <kevinjohngallagher@hotmail.com>
For #1992. Every guide page now ends with "Report a problem with this
page", which opens the new Documentation feedback issue form with its
page field set to the public address of that guide. The address is
built from the page's route and the published base, so the committed
offline copy reports the same public URL and no local path, query
string or account detail reaches the form. The link uses the theme's
doc-after slot, because the footer slot is not rendered on pages that
turn off previous/next links. docs/ is regenerated.

Signed-off-by: Kevinjohn Gallagher <kevinjohngallagher@hotmail.com>
For #2030. The folder held comparison material for a documentation
direction that has been chosen: three sample treatments, research
notes, an FAQ appendix, generated previews and their builder and test
(87 files). Its direction, conclusions, source observations and
evidence limits are now recorded in #1846, with a permalink to the
folder at f65766b, the last main commit that contains it. Nothing
outside the folder referred to it.

Signed-off-by: Kevinjohn Gallagher <kevinjohngallagher@hotmail.com>
For #1982. The contributor section now has a task-to-directory table
for apps/frontend, apps/backend, packages/shared (with its domain and
lib folders, where the shared scheduling rules live), docs-src, docs and
user-stories, and says how guide sources, generated offline
documentation and acceptance criteria differ. It links to the
architecture reference for module detail. documentation-exploration/ is
left out because #2030 removes it.

Signed-off-by: Kevinjohn Gallagher <kevinjohngallagher@hotmail.com>
For #2040. A short list under the tagline states what CapacityLens is,
who it is for, licence and cost, requirements, status with the release
link, and links to the demo, install guide and documentation. Each line
restates the README or the introduction page; the narrative stays below.

Signed-off-by: Kevinjohn Gallagher <kevinjohngallagher@hotmail.com>
For #2041. The introduction page now states the category in plain
terms (self-hosted resource scheduling and capacity planning, by the
week), and both it and the README gain an Alternatives paragraph naming
Float, Productive, awork, Runn, Teamwork, Resource Guru and eResource
Scheduler. It says those tools each cover several jobs, that
CapacityLens does less, and that anyone needing budgets, timesheets,
hour-level booking or a hosted service should choose one of them. The
README's fact block from #2040 already states the category. docs/ is
regenerated.

Signed-off-by: Kevinjohn Gallagher <kevinjohngallagher@hotmail.com>
For #2042. The README's Install section now has the one-command install
block, copied from docs-src/self-hosting/install-without-docker.md, with
its prerequisites on one line, a note that the command asks no
questions (packaging/release/install.sh reads no input) and prints the
setup link, and the readiness check: /health/ready answers HTTP 200
with "isHealthy":true, or 503 when the database checks fail
(apps/backend/start/routes.ts:36). The install guide's step 5 states
the same expected response. A documentation policy test fails when the
README block and the guide's block differ or either loses the success
check. No install duration is given: no repository source states one.

Signed-off-by: Kevinjohn Gallagher <kevinjohngallagher@hotmail.com>
For #1983. The guide now opens with two entry points: a first-change
walkthrough (clone, set up, try the demo, find the code with the README
map, make a focused edit, check it, open a signed-off PR) and a checks
table by change type for returning contributors. Set up, daily
development, checks, the submission gate with the CI summary and pull
requests come in reading order; formatting, engineering standards,
documentation publishing, runtime upgrades, packaged-dialog acceptance
and releases follow.

The specialist material moves, unchanged, to the documentation site:
the AdonisJS review record to Reviews and compliance, and the Lucid
soft-delete integration and the beta transfer contract to the
architecture reference, each linked from a Reference records list.
Existing anchors used elsewhere (#your-first-change, step 6, and

Signed-off-by: Kevinjohn Gallagher <kevinjohngallagher@hotmail.com>
#documentation-and-github-pages) still resolve. docs/ is regenerated.
…restoration-spec

Signed-off-by: Kevinjohn Gallagher <kevinjohngallagher@hotmail.com>
…031-step-2-part-2-appshell-tests

Signed-off-by: Kevinjohn Gallagher <kevinjohngallagher@hotmail.com>
…1-step-2-part-3-scheduler-model-tests

Signed-off-by: Kevinjohn Gallagher <kevinjohngallagher@hotmail.com>
…sue/2031-step-2-part-4-capacity-tests

Signed-off-by: Kevinjohn Gallagher <kevinjohngallagher@hotmail.com>
…1-step-2-part-5-mutations-tests

Signed-off-by: Kevinjohn Gallagher <kevinjohngallagher@hotmail.com>
…84-decisions-authoritative

Signed-off-by: Kevinjohn Gallagher <kevinjohngallagher@hotmail.com>
…taller-owner-handoff

Signed-off-by: Kevinjohn Gallagher <kevinjohngallagher@hotmail.com>

# Conflicts:
#	docs/getting-started/quick-start.html
#	docs/owner/index.html
…s-feedback-links

Signed-off-by: Kevinjohn Gallagher <kevinjohngallagher@hotmail.com>

# Conflicts:
#	docs/admin/add-people.html
#	docs/admin/company-settings.html
#	docs/admin/diagnostics.html
#	docs/admin/first-booking.html
#	docs/admin/invite-teammates.html
#	docs/admin/ongoing-administration.html
#	docs/admin/prepare-work.html
#	docs/getting-started/quick-start.html
#	docs/getting-started/roles-and-permissions.html
#	docs/getting-started/try-the-demo.html
#	docs/getting-started/what-is-capacitylens.html
#	docs/owner/appoint-an-admin.html
#	docs/owner/index.html
#	docs/using/account.html
#	docs/using/activities.html
#	docs/using/disciplines.html
#	docs/using/editor.html
#	docs/using/help.html
#	docs/using/join-your-team.html
#	docs/using/overview.html
#	docs/using/projects.html
#	docs/using/read-the-schedule.html
#	docs/using/resources.html
#	docs/using/schedule-work.html
#	docs/using/settings.html
#	docs/using/team-access.html
#	docs/using/time-off.html
#	docs/using/viewer.html
…documentation-exploration

Signed-off-by: Kevinjohn Gallagher <kevinjohngallagher@hotmail.com>
…/1982-readme-edit-map

Signed-off-by: Kevinjohn Gallagher <kevinjohngallagher@hotmail.com>
…-block

Signed-off-by: Kevinjohn Gallagher <kevinjohngallagher@hotmail.com>
…alternatives

Signed-off-by: Kevinjohn Gallagher <kevinjohngallagher@hotmail.com>

# Conflicts:
#	docs/getting-started/what-is-capacitylens.html
…e-install-block

Signed-off-by: Kevinjohn Gallagher <kevinjohngallagher@hotmail.com>
…buting-route

Signed-off-by: Kevinjohn Gallagher <kevinjohngallagher@hotmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

polish-done Polish review complete

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Shorten CONTRIBUTING.md to the route from clone to first PR

1 participant