Documentation
Contributing guide
This document covers everything you need to start contributing to ConfigIQ alongside other engineers.
1. Getting access
Ask the repo owner to add you as a collaborator. Once you accept the email invite you will have push access to create branches and open pull requests.
You will also need:
- Node.js 20 or later — check with
node -v - npm 10 or later — check with
npm -v - Git — check with
git --version - GitHub CLI (optional but useful) — cli.github.com
2. First-time setup
# Clone the repo
git clone https://github.com/redhat-performance/configiq.git
cd configiq
# Install dependencies (also wires up pre-commit hooks automatically)
npm install
# Start the dev server
npm run dev
The app runs at http://localhost:3000.
If port 3000 is in use, Next.js will move to 3001. Check the terminal output for the actual URL.
Useful commands
| Command | What it does |
|---|---|
npm run dev |
Start dev server with hot reload |
npm run build |
Production build — run this before opening a PR |
npm run type-check |
TypeScript check without building |
npm run lint |
ESLint check |
npm test |
Run the test suite (builds the docs first) |
npm run docs:build |
Render Markdown into the app and the help index |
npm run docs:check |
Verify the generated docs match the Markdown sources |
docs:build runs automatically before dev, build, and test, so you rarely
call it by hand. docs:check never writes anything; use it to confirm a change
that touches documentation is complete before you commit.
3. How the codebase is structured
app/ Next.js App Router pages
layout.tsx Root layout — fonts, PatternFly CSS imports
page.tsx Homepage
predict/ Predict performance tool
recommend/ Recommend sizing tool
kv-cache/ KV cache calculator
gpu-explorer/ GPU Explorer
hybrid-savings/ Hybrid Savings
routing/ Routing Economics
cluster-cost/ Cluster cost calculator
docs/ Documentation index and rendered Markdown pages
api/ Same-origin proxy routes for the services
components/
layout/
AppShell.tsx Top nav bar and PatternFly Page wrapper
help/ Help popover: search, ask, and tours
lib/
api/ AISimulators API clients and response adapters
assistant/ Assistant tools and prompt (server-side only)
deep-links/ Shared-view link format and parsing
docs/ Docs manifest and generated output
gpu-math/ Legacy static catalogs and historical fallback code
help/ Search corpus, glossary, tours, and affordances
pricing/ Pricing data and helpers
hooks/ Same-origin catalog and pricing data hooks
utils/
format.ts Number and unit formatting helpers
scripts/
build-docs.mjs Renders docs/ and writes the help index
docs/ Architecture docs, guides, and decision records
public/ Static assets
The most important rule: GPU math belongs in AISimulators. Components call
the lib/api/ clients through the same-origin app/api/ routes and display
results. Do not add new sizing formulas to lib/gpu-math/.
4. Day-to-day workflow
The main branch is protected. Nobody can push to it directly — all changes go through a pull request that requires:
- CI to pass (type-check + lint + build)
- At least one approving review from another engineer
Step-by-step
1. Always start from an up-to-date main
git checkout main
git pull origin main
2. Create a feature branch
Use a short, descriptive name in this format:
git checkout -b feature/gpu-explorer-filters
git checkout -b fix/mobile-nav-overflow
git checkout -b chore/update-model-catalog
Prefixes: feature/ for new functionality, fix/ for bug fixes, chore/ for maintenance.
3. Make your changes and commit
Pre-commit hooks run automatically when you git commit. They check lint and types on staged files and block the commit if anything fails — fix the error and try again.
git add app/predict/page.tsx
git commit -s -m "Add GPU memory breakdown chart to estimate panel"
Write commit messages in the imperative ("Add", "Fix", "Remove") and describe what the change does, not what files changed.
Always commit with -s. Every commit must carry a Signed-off-by: trailer
matching the committer identity, and -s adds it for you. For a commit you
already made, fix it with git commit --amend -s.
4. Push your branch
git push origin feature/gpu-explorer-filters
5. Open a pull request
gh pr create --title "Add GPU memory breakdown chart" --body "Short description of what and why"
Or open one from github.com. Target branch should always be main.
CI runs automatically. You will see checks appear on the PR page.
6. Request a review
Tag the other engineer for review. While you wait, you can start reviewing their open PRs.
7. Address feedback
Push additional commits to the same branch. The CI re-runs and any previous approval is dismissed automatically, so they will need to re-approve after you push changes.
8. Merge
Once CI passes and the review is approved, merge the PR. Delete the branch after merging — GitHub shows a button for this.
9. Pull main and start the next branch
git checkout main
git pull origin main
git checkout -b feature/next-thing
5. Avoiding conflicts
Two engineers working at the same time will sometimes touch the same files. The most likely conflict points in this repo are:
| File | Why it conflicts |
|---|---|
app/globals.css |
All shared CSS lives here |
app/predict/Performance.tsx |
Large file, most active page |
lib/api/ |
API contracts and response adapters |
package.json |
Dependency changes |
Practical rules to avoid painful merges:
- Keep PRs small and short-lived. A PR that takes a week to land will conflict with everything.
- Coordinate verbally before both editing the same section (e.g. "I'm touching the estimate panel today, can you work on the model gallery?").
- Pull
mainbefore starting a new branch, not just at the start of the day. - If your branch is more than a day old and others have merged, rebase before opening a PR:
git fetch origin
git rebase origin/main
If you hit a merge conflict during rebase, Git will pause and show the conflicting file. Open it, resolve the marked sections, then:
git add <conflicting-file>
git rebase --continue
6. Code conventions
Follow these so the codebase stays consistent across contributors.
PatternFly only for UI
Do not install Tailwind, shadcn/ui, Material UI, or any other component library. PatternFly v6 is the only component library. If you need a UI pattern, check patternfly.org first.
Red Hat design system for colors and fonts
Use the established CSS variables — do not introduce arbitrary hex colors:
/* Current theme tokens */
var(--gc-brand-red) /* #ee0000 — brand red, logo only */
var(--gc-link) /* #0066cc — interactive elements */
var(--gc-text) /* #151515 — primary text */
var(--gc-text-2) /* #3c3f42 — body and secondary text */
var(--border) /* #d2d2d2 — borders */
/* Compatibility tokens */
var(--rh-red-50) /* #ffeaea — selected state backgrounds */
var(--rh-gray-95) /* #151515 — primary text */
var(--rh-gray-50) /* #6a6e73 — legacy secondary text */
var(--rh-gray-20) /* #d2d2d2 — borders */
var(--rh-gray-10) /* #f0f0f0 — page background */
/* Font variables */
var(--font-display) /* Red Hat Display — headings */
var(--font-body) /* Red Hat Text — body copy */
var(--font-mono) /* Red Hat Mono — code, labels */
Font weights: use 400 (regular) and 500 (medium) for body text. 700 bold is for Display headings only.
Sentence case everywhere
Red Hat brand standard. No title case.
✓ What model are you serving?
✓ See full breakdown
✗ What Model Are You Serving?
✗ See Full Breakdown
TypeScript strict — no any
Define proper interfaces. The CI type-check step will catch any types.
Server components by default
Add "use client" only when the component uses browser APIs, state (useState), or event handlers. If in doubt, check whether removing it causes an error.
Documentation is rendered at build time
User-facing documentation lives in docs/*.md, and scripts/build-docs.mjs
renders it into the app. Never parse Markdown in the browser or add a
Markdown-rendering package to the client bundle.
To add or change a page:
- Edit the Markdown file, or add the new file under
docs/. - Register it in
docs/manifest.jsonwith a uniqueslug, atitle, a one-sentencedescription, the repo-relativefile, and anorder. - Link it from
docs/overview.md; the manifest test fails if a section is not reachable from the overview. - Run
npm run docs:build.
Links between documents use the file name: [Costs](costs.md). They are
rewritten to /docs/costs. Links that point at an anchor must match a heading
in that document, or the build fails.
The same build produces public/help-index.json, which powers the in-app help
search, so a documentation change is also a change to what search can find.
No unnecessary comments
Only add a comment when the why is non-obvious — a hidden constraint, a tricky invariant, a workaround for a specific bug. Well-named variables and functions are self-documenting.
7. PR checklist
Before marking a PR ready for review:
-
npm run type-checkpasses locally -
npm run lintpasses locally -
npm testpasses locally -
npm run buildpasses locally - Documentation changes are registered in
docs/manifest.jsonandnpm run docs:checkpasses - New GPU math is in AISimulators, not in a component or
lib/gpu-math/ - Shared views are honest: new or changed inputs appear in the page's link
contract and its request census, and a new page is registered in
lib/deep-links/registry.ts - No new third-party UI libraries added to
package.json - All UI text uses sentence case
- No arbitrary hardcoded hex colors — use established
--gc-*,--rh-*, or--font-*variables as appropriate
8. Getting help
- CLAUDE.md and AGENTS.md — context files for coding agents; also useful background for any contributor
- docs/ — architecture decisions and tech stack rationale
- Open a GitHub issue if you find a bug or want to propose a feature before building it