Skip to content

Commit 9ab39c3

Browse files
pmoharana-cmdpmoharana-cmd
committed
Add contributing docs
1 parent 985c649 commit 9ab39c3

3 files changed

Lines changed: 181 additions & 33 deletions

File tree

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
## Linear
2+
3+
**Issue:**
4+
5+
<!-- e.g. CSSG-12 -->
6+
7+
## What changes
8+
9+
<!-- List the main changes: files added/updated, features, or fixes. -->
10+
11+
## Why it's being done
12+
13+
<!-- Context: which ticket/requirement this addresses and why. -->
14+
15+
## Summary
16+
17+
<!-- One or two sentences describing the PR. -->
18+
19+
## How to verify
20+
21+
<!-- Steps for reviewers to check your changes (optional). -->
22+
23+
- [ ] Lint, format, and tests pass locally (`bun run lint:all`, `bun run format:check:all`, `bun run test:all`)
24+
25+
## Notes
26+
27+
<!-- Optional: follow-ups, caveats, breaking changes, or anything else reviewers should know. -->

‎CONTRIBUTING.md‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
# Contributing to cssg-admin
2+
3+
This runbook describes how to contribute to the repository when working from Linear tickets. Following these steps keeps branches tidy, ensures quality checks pass, and links your work to the right issue.
4+
5+
---
6+
7+
## Prerequisites
8+
9+
- **Bun** installed ([bun.sh](https://bun.sh))
10+
- Access to the repository and (for PRs) the default branch
11+
- A Linear ticket you’re implementing (e.g. `CSSG-12`)
12+
13+
---
14+
15+
## Step 1: Start from an up-to-date `main`
16+
17+
```bash
18+
git checkout main
19+
git pull origin main
20+
```
21+
22+
Always branch from the latest `main` so your changes don’t conflict with others’ work.
23+
24+
---
25+
26+
## Step 2: Create a descriptive branch
27+
28+
Use a **three-word, hyphen-separated** branch name that summarizes the work (no issue code here; that goes in the PR title).
29+
30+
**Examples:**
31+
32+
| Linear ticket | Branch name examples |
33+
| ----------------------------------- | --------------------------------------------------------- |
34+
| CSSG-12 (public pages + global nav) | `public-pages-global-nav` or `global-navbar-public-pages` |
35+
| CSSG-13 (login, signup, onboarding) | `login-signup-onboarding` or `auth-onboarding-flow` |
36+
37+
```bash
38+
git switch -c your-three-word-branch-name
39+
```
40+
41+
---
42+
43+
## Step 3: Do your changes
44+
45+
- Implement the acceptance criteria from the Linear ticket.
46+
- Prefer small, focused commits (e.g. one logical change per commit).
47+
- If the ticket references Figma or a design doc, keep that open for reference.
48+
49+
---
50+
51+
## Step 4: Lint, format, and test
52+
53+
From the **repository root**, run:
54+
55+
```bash
56+
# Lint all workspaces (frontend, backend, shared)
57+
bun run lint:all
58+
59+
# Format all workspaces (writes formatted files)
60+
bun run format:all
61+
62+
# Verify formatting (CI-style check; must pass for clean CI)
63+
bun run format:check:all
64+
65+
# Run all tests
66+
bun run test:all
67+
```
68+
69+
Fix any failures before pushing. Optional: run only the parts you changed:
70+
71+
- `bun run lint:frontend` / `lint:backend` / `lint:shared`
72+
- `bun run format:frontend` / `format:backend` / `format:shared`
73+
- `bun run test:backend` / `test:shared`
74+
75+
---
76+
77+
## Step 5: Push your branch
78+
79+
```bash
80+
git push -u origin your-three-word-branch-name
81+
```
82+
83+
Use the same branch name you created in Step 2.
84+
85+
---
86+
87+
## Step 6: Open a PR linked to Linear
88+
89+
Create a Pull Request with a title in this form so Linear can link it to the issue:
90+
91+
```
92+
[ISSUE-CODE]: Short description of the change
93+
```
94+
95+
**Examples:**
96+
97+
- `[CSSG-12]: Add global navbar and public pages (Home, About, Contact, Projects)`
98+
- `[CSSG-13]: Add login, signup, and onboarding flow with Figma-aligned UI`
99+
100+
Use the **exact** issue identifier (e.g. `CSSG-12`, `CSSG-13`). Linear will then show the PR on the issue and vice versa.
101+
102+
When you open a PR, GitHub will pre-fill the body from the [PR template](.github/PULL_REQUEST_TEMPLATE.md). Fill in the **Issue** (Linear ticket code), a short **Summary**, and any **How to verify** steps for reviewers. You can also add "Closes ISSUE-CODE" or note follow-ups in the description.
103+
104+
---
105+
106+
## Quick reference
107+
108+
| Step | Action |
109+
| ---- | ------------------------------------------------------------------------------------------- |
110+
| 1 | `git checkout main && git pull origin main` |
111+
| 2 | `git checkout -b three-word-branch-name` |
112+
| 3 | Implement the ticket |
113+
| 4 | `bun run lint:all` → `bun run format:all` → `bun run format:check:all` → `bun run test:all` |
114+
| 5 | `git push -u origin three-word-branch-name` |
115+
| 6 | Open PR with title `[ISSUE-CODE]: description` |
116+
117+
---
118+
119+
For more on the monorepo (workspaces, shared package, tooling), see the main [README.md](./README.md).

‎README.md‎

Lines changed: 35 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@
22

33
This repository is a **Bun workspace** monorepo containing shared packages and deployable applications.
44

5+
**Contributing:** See [CONTRIBUTING.md](./CONTRIBUTING.md) for the contribution runbook (branch from Linear tickets, lint/format/test, and PR naming to link to Linear).
6+
57
## Architecture
68

79
```
@@ -19,11 +21,11 @@ workspace/
1921

2022
### Workspaces
2123

22-
| Path | Package name | Purpose |
23-
|-------------------|----------------|---------|
24+
| Path | Package name | Purpose |
25+
| ----------------- | -------------- | --------------------------------------------------------- |
2426
| `apps/frontend` | `frontend` | Next.js app (React, Tailwind). Depends on `@cssg/shared`. |
25-
| `apps/backend` | `backend` | Hono HTTP API run with Bun. Depends on `@cssg/shared`. |
26-
| `packages/shared` | `@cssg/shared` | Shared TypeScript utilities/types. No app-specific deps. |
27+
| `apps/backend` | `backend` | Hono HTTP API run with Bun. Depends on `@cssg/shared`. |
28+
| `packages/shared` | `@cssg/shared` | Shared TypeScript utilities/types. No app-specific deps. |
2729

2830
- **Root** `package.json` defines `"workspaces": ["packages/*", "apps/*"]`. Dependencies are hoisted where possible.
2931
- **Shared code**: Add types, utils, or constants in `packages/shared` and depend on it with `"@cssg/shared": "workspace:*"` in an app’s `package.json`, then run `bun install` from the repo root.
@@ -39,11 +41,11 @@ Run these from the **repository root** unless noted.
3941

4042
### Development
4143

42-
| Command | Description |
43-
|-------------------|-------------|
44-
| `bun run dev:all` | Start all workspaces that have a `dev` script (frontend + backend). |
45-
| `bun run dev:frontend` | Start only the Next.js app (`apps/frontend`). |
46-
| `bun run dev:backend` | Start only the Hono backend (`apps/backend`). |
44+
| Command | Description |
45+
| ---------------------- | ------------------------------------------------------------------- |
46+
| `bun run dev:all` | Start all workspaces that have a `dev` script (frontend + backend). |
47+
| `bun run dev:frontend` | Start only the Next.js app (`apps/frontend`). |
48+
| `bun run dev:backend` | Start only the Hono backend (`apps/backend`). |
4749

4850
From a single app:
4951

@@ -52,30 +54,30 @@ From a single app:
5254

5355
### Linting
5456

55-
| Command | Description |
56-
|----------------------|-------------|
57-
| `bun run lint:all` | Run `lint` in every workspace that defines it. |
58-
| `bun run lint:frontend` | Lint frontend (Next.js ESLint config). |
59-
| `bun run lint:backend` | Lint backend (root ESLint config). |
60-
| `bun run lint:shared` | Lint `@cssg/shared` (root ESLint config). |
57+
| Command | Description |
58+
| ----------------------- | ---------------------------------------------- |
59+
| `bun run lint:all` | Run `lint` in every workspace that defines it. |
60+
| `bun run lint:frontend` | Lint frontend (Next.js ESLint config). |
61+
| `bun run lint:backend` | Lint backend (root ESLint config). |
62+
| `bun run lint:shared` | Lint `@cssg/shared` (root ESLint config). |
6163

6264
### Formatting (Prettier)
6365

64-
| Command | Description |
65-
|-----------------------|-------------|
66-
| `bun run format:all` | Run `format` in every workspace (writes formatted files). |
67-
| `bun run format:check`| Check formatting for the whole repo (CI-friendly; no write). |
68-
| `bun run format:frontend` | Format only `apps/frontend`. |
69-
| `bun run format:backend` | Format only `apps/backend`. |
70-
| `bun run format:shared` | Format only `packages/shared`. |
66+
| Command | Description |
67+
| ------------------------- | ------------------------------------------------------------ |
68+
| `bun run format:all` | Run `format` in every workspace (writes formatted files). |
69+
| `bun run format:check` | Check formatting for the whole repo (CI-friendly; no write). |
70+
| `bun run format:frontend` | Format only `apps/frontend`. |
71+
| `bun run format:backend` | Format only `apps/backend`. |
72+
| `bun run format:shared` | Format only `packages/shared`. |
7173

7274
### Tests
7375

74-
| Command | Description |
75-
|---------------------|-------------|
76-
| `bun run test:all` | Run `test` in every workspace that defines it. |
77-
| `bun run test:backend` | Run backend tests. |
78-
| `bun run test:shared` | Run shared package tests. |
76+
| Command | Description |
77+
| ---------------------- | ---------------------------------------------- |
78+
| `bun run test:all` | Run `test` in every workspace that defines it. |
79+
| `bun run test:backend` | Run backend tests. |
80+
| `bun run test:shared` | Run shared package tests. |
7981

8082
From a single app/package:
8183

@@ -106,9 +108,9 @@ Do **not** use `bun add @cssg/shared` from the app directory; that will try to i
106108

107109
## Tooling summary
108110

109-
| Tool | Scope | Config |
110-
|------------|--------|--------|
111-
| **Bun** | Install, run scripts, run backend | Root + per-package `package.json` |
112-
| **TypeScript** | All packages | `tsconfig.base.json` + per-package `tsconfig.json` |
113-
| **ESLint** | Backend + shared (root); frontend (own) | Root `eslint.config.mjs`; `apps/frontend/eslint.config.mjs` |
114-
| **Prettier** | Whole repo | Root `.prettierrc` (Tailwind plugin), `.prettierignore` |
111+
| Tool | Scope | Config |
112+
| -------------- | --------------------------------------- | ----------------------------------------------------------- |
113+
| **Bun** | Install, run scripts, run backend | Root + per-package `package.json` |
114+
| **TypeScript** | All packages | `tsconfig.base.json` + per-package `tsconfig.json` |
115+
| **ESLint** | Backend + shared (root); frontend (own) | Root `eslint.config.mjs`; `apps/frontend/eslint.config.mjs` |
116+
| **Prettier** | Whole repo | Root `.prettierrc` (Tailwind plugin), `.prettierignore` |

0 commit comments

Comments
 (0)