[READ-ONLY] Mirror of https://github.com/bombshell-dev/clack. Effortlessly build beautiful command-line apps
bomb.sh/docs/clack/basics/getting-started/
cli
command-line
command-line-app
node
prompt
prompts
docs: add contributing guidelines for Clack (#277)
Co-authored-by: Nate Moore <natemoo-re@users.noreply.github.com>
authored by
Paul Valladares
Nate Moore
and committed by
GitHub
(Apr 7, 2025, 8:29 AM -0600)
0146d83d
3ec796ed
+373
+373
CONTRIBUTING.md
+373
CONTRIBUTING.md
···
1
+
# Contributing to Clack
2
+
3
+
Thank you for your interest in contributing to Clack! This document provides detailed instructions for setting up your development environment, navigating the codebase, making changes, and submitting contributions.
4
+
5
+
> [!Tip]
6
+
> **For new contributors:** Take a look at [https://github.com/firstcontributions/first-contributions](https://github.com/firstcontributions/first-contributions) for helpful information on contributing to open source projects.
7
+
8
+
## Getting Started
9
+
10
+
### Prerequisites
11
+
12
+
- [Node.js](https://nodejs.org/) (version specified in `.nvmrc`, currently v20.18.1)
13
+
- [pnpm](https://pnpm.io/) (version 9.14.2 or higher)
14
+
15
+
If you use [volta](https://volta.sh/) or [nvm](https://github.com/nvm-sh/nvm), the correct Node.js version will be automatically selected based on the project's `.nvmrc` file.
16
+
17
+
### Local Development Setup
18
+
19
+
1. **Fork the repository**:
20
+
- Visit [https://github.com/bombshell-dev/clack](https://github.com/bombshell-dev/clack)
21
+
- Click the "Fork" button in the top right
22
+
- Clone your fork to your local machine
23
+
24
+
```bash
25
+
git clone https://github.com/YOUR_USERNAME/clack.git
26
+
cd clack
27
+
```
28
+
29
+
2. **Set up the upstream remote**:
30
+
```bash
31
+
git remote add upstream https://github.com/bombshell-dev/clack.git
32
+
```
33
+
34
+
3. **Install dependencies**:
35
+
```bash
36
+
pnpm install
37
+
```
38
+
39
+
4. **Build the packages**:
40
+
```bash
41
+
pnpm build
42
+
```
43
+
44
+
5. **Run the development server**:
45
+
```bash
46
+
pnpm dev
47
+
```
48
+
49
+
### Using Clack Packages in Your Own Projects During Development
50
+
51
+
If you want to test changes to Clack packages in your own project, you can use pnpm's linking capabilities:
52
+
53
+
1. **Build the Clack packages locally first**:
54
+
```bash
55
+
# In the clack repository
56
+
cd /path/to/clack
57
+
pnpm build
58
+
```
59
+
60
+
2. **Link the packages to your project using one of these methods**:
61
+
62
+
**Method 1: Using pnpm link**
63
+
```bash
64
+
# In your project
65
+
cd /path/to/your-project
66
+
67
+
# Link @clack/core
68
+
pnpm link --global /path/to/clack/packages/core
69
+
70
+
# Link @clack/prompts
71
+
pnpm link --global /path/to/clack/packages/prompts
72
+
```
73
+
74
+
**Method 2: Using local path in package.json**
75
+
76
+
In your project's package.json, reference the local paths:
77
+
```json
78
+
{
79
+
"dependencies": {
80
+
"@clack/core": "file:/path/to/clack/packages/core",
81
+
"@clack/prompts": "file:/path/to/clack/packages/prompts"
82
+
}
83
+
}
84
+
```
85
+
Then run `pnpm install` in your project.
86
+
87
+
3. **Watch for changes** (optional):
88
+
```bash
89
+
# In the clack repository
90
+
cd /path/to/clack
91
+
pnpm build --watch
92
+
```
93
+
94
+
4. **Refresh after changes**:
95
+
If you're making changes to Clack while testing in your project, you'll need to rebuild Clack and potentially reinstall in your project:
96
+
```bash
97
+
# In the clack repository
98
+
cd /path/to/clack
99
+
pnpm build
100
+
101
+
# In your project (if using Method 2)
102
+
cd /path/to/your-project
103
+
pnpm install
104
+
```
105
+
106
+
With this setup, you can develop and test your changes to Clack within the context of your own project. This is especially useful for implementing new features like filtering.
107
+
108
+
## Repository Structure
109
+
110
+
Clack is organized as a monorepo using pnpm workspaces. Understanding the structure will help you navigate and contribute effectively:
111
+
112
+
```
113
+
clack/
114
+
├── .changeset/ # Changeset files for versioning
115
+
├── .github/ # GitHub workflows and templates
116
+
├── examples/ # Example implementations of Clack
117
+
├── packages/ # Core packages
118
+
│ ├── core/ # Unstyled primitives (@clack/core)
119
+
│ └── prompts/ # Ready-to-use components (@clack/prompts)
120
+
├── biome.json # Biome configuration
121
+
├── package.json # Root package.json
122
+
├── pnpm-workspace.yaml # Workspace configuration
123
+
└── tsconfig.json # TypeScript configuration
124
+
```
125
+
126
+
### Key Packages
127
+
128
+
1. **@clack/core** (`packages/core/`):
129
+
- Contains the unstyled, extensible primitives for building CLI applications
130
+
- The foundation layer that provides the core functionality
131
+
132
+
2. **@clack/prompts** (`packages/prompts/`):
133
+
- Built on top of @clack/core
134
+
- Provides beautiful, ready-to-use CLI prompt components
135
+
- What most users will interact with directly
136
+
137
+
### Examples
138
+
139
+
The `examples/` directory contains sample projects that demonstrate how to use Clack. Examining these examples is a great way to understand how the library works in practice.
140
+
141
+
## Development Workflow
142
+
143
+
### Common Commands
144
+
145
+
- **Build all packages**:
146
+
```bash
147
+
pnpm build
148
+
```
149
+
150
+
- **Start development environment**:
151
+
```bash
152
+
pnpm dev
153
+
```
154
+
155
+
- **Run tests**:
156
+
```bash
157
+
pnpm test
158
+
```
159
+
160
+
- **Lint code**:
161
+
```bash
162
+
pnpm lint
163
+
```
164
+
165
+
- **Format code**:
166
+
```bash
167
+
pnpm format
168
+
```
169
+
170
+
- **Type check**:
171
+
```bash
172
+
pnpm type-check
173
+
```
174
+
175
+
- **Build stubbed packages** (for faster development):
176
+
```bash
177
+
pnpm stub
178
+
```
179
+
180
+
### Making Changes
181
+
182
+
1. **Create a new branch**:
183
+
```bash
184
+
git checkout -b my-feature-branch
185
+
```
186
+
187
+
2. **Implement your changes**:
188
+
- For bug fixes, start by reproducing the issue
189
+
- For new features, consider how it fits into the existing architecture
190
+
- Maintain type safety with TypeScript
191
+
- Add or update tests as necessary
192
+
193
+
3. **Run local verification**:
194
+
```bash
195
+
# Ensure everything builds
196
+
pnpm build
197
+
198
+
# Check formatting and lint issues
199
+
pnpm format
200
+
pnpm lint
201
+
202
+
# Verify type correctness
203
+
pnpm type-check
204
+
205
+
# Run tests
206
+
pnpm test
207
+
```
208
+
209
+
4. **Create a changeset** (for changes that need versioning):
210
+
```bash
211
+
pnpm changeset
212
+
```
213
+
- Follow the prompts to select which packages have changed
214
+
- Choose the appropriate semver increment (patch, minor, major)
215
+
- Write a concise but descriptive message explaining the changes
216
+
217
+
### Testing Your Changes
218
+
219
+
For testing changes to the core functionality:
220
+
221
+
1. **Use the examples**:
222
+
```bash
223
+
# Run an example to test your changes
224
+
pnpm --filter @example/changesets run start
225
+
```
226
+
227
+
2. **Create a test-specific example** (if needed):
228
+
- Add a new directory in the `examples/` folder
229
+
- Implement a minimal reproduction that uses your new feature/fix
230
+
- Run it with `pnpm --filter @example/your-example run start`
231
+
232
+
### Debugging Tips
233
+
234
+
When encountering issues during development:
235
+
236
+
1. **Check for errors in the console** - Clack will often output helpful error messages
237
+
2. **Review the API documentation** - Ensure you're using components and functions as intended
238
+
3. **Look at existing examples** - See how similar features are implemented
239
+
4. **Inspect the packages individually** - Sometimes issues are isolated to either `core` or `prompts`
240
+
241
+
## Pull Request Process
242
+
243
+
1. **Commit your changes**:
244
+
```bash
245
+
git add .
246
+
git commit -m "feat: add new awesome feature"
247
+
```
248
+
249
+
2. **Push to your fork**:
250
+
```bash
251
+
git push origin my-feature-branch
252
+
```
253
+
254
+
3. **Create a pull request**:
255
+
- Go to your fork on GitHub
256
+
- Click "New pull request"
257
+
- Select your branch and add a descriptive title
258
+
- Fill in the PR template with details about your changes
259
+
- Reference any related issues
260
+
261
+
4. **Wait for the automated checks**:
262
+
- GitHub Actions will run tests, type checking, and lint validation
263
+
- Fix any issues that arise
264
+
265
+
5. **Address review feedback**:
266
+
- Make requested changes
267
+
- Push additional commits to your branch
268
+
- The PR will update automatically
269
+
270
+
### PR Previews
271
+
272
+
Clack uses [pkg.pr.new](https://pkg.pr.new) (provided by [bolt.new](https://bolt.new)) to create continuous preview releases of all PRs. This simplifies testing and makes verifying bug fixes easier for our dependents.
273
+
274
+
The workflow that builds a preview version and adds instructions for installation as a comment on your PR should run automatically if you have contributed to Clack before. First-time contributors may need to wait until a maintainer manually approves GitHub Actions running on your PR.
275
+
276
+
## Release Process
277
+
278
+
Clack uses [Changesets](https://github.com/changesets/changesets) to manage versions and releases.
279
+
280
+
1. **For contributors**:
281
+
- Create a changeset file with your PR as described above
282
+
- Maintainers will handle the actual release process
283
+
284
+
2. **For maintainers**:
285
+
- Merging PRs with changesets will queue them for the next release
286
+
- When ready to release:
287
+
```bash
288
+
# Update versions based on changesets
289
+
pnpm ci:version
290
+
291
+
# Publish to npm
292
+
pnpm ci:publish
293
+
```
294
+
295
+
### Backporting to v0 Branch
296
+
297
+
Clack maintains a stable `v0` branch alongside the main development branch. For maintainers who need to backport changes:
298
+
299
+
1. Label PRs that should be backported with the `backport` label
300
+
2. After the PR is merged to `main`, manually cherry-pick the squashed commit into the `v0` branch:
301
+
```bash
302
+
# Ensure you have the latest v0 branch
303
+
git checkout v0
304
+
git pull upstream v0
305
+
306
+
# Cherry-pick the squashed commit from main
307
+
git cherry-pick <commit-hash>
308
+
309
+
# Push the changes
310
+
git push upstream v0
311
+
```
312
+
3. CI is configured to run changesets from the `v0` branch, so release PRs will be opened automatically
313
+
314
+
The GitHub Actions are configured to cut releases from both the `main` and `v0` branches.
315
+
316
+
## Filing Issues
317
+
318
+
When reporting bugs or requesting features:
319
+
320
+
1. **Check existing issues** to avoid duplicates
321
+
2. **Use the issue templates** to provide all necessary information
322
+
3. **Be specific and clear** about what's happening and what you expect
323
+
4. **Provide reproduction steps** - ideally a minimal example that demonstrates the issue
324
+
5. **Include environment details** like OS, Node.js version, etc.
325
+
326
+
### Issue Types
327
+
328
+
When opening an issue, consider which category it falls into:
329
+
330
+
- **Bug Report**: Something isn't working as documented or expected
331
+
- **Feature Request**: A suggestion for new functionality
332
+
- **Documentation Issue**: Improvements or corrections to documentation
333
+
- **Performance Issue**: Problems with speed or resource usage
334
+
335
+
## Style Guide
336
+
337
+
We use [Biome](https://biomejs.dev/) for linting and formatting. Your code should follow these standards:
338
+
339
+
```bash
340
+
# To check formatting
341
+
pnpm format
342
+
343
+
# To lint and fix issues automatically where possible
344
+
pnpm lint
345
+
```
346
+
347
+
The project follows standard TypeScript practices. If you're new to TypeScript:
348
+
- Use precise types whenever possible
349
+
- Avoid `any` unless absolutely necessary
350
+
- Look at existing code for patterns to follow
351
+
352
+
### Commit Message Format
353
+
354
+
We follow conventional commits for commit messages:
355
+
356
+
- `feat:` - A new feature
357
+
- `fix:` - A bug fix
358
+
- `docs:` - Documentation changes
359
+
- `style:` - Changes that don't affect code functionality (formatting, etc)
360
+
- `refactor:` - Code changes that neither fix bugs nor add features
361
+
- `perf:` - Performance improvements
362
+
- `test:` - Adding or correcting tests
363
+
- `chore:` - Changes to the build process, tools, etc
364
+
365
+
## License
366
+
367
+
By contributing, you agree that your contributions will be licensed under the project's MIT License.
368
+
369
+
Thank you for taking the time to contribute to Clack! Feel free to join our community Discord at [bomb.sh/chat](https://bomb.sh/chat). It's a great place to connect with other project contributors—we're chill!
370
+
371
+
## Acknowledgments
372
+
373
+
This contributing guide was inspired by and adapted from the [Astro Contributing Manual](https://github.com/withastro/astro/blob/main/CONTRIBUTING.md). We appreciate their excellent documentation and open source practices.