struxadotcloud/struxa

public

docs: update contributing guide for stable release and readme banner url4c7d3843 months ago162 lines · 6.2 KB

1	# Contributing to Struxa
2
3	Thank you for your interest in contributing. Struxa is an open-source project and every bit of help — code, bug reports, design critique, or documentation — moves it forward.
4
5	---
6
7	## Ways to Contribute
8
9	- Bug reports — open an Issue describing what happened, what you expected, and your environment
10	- Feature requests — open an Issue with a clear description of the problem you are solving, not just the solution
11	- Code — pick up an open Issue, discuss your approach in the Issue thread, then open a PR
12	- Design feedback — UI/UX critique on open Issues or PRs is welcome; refer to
13	- Documentation — improve README, CONTRIBUTING, or inline code comments
14
15	If you are unsure where to start, look for Issues labeled `good first issue`.
16
17	---
18
19	## Development Setup
20
21	### Prerequisites
22
23	- [Bun](https://bun.sh
24	- MySQL (local install or Docker)
25	- Node.js is not required — Bun handles everything
26
27	### Steps
28
29	```bash
30	# 1. Fork the repo on GitHub, then clone your fork
31	git clone https://github.com/<your-username
32	cd struxa
33
34	# 2. Install dependencies (Bun workspaces installs all packages)
35	bun install
36
37	# 3. Set up environment variables
38	cp apps/web/.env.example apps/web/.env
39	# Fill in your DATABASE_URL, BETTER_AUTH_SECRET, and any other required vars
40
41	# 4. Start the database
42	bun run db:start #
43
44	# 5. Push the schema to your database
45	bun run db:push
46
47	# 6. Set up git hooks
48	bun run prepare
49
50	# 7. Start the dev server
51	bun run dev #
52	```
53
54	---
55
56	## Monorepo Structure
57
58	\| Path \| Package \| What goes here \|
59	\| ------------------ \| ---------------- \|
60	\| `apps/web/` \| — \| Next.js panel app. Pages, routes, app-specific components
61	\| `apps/fumadocs/` \| — \| Documentation site
62	\| `packages/ui/` \| `@struxa/ui
63	\| `packages/api/` \| `@struxa/api
64	\| `packages/auth/` \| `@struxa/auth
65	\| `packages/db/` \| `@struxa/db
66	\| `packages/env/` \| `@struxa/env
67	\| `packages/config/` \| `@struxa/config
68
69	Rule of thumb: if logic is used in more than one app, it belongs in a package. If a UI component is used across multiple pages, it belongs in `
70
71	---
72
73	## Code Style
74
75	- TypeScript strict — no
76	- Formatting — Oxfmt handles it; run
77	- Linting — Oxlint; run
78	- Environment variables — all env vars must go through
79	- Authentication — use Better-Auth via
80	- UI — compose from
81	- API — define procedures in
82
83	---
84
85	## Commit Convention
86
87	Struxa uses [Conventional Commits](https://www.conventionalcommits.org/
88
89	```
90	<type>(<scope>): <short description>
91
92	[optional body]
93	```
94
95	\| Type \| When to use \|
96	\| ---------- \| ----------------------------------------------- \|
97	\| `feat` \| New feature or capability \|
98	\| `fix` \| Bug fix \|
99	\| `refactor` \| Code change that is neither a fix nor a feature \|
100	\| `chore` \| Build, tooling, or dependency changes \|
101	\| `docs` \| Documentation only \|
102	\| `style` \| Formatting, no logic change \|
103	\| `test` \| Adding or updating tests \|
104
105	Examples:
106
107	```
108	feat(api): add server start/stop procedures
109	fix(auth): handle expired session redirect
110	docs: update getting started steps in README
111	chore(db): upgrade drizzle-orm to 0.43.0
112	```
113
114	---
115
116	## Pull Request Process
117
118	1. Branch off
119	2. Keep PRs small and focused. One concern per PR. Split large changes into a sequence.
120	3. Link the Issue your PR addresses in the PR description.
121	4. Run checks locally before opening:
122	```bash
123	bun run check-types
124	bun run check
125	```
126	5. Fill in the PR template — describe what changed, why, and how to verify it manually.
127	6. UI changes — include a screenshot or screen recording. State which parts of
128	7. A maintainer will review. Expect feedback. Do not merge your own PRs.
129
130	---
131
132	## Design Guidelines
133
134	All UI work must follow the design language documented in [DESIGN.md](./DESIGN.md
135
136	- Dark background (`#0a0a0a` / `#141414` surfaces)
137	- Text hierarchy: white primary, `#888888` labels, `#555555` muted
138	- Green (`#22c55e`) for status indicators and charts only
139	- Amber (`#f59e0b`) for primary CTAs only
140	- Rose (`#f43f5e`) for destructive actions only
141	- No border radius (or minimal — `rounded-sm` maximum for inputs)
142	- ALL CAPS labels with wide letter-spacing
143	- Monospace font for any terminal, log, or code surface
144
145	If a design decision is not covered by DESIGN.md, open a discussion before implementing.
146
147	---
148
149	## Code of Conduct
150
151	- Be direct and constructive. Critique the code, not the person.
152	- Assume good intent until proven otherwise.
153	- Maintainers may close Issues or PRs without explanation if they are out of scope.
154	- No harassment, discrimination, or bad-faith behavior. Violations result in a ban.
155
156	This project follows the spirit of the [Contributor Covenant](https://www.contributor-covenant.org/
157
158	---
159
160	## Questions?
161
162	Open an Issue with the `question` label. Do not DM maintainers directly.