Skip to content

docs: #4 workflow guide and AI decision log #33

Merged
merged 8 commits into from
Oct 2, 2026
+185 −0
Merged

docs: #4 workflow guide and AI decision log #33

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
d7f9708
docs: #4 workflow guide and AI decision log
erikhfj Sep 25, 2026
168d2df
docs: #4 replace em-dashes with hyphens
erikhfj Sep 25, 2026
57df1b9
docs: #4 soften the review rule to guidance
erikhfj Oct 1, 2026
582c450
docs: #4 simplify the AI usage log to a table
erikhfj Oct 1, 2026
a0392ea
docs: #4 add Robert's AI usage
robertky Oct 2, 2026
d8e8912
docs: #4 add Rachel's AI usage and sort entries by date
rachelks Oct 2, 2026
cbfff75
docs: Added AI-Usage documentation
evenkkl Oct 2, 2026
c4bc766
docs: #4 sort and format AI usage log
rachelks Oct 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
55 changes: 55 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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).
45 changes: 45 additions & 0 deletions docs/AI-USAGE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
85 changes: 85 additions & 0 deletions docs/WORKFLOW.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,85 @@
# Workflow

How we work in this repository. Agreed by the group, 24 September 2026.

## Branching

```
feat/<issue>-short-name new functionality
fix/<issue>-short-name bug fixes
docs/<issue>-short-name documentation
chore/<issue>-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.