Contributing to Xbin

Thanks for taking the time to contribute. Xbin is a small, Cloudflare-native paste service, and thoughtful bug reports, documentation improvements, tests, and focused pull requests all make a real difference.

This guide exists to keep contribution flow predictable for both contributors and maintainers, in line with the documentation-first recommendations from Open Source Guides.

Before you start

Read the README to understand the project scope and local setup.
Search existing issues and pull requests before opening a new one.
For large features or design changes, open an issue before writing code so we can confirm the change fits the project.
For security issues, do not open a public issue. Follow SECURITY.md.
By participating, you agree to follow the Code of Conduct.

Good contributions

Contributions are especially helpful when they improve:

correctness and test coverage
Cloudflare deployment and operations
PrivateBin compatibility
security hardening
performance and reliability
accessibility and UX polish
documentation and onboarding

Contributions that significantly expand scope may be declined if they pull Xbin away from its core purpose: secure, encrypted paste sharing with simple operations.

Development setup

Install dependencies:
```
bun install
```
Create local secrets:
```
Copy-Item .dev.vars.example .dev.vars
```
Start local development:
```
bun run dev
```

Run the local quality checks:

bun run format:check
bun run check
bun run test:coverage

If you changed bindings or Worker config, refresh generated types:
```
bun run cf-typegen
```

Coding expectations

Follow the existing TypeScript style: tabs, single quotes, semicolons, and clear helper names.
Keep route handling, validation, configuration, and persistence logic separated.
Prefer small, focused changes over broad refactors.
Add or update tests for behavioral changes. CI expects strong coverage, and patch coverage matters.
Update documentation when behavior, commands, configuration, or contributor workflow changes.
Never commit secrets, tokens, credentials, or private Cloudflare account data.

Pull request checklist

Before opening a PR, please make sure that:

the change is scoped to one coherent improvement
tests were added or updated where appropriate
bun run format:check passes
bun run check passes
bun run test:coverage passes
generated Worker types were refreshed if Wrangler bindings changed
relevant docs were updated

Conventional Commit titles are appreciated and match this repository’s existing history, for example:

fix(repository): avoid orphaned blob cleanup retries
docs: clarify local Cloudflare setup
test(http): cover legacy share-link handling

Issues and support

Please use the repository templates when opening issues:

bug report for defects or regressions
feature request for scope-aligned enhancements
question for setup or usage help

When reporting a bug, include:

what you expected to happen
what actually happened
steps to reproduce
environment details
sanitized logs, screenshots, or request samples when helpful

Review and response expectations

Xbin is maintained on a best-effort schedule. Response times can vary, but a polite follow-up on an issue or pull request after 7 days is welcome.

To keep collaboration transparent and searchable, please prefer public GitHub issues and pull requests over private messages for normal support and feature discussion.

Maintainer discretion

Maintainers may close contributions that do not fit the project’s scope, quality bar, or operational model. When that happens, we will try to explain why and point to relevant documentation so the next contribution has a clearer path.

3.9 KiB Raw Permalink Blame History Unescape Escape