Skip to content

Commit f01e41e

Browse files
kmelvekmelve
authored
Merge pull request #3 from sanity-labs/docs/add-contributing-and-workflow
docs: add CONTRIBUTING.md and document PR workflow
2 parents cd367d4 + 3b5bfed commit f01e41e

File tree

7 files changed

+2570
-3782
lines changed

7 files changed

+2570
-3782
lines changed

‎.github/workflows/ci.yml‎

Lines changed: 9 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -16,24 +16,27 @@ jobs:
1616
runs-on: ubuntu-latest
1717
strategy:
1818
matrix:
19-
node: ['20', '22']
19+
node: ['22', '24']
2020
steps:
2121
- uses: actions/checkout@v4
2222

23+
- name: Setup pnpm
24+
uses: pnpm/action-setup@v4
25+
2326
- name: Setup Node.js
2427
uses: actions/setup-node@v4
2528
with:
2629
node-version: ${{ matrix.node }}
27-
cache: 'npm'
30+
cache: 'pnpm'
2831

2932
- name: Install dependencies
30-
run: npm ci
33+
run: pnpm install --frozen-lockfile
3134

3235
- name: Type check
33-
run: npm run typecheck
36+
run: pnpm typecheck
3437

3538
- name: Build
36-
run: npm run build
39+
run: pnpm build
3740

3841
- name: Test
39-
run: npm run test:run
42+
run: pnpm test:run

‎.github/workflows/release.yml‎

Lines changed: 9 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -22,28 +22,31 @@ jobs:
2222
with:
2323
fetch-depth: 0
2424

25+
- name: Setup pnpm
26+
uses: pnpm/action-setup@v4
27+
2528
- name: Setup Node.js
2629
uses: actions/setup-node@v4
2730
with:
2831
node-version: '22'
29-
cache: 'npm'
32+
cache: 'pnpm'
3033
registry-url: 'https://registry.npmjs.org'
3134

3235
- name: Install dependencies
33-
run: npm ci
36+
run: pnpm install --frozen-lockfile
3437

3538
- name: Build
36-
run: npm run build
39+
run: pnpm build
3740

3841
- name: Test
39-
run: npm run test:run
42+
run: pnpm test:run
4043

4144
- name: Create Release Pull Request or Publish
4245
id: changesets
4346
uses: changesets/action@v1
4447
with:
45-
publish: npx changeset publish
46-
version: npx changeset version
48+
publish: pnpm release
49+
version: pnpm changeset version
4750
title: 'chore: version packages'
4851
commit: 'chore: version packages'
4952
env:

‎CLAUDE.md‎

Lines changed: 22 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -4,20 +4,37 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
44

55
## Project Overview
66

7-
**boxfix** (`@sanity-labs/boxfix`) is a CLI tool and library that fixes misaligned ASCII diagram borders in markdown files. LLMs often generate diagrams where content lines are shorter than boundary lines - this tool detects and pads those lines to proper width.
7+
**boxfix** is a CLI tool and library that fixes misaligned ASCII diagram borders in markdown files. LLMs often generate diagrams where content lines are shorter than boundary lines - this tool detects and pads those lines to proper width.
8+
9+
## Workflow
10+
11+
This project uses a PR-based workflow with branch protection on `main`:
12+
13+
- **No direct pushes to main** - All changes require a pull request
14+
- **CI must pass** - Tests run on Node 22 and 24
15+
- **Approval required** - At least 1 review needed before merge
16+
- **Conventional commits** - Use `feat:`, `fix:`, `docs:`, etc.
17+
18+
When making changes:
19+
1. Create a feature branch from `main`
20+
2. Make changes and ensure CI passes locally
21+
3. Open a PR and wait for review
22+
4. Squash or rebase merge when approved
23+
24+
See [CONTRIBUTING.md](./CONTRIBUTING.md) for detailed guidelines.
825

926
## Commands
1027

1128
```bash
1229
# Build (uses tsup)
13-
npm run build
30+
pnpm build
1431

1532
# Run tests
16-
npm test # Watch mode
17-
npm run test:run # Single run
33+
pnpm test # Watch mode
34+
pnpm test:run # Single run
1835

1936
# Type checking
20-
npm run typecheck
37+
pnpm typecheck
2138

2239
# CLI usage (after build)
2340
./dist/cli.js input.md # Output to stdout

‎CONTRIBUTING.md‎

Lines changed: 205 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,205 @@
1+
# Contributing to boxfix
2+
3+
Thank you for your interest in contributing to boxfix! This document provides guidelines and instructions for contributing.
4+
5+
## Development Setup
6+
7+
### Prerequisites
8+
9+
- Node.js 22 or later (LTS)
10+
- npm
11+
12+
### Getting Started
13+
14+
1. Fork and clone the repository:
15+
```bash
16+
git clone https://github.com/YOUR_USERNAME/boxfix.git
17+
cd boxfix
18+
```
19+
20+
2. Install dependencies:
21+
```bash
22+
pnpm install
23+
```
24+
25+
3. Build the project:
26+
```bash
27+
pnpm build
28+
```
29+
30+
4. Run tests to verify setup:
31+
```bash
32+
ppnpm test:run
33+
```
34+
35+
## Development Workflow
36+
37+
### Branch Protection
38+
39+
The `main` branch is protected with the following rules:
40+
41+
- **Pull requests required** - All changes must go through a PR
42+
- **Approval required** - At least 1 approving review needed
43+
- **Status checks required** - CI must pass on Node 22 and 24
44+
- **No force pushes** - History cannot be rewritten on main
45+
- **Stale reviews dismissed** - New commits invalidate previous approvals
46+
47+
### Creating a Pull Request
48+
49+
1. Create a feature branch from `main`:
50+
```bash
51+
git checkout -b feat/your-feature-name
52+
```
53+
54+
2. Make your changes, ensuring:
55+
- Tests pass: `ppnpm test:run`
56+
- Types check: `pnpm typecheck`
57+
- Build succeeds: `pnpm build`
58+
59+
3. Commit using [conventional commits](#commit-conventions)
60+
61+
4. Push and create a PR against `main`
62+
63+
5. Wait for CI to pass and request a review
64+
65+
### Commit Conventions
66+
67+
We use [Conventional Commits](https://www.conventionalcommits.org/). Format:
68+
69+
```
70+
<type>(<scope>): <description>
71+
72+
[optional body]
73+
74+
[optional footer(s)]
75+
```
76+
77+
**Types:**
78+
- `feat` - New feature
79+
- `fix` - Bug fix
80+
- `docs` - Documentation only
81+
- `style` - Code style (formatting, semicolons, etc.)
82+
- `refactor` - Code change that neither fixes a bug nor adds a feature
83+
- `perf` - Performance improvement
84+
- `test` - Adding or updating tests
85+
- `build` - Build system or external dependencies
86+
- `ci` - CI configuration
87+
- `chore` - Other changes that don't modify src or test files
88+
89+
**Examples:**
90+
```bash
91+
feat(cli): add --verbose flag for detailed output
92+
fix(width): handle zero-width joiners in emoji sequences
93+
docs: update installation instructions
94+
test: add edge cases for nested boxes
95+
```
96+
97+
## Project Structure
98+
99+
```
100+
src/
101+
├── types.ts # Type definitions and constants
102+
├── width.ts # Display width calculation
103+
├── diagram-detector.ts # Diagram vs code heuristics
104+
├── boxfix.ts # Core fixing algorithm
105+
├── markdown.ts # Markdown processing
106+
├── cli.ts # CLI entry point
107+
└── index.ts # Library exports
108+
109+
test/
110+
└── boxfix.test.ts # Test suite
111+
112+
examples/ # Before/after diagram examples
113+
```
114+
115+
## Testing
116+
117+
### Running Tests
118+
119+
```bash
120+
pnpm test # Watch mode
121+
ppnpm test:run # Single run (CI)
122+
```
123+
124+
### Writing Tests
125+
126+
Tests use [Vitest](https://vitest.dev/). The test file covers:
127+
128+
- Width calculation for ASCII, Unicode, CJK, and emoji
129+
- Diagram detection heuristics
130+
- Line type classification (boundary, content, tree)
131+
- Fixing various box styles
132+
- Markdown code block processing
133+
134+
When adding features, include tests that cover:
135+
- Happy path
136+
- Edge cases
137+
- Error conditions (if applicable)
138+
139+
### Test Guidelines
140+
141+
- Test behavior, not implementation
142+
- One assertion per test when possible
143+
- Use descriptive test names
144+
- Follow existing test patterns
145+
146+
## Code Style
147+
148+
- TypeScript strict mode
149+
- ESM modules (no CommonJS)
150+
- Prefer `const` over `let`
151+
- Use descriptive variable names
152+
- Keep functions focused and small
153+
154+
## Making Changes
155+
156+
### Adding Features
157+
158+
1. Check existing issues or create one to discuss the feature
159+
2. Fork and create a feature branch
160+
3. Write tests first (TDD encouraged)
161+
4. Implement the feature
162+
5. Update documentation if needed
163+
6. Submit a PR
164+
165+
### Fixing Bugs
166+
167+
1. Create an issue describing the bug (if not already reported)
168+
2. Fork and create a fix branch
169+
3. Add a test that reproduces the bug
170+
4. Fix the bug
171+
5. Verify the test passes
172+
6. Submit a PR referencing the issue
173+
174+
### Documentation
175+
176+
- Update README.md for user-facing changes
177+
- Update CLAUDE.md for architectural changes
178+
- Add examples to `examples/` for new diagram support
179+
180+
## Release Process
181+
182+
Releases are managed through [Changesets](https://github.com/changesets/changesets):
183+
184+
1. Create a changeset when making user-facing changes:
185+
```bash
186+
pnpm changeset
187+
```
188+
189+
2. Follow the prompts to describe your changes
190+
191+
3. Commit the generated changeset file with your PR
192+
193+
4. When merged to main, the release workflow will:
194+
- Create/update a "Version Packages" PR
195+
- When that PR is merged, publish to npm
196+
197+
## Getting Help
198+
199+
- Open an issue for bugs or feature requests
200+
- Check existing issues before creating new ones
201+
- Be clear and provide context in your reports
202+
203+
## Code of Conduct
204+
205+
Be respectful and constructive. We're all here to build something useful.

0 commit comments

Comments
 (0)