Thank you for your interest in contributing to scryfall-api — A JavaScript library for scryfall.com
Before you dive in, please read this guide fully. We have a structured workflow to keep the project organized and maintainable.
- Issue-First Workflow
- Label System
- Development Setup
- Testing
- Commit Convention
- Pull Request Rules
- Code of Conduct
No PR without an issue. No exceptions.
This project follows a strict issue-first workflow:
- Open an issue using the appropriate template (Bug Report or Feature Request)
- Wait for approval — a maintainer will add the
status:approvedlabel when the issue is ready to be worked on - Comment on the issue to let others know you're working on it
- Open a PR referencing the approved issue
PRs that are not linked to an approved issue will be automatically rejected by CI.
| Label | Description |
|---|---|
type:bug |
Bug fix |
type:feature |
New feature or enhancement |
type:docs |
Documentation only |
type:refactor |
Code refactoring, no functional changes |
type:chore |
Build, CI, tooling changes |
| Label | Description |
|---|---|
status:needs-review |
Newly opened, awaiting maintainer review |
status:approved |
Approved for implementation — work can begin |
status:in-progress |
Being worked on |
status:blocked |
Blocked by another issue or external dependency |
status:wont-fix |
Out of scope or won't be addressed |
| Label | Description |
|---|---|
priority:critical |
Blocking issues, security vulnerabilities |
priority:high |
Important, affects many users |
priority:medium |
Normal priority |
priority:low |
Nice to have |
- Node/Bun
- Git
git clone https://github.com/MarioMH8/proxystudio.app.git
cd proxystudio.app
bun run build
bun run devRun the full unit test suite:
bun testRun tests for a specific package:
bun test ./test/specific-file.test.tsThis project uses Conventional Commits.
Commit messages must match this pattern:
^(build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test)(\([a-z0-9\._-]+\))?!?: .+
<type>(<optional-scope>)!: <description>
[optional body]
[optional footer]
| Type | Purpose |
|---|---|
feat |
New feature |
fix |
Bug fix |
docs |
Documentation only |
refactor |
Code change (no behavior change) |
chore |
Maintenance, dependencies, tooling |
style |
Formatting, linting (no logic change) |
perf |
Performance improvement |
test |
Adding or updating tests |
build |
Build system or external deps |
ci |
CI configuration |
revert |
Reverts a previous commit |
feat(tui): add progress bar to installation steps
fix(agent): correct Claude Code detection on macOS
docs: update contributing guide
chore(deps): bump bubbletea to v0.26
refactor(pipeline): extract step executor
style: fix linter warnings in catalog package
perf(system): cache OS detection result
test(installer): add coverage for catalog step execution
build: update goreleaser config for arm64
ci: split unit and e2e test jobs
revert: undo model picker redesign
Add ! after the type/scope and include a BREAKING CHANGE: footer:
feat(cli)!: rename --config flag to --config-file
BREAKING CHANGE: the --config flag has been renamed to --config-file.
Update your scripts and aliases accordingly.
Breaking changes map to the type:breaking-change label.
Branch names must match this pattern:
^(feat|fix|chore|docs|style|refactor|perf|test|build|ci|revert)\/[a-z0-9._-]+$
Rules:
- All lowercase
- Use hyphens, dots, or underscores as separators (no spaces, no uppercase)
- Description must be short and descriptive
Examples: feat/user-login, fix/crash-on-startup, docs/api-reference, ci/add-e2e-job
Structure commits by deliverable unit, not by file type. A good commit includes the code, tests, and docs needed to understand and verify one behavior or workflow.
- Prefer
feat(auth): validate tokens at loginover separatemodels,services, andtestscommits. - Keep rollback reasonable: reverting one commit should not remove unrelated work.
- When a PR grows near 400 changed lines, promote work-unit commits into chained or stacked PRs.
Review feedback should be warm, direct, and useful quickly. Start with the actionable point, explain why when needed, and avoid recapping the PR before giving feedback.
- There is a linked approved issue (
Closes #<N>) - Commits are organized by deliverable work unit
- All unit tests pass (
bun test) - Commits follow Conventional Commits format
- Code is self-reviewed
Use the same Conventional Commits format as commit messages:
feat(tui): add keyboard shortcut help overlay
fix(agent): handle missing HOME env var gracefully
All PRs go through automated checks:
| Check | What It Verifies |
|---|---|
| Check Issue Reference | PR body contains Closes/Fixes/Resolves #N |
| Check Issue Has status:approved | The linked issue has been approved by a maintainer |
| Check PR Has type: Label* | Exactly one type:* label is applied |
| Unit Tests | bun test passes |
| ESLint | bun run lint:fix passes |
| Typecheck | bun run typecheck passes |
All checks must pass before a PR can be merged.
In the PR body, include one of:
Closes #42
Fixes #42
Resolves #42
Be respectful. We're building something together.
- Critique code, not people
- Be constructive in reviews
- Welcome newcomers
Violations may result in removal from the project.
Use GitHub Discussions — not issues — for questions, ideas, and general conversation.