diff --git a/README.md b/README.md index ddbfccc..22b7817 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,58 @@ Repository for team IT2810-H26-T19 in IT2810-H26. +**Crate** - a searchable catalog of albums. Search by word, filter and sort the +results, open an album for detail, and persist ratings, reviews and a personal +wantlist ("crate"). + +IT2810 (NTNU) Project 2. Group T19: `erikhfj`, `robertky`, `evenkkl`, +`rachelks`. + +| | | +| ----------------- | --------------------------------------- | +| Current milestone | **M1 - spec and mockup**, due 2 October | +| Live prototype | http://it2810-19.idi.ntnu.no/project2 | +| Workflow | [`docs/WORKFLOW.md`](docs/WORKFLOW.md) | +| AI usage log | [`docs/AI-USAGE.md`](docs/AI-USAGE.md) | + +## Getting started + +Requires Node.js 24+ and [pnpm](https://pnpm.io) 10+. + +```bash +pnpm install +pnpm dev # Vite dev server on :5173 +``` + +Before opening a PR: + +```bash +pnpm format:check && pnpm lint && pnpm typecheck && pnpm test +``` + +All four must pass. CI runs the same thing. + +| Command | Purpose | +| ----------------------------------- | ---------------------------------- | +| `pnpm dev` | Vite dev server | +| `pnpm build` | Type-check + production build | +| `pnpm lint` | ESLint - must pass with 0 warnings | +| `pnpm format` / `pnpm format:check` | Prettier | +| `pnpm typecheck` | `tsc --noEmit` in every workspace | +| `pnpm test` | Vitest, single run | + +## Project status + +| Milestone | Due | Delivers | +| --------- | ------ | ----------------------------------------------------------------------------------------- | +| M1 | 2 Oct | Spec and mockup: GraphQL schema, architecture ADRs, UI sketch, client rendering mock data | +| M2 | 16 Oct | PostgreSQL + GraphQL backend on the VM, client interaction | +| M3 | 30 Oct | Beta: search, paging, sorting, filtering, accessibility, bærekraft | +| M4 | 13 Nov | Finished prototype and the full test suite | + +`client/` currently renders mock data. `server/` (PostgreSQL + GraphQL Yoga) +arrives in M2 and `e2e/` (Playwright) in M4. + ## Working in this repository `main` is protected - you cannot push to it directly. Work on a branch and @@ -22,3 +74,6 @@ Before a pull request can be merged: 3. **Pushing new commits dismisses the approval**, so if you change something after being approved, ask for another review. This is deliberate: what was approved is what gets merged. + +Branch naming, commit style, PR size and review expectations are in +[`docs/WORKFLOW.md`](docs/WORKFLOW.md). diff --git a/docs/AI-USAGE.md b/docs/AI-USAGE.md new file mode 100644 index 0000000..321d7e7 --- /dev/null +++ b/docs/AI-USAGE.md @@ -0,0 +1,45 @@ +# AI usage log + +IT2810 requires documentation of how AI tools were used, and that the group +shows its own control over the development. The control is visible in the +issues, the pull requests and the reviews. This table is the record of tool +usage behind that work. + +Everyone adds their own rows. Two rows in the middle have no tool in them on +purpose: they are where a person overruled what the tool proposed, which is +the part that matters most. + +| Date | Who | Tool | Used for | +| ---------- | -------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 2026-09-23 | erikhfj | opencode | Stack prototype (PostgreSQL, GraphQL Yoga, Drizzle, React + Apollo) to answer two design risks early: does Postgres FTS give case-insensitive single-term search, and does keyset paging stay correct across every sort mode. Verified live on the VM. **Closed unmerged**, kept as `archive/scaffold-prototype`. | +| 2026-09-23 | erikhfj | opencode | VM bootstrap scripts: PostgreSQL role and database, Node 24 via nvm, `crate-api` systemd unit, Apache `ProxyPass /graphql` | +| 2026-09-23 | erikhfj | opencode | Smoke tests against the running API. These caught three bugs the unit tests had missed: `GenreFacet.genre` shape drift from the SDL, drizzle expanding a JS array into scalar parameters inside a `::int[]` cast, and a missing review aggregate on `album(id:)` | +| 2026-09-24 | erikhfj | opencode | Plan to retire the prototype PR and re-land the work in milestone-sized PRs | +| 2026-09-24 | rachelks | - | **Overruled the plan.** Splitting generated code into smaller PRs would only fix the git cosmetics, so each issue must be implemented from its requirements by its owner. The prototype is a reference, not a source to copy from. Taken. | +| 2026-09-24 | robertky | - | **Overruled the plan.** Dropped the plan-before-code step as process for its own sake; clear issues plus PR descriptions that say what was done and tested are what reviewers read. Also: assign issues one milestone at a time, not all up front. Taken. | +| 2026-09-27 | rachelks | Codex (ChatGPT) | Discussed the UI specification for #29 and how to translate the project requirements into the planned interface. I reviewed and adapted the specification to the group's agreed design. | +| 2026-09-27 | robertky | Codex (ChatGPT) | Assisted with drafting the M1 GraphQL schema and data model for #2. I reviewed the model, kept database/resolvers out of M1, and incorporated peer-review feedback before merge. | +| 2026-09-28 | erikhfj | opencode | Tooling for #1: pnpm workspace, ESLint 9 flat config, Prettier, strict TypeScript, `AGENTS.md` | +| 2026-09-28 | rachelks | Codex (ChatGPT) | Assisted with reviewing #32 and diagnosing a Windows-specific formatting failure. Testing with `core.autocrlf=true` exposed the LF/CRLF issue; I reported it in the review and erikhfj fixed it with `.gitattributes` before merge. | +| 2026-09-28 | erikhfj | opencode | Review fix for #1: `.gitattributes` with `* text=auto eol=lf` after `core.autocrlf` broke `pnpm format:check` on Windows | +| 2026-09-28 | erikhfj | opencode | Workflow guide and this log for #4 | +| 2026-09-28 | evenkkl | Claude | Assisted with formulating a schema for the architecture decision in #3, and served as a sparring partner to help understand why we made the decisions we did. | +| 2026-09-28 | erikhfj | opencode | CI for #27: `quality` and `deploy` jobs, self-hosted runner registered on the VM, client bundle budget | +| 2026-09-28 | rachelks | Codex (ChatGPT) | Assisted with reviewing the CI workflow in #34. Identified that the `project2` runner label was not used by the deploy job. I reported it in the review, erikhfj then pinned the deploy job to the intended runner. | +| 2026-09-29 | erikhfj | opencode | Review fix for #27: `pull_request` no longer filters on `branches: [main]`, which had silently given stacked PRs zero CI runs | +| 2026-09-30 | rachelks | Codex (ChatGPT) | Assisted with reviewing the GraphQL schema in #35. I identified a missing paginated review connection required by the specification and requested changes; robertky corrected the schema before merge. | +| 2026-09-30 | robertky | Codex (ChatGPT) | Helped me interpret Rachel's schema review on #35. | +| 2026-09-30 | evenkkl | Claude | Assisted with formulating reviews of PR #35, and identifying additional areas for improvement. | +| 2026-10-01 | erikhfj | opencode | Answers to the open design questions: UUID as an `X-User-Id` header into the GraphQL context, narrowing facet counts, `id` tie-breakers, nulls last in both directions | +| 2026-10-01 | rachelks | Codex (ChatGPT) | Assisted with diagnosing the CI deploy failure after merge. The investigation traced the API restart issue to the `crate-api.service` check, `sudo` requiring a TTY, and a race while waiting for the API to start; erikhfj then fixed the deploy workflow. | +| 2026-10-01 | erikhfj | opencode | CI deploy fix for #27 after rachelks reported it: `grep -q` SIGPIPE silently skipped a live service, `sudo` had no TTY, and `sleep 2` raced Node binding the port. All three verified against the live unit | +| 2026-10-01 | erikhfj | opencode | Simplified this log to a table at the group's request | +| 2026-10-01 | robertky | Codex (ChatGPT) | Assisted with formulating good reviews of the architecture and UI-specification PRs. The group decided to include decade filtering; Rachel implemented the corresponding schema and documentation update in #38. | + +## Notes + +- The prototype was never merged. `archive/scaffold-prototype` is a reference to + check against or to consult when stuck, not a source to copy from. That was + Rachel's correction and it is the rule the rest of this table follows. +- Anything in a PR that the author cannot explain line by line should not be in + the PR. That is the test, not the tool that produced it. diff --git a/docs/WORKFLOW.md b/docs/WORKFLOW.md new file mode 100644 index 0000000..1a4a7d4 --- /dev/null +++ b/docs/WORKFLOW.md @@ -0,0 +1,85 @@ +# Workflow + +How we work in this repository. Agreed by the group, 24 September 2026. + +## Branching + +``` +feat/-short-name new functionality +fix/-short-name bug fixes +docs/-short-name documentation +chore/-short-name tooling, dependencies, CI +``` + +Branch from `main`. Keep the branch name tied to the issue so the history +reads as a list of the work we planned. + +## Commits + +Conventional commits, referencing the issue: + +``` +feat: #9 mock-data search list with debounced input +fix: #13 facet counts ignored the active genre filter +chore: #1 pnpm workspace, ESLint, Prettier, TypeScript +``` + +One logical change per commit. If a change needs three paragraphs to explain, +it should probably have been two commits. + +## Pull requests + +- **Small.** Reviewable in about 30 minutes. If it touches more than a dozen + files, it should have been split. +- **One owner, one reviewer who is not the author.** Rotating who reviews + which area is the point - we learn from each other's code. +- **The description says what was done and what was tested.** That is what the + reviewer reads. Include the commands you ran and their output if the change + is behavioural. +- **"LGTM" on its own is a weak review.** A question or a push-back is usually + worth more than an approval, even when the answer turns out to be "you're + right, no change needed". This is guidance, not a gate: if a change really is + trivial, approving it is fine. The course asks us to learn from each other's + code, and that is what this is for. + +`main` is protected: no direct pushes. Every change goes through a PR and an +approval from `@IT2810-H26/it2810-h26-t19`. Staff approvals do not count. + +## Before opening a PR + +Implement from the issue's requirements - not by copying from +`archive/scaffold-prototype`. That branch is a reference to check against or +to consult when stuck, not a source to paste from. + +Then run: + +```bash +pnpm format:check && pnpm lint && pnpm typecheck && pnpm test +``` + +All four must pass. CI runs the same thing and will reject the PR otherwise. + +## Milestones + +Work is planned in four milestones that line up with the four +underveisinnleveringer. Issues are assigned one milestone at a time - at the +start of each milestone, not all at once up front - so we can rebalance based +on what we learned from the previous one. + +| Milestone | Due | Delivers | +| --------- | ------ | ------------------------------------------------------------------ | +| M1 | 2 Oct | Spec and mockup: schema, ADRs, UI sketch, client with mock data | +| M2 | 16 Oct | Database and GraphQL backend running on the VM, client interaction | +| M3 | 30 Oct | Beta: search, paging, sorting, filtering, accessibility, bærekraft | +| M4 | 13 Nov | Finished prototype and the full test suite | + +## Using AI tools + +AI is allowed and we use it. What the course requires is that we document how, +and that the process shows our own control and planning through issues, pull +requests, code review and systematic collaboration. + +That is what [`docs/AI-USAGE.md`](./AI-USAGE.md) is for: a table of date, who, +tool and what it was used for. Everyone adds their own rows. The rows with no +tool in them are the ones where a person overruled the tool, which is the +evidence of our own control that the course actually asks for.