133 lines
4.4 KiB
Markdown
133 lines
4.4 KiB
Markdown
# Contributing to Xget
|
|
|
|
Thank you for helping improve Xget. Contributions of all sizes are welcome,
|
|
including bug reports, documentation improvements, test coverage, performance
|
|
investigations, new platform support, and code changes.
|
|
|
|
Before you contribute, please read these repository documents:
|
|
|
|
- [README](README.md) for project scope, supported platforms, and deployment
|
|
options
|
|
- [Code of Conduct](CODE_OF_CONDUCT.md) for community expectations
|
|
- [Security Policy](SECURITY.md) for responsible vulnerability reporting
|
|
- [Governance](GOVERNANCE.md) for maintainer roles and decision-making
|
|
|
|
## Ways to contribute
|
|
|
|
- Report bugs with a minimal reproduction and clear expected behavior
|
|
- Propose features that improve correctness, usability, observability, or
|
|
maintainability
|
|
- Improve documentation, examples, or deployment guidance
|
|
- Add or expand automated tests
|
|
- Validate behavior against real clients, registries, or upstream platforms
|
|
|
|
## Before opening an issue
|
|
|
|
- Search existing issues and pull requests first to avoid duplicates
|
|
- Keep one report focused on one problem or one proposal
|
|
- Include enough detail for someone else to reproduce the issue
|
|
- Do not use public issues for security vulnerabilities; follow
|
|
[`SECURITY.md`](SECURITY.md) instead
|
|
|
|
Useful details to include:
|
|
|
|
- The request URL or request shape that failed, with secrets removed
|
|
- The upstream platform involved, such as GitHub, npm, Docker Hub, or OpenAI
|
|
- Expected behavior and actual behavior
|
|
- Steps to reproduce the problem
|
|
- Logs, screenshots, or response headers when relevant
|
|
- Your runtime or deployment environment, if it affects the issue
|
|
|
|
## Development setup
|
|
|
|
Xget uses Node.js and Wrangler for local development.
|
|
|
|
1. Install Node.js 24 and npm.
|
|
2. Install dependencies with `npm ci`.
|
|
3. Start the local worker with `npm run dev`.
|
|
4. Run tests and checks before opening a pull request.
|
|
|
|
Common commands:
|
|
|
|
```bash
|
|
npm run dev
|
|
npm run lint
|
|
npm run format:check
|
|
npm run test:run
|
|
npm run test:coverage
|
|
npm run type-check
|
|
```
|
|
|
|
## Repository layout
|
|
|
|
- `src/` contains the Worker entry point, request pipeline, protocol handlers,
|
|
routing logic, upstream fetch helpers, and shared utilities
|
|
- `test/` contains unit, feature, platform, and integration tests
|
|
- `adapters/` contains deployment adapters for non-Workers targets
|
|
- `docs/` contains longer-form operational and deployment documentation
|
|
|
|
## Pull request workflow
|
|
|
|
1. Fork the repository and create a branch from `main`.
|
|
2. Keep the change focused. Avoid mixing unrelated fixes.
|
|
3. Add or update tests when behavior changes.
|
|
4. Update documentation when user-facing behavior, configuration, or supported
|
|
platforms change.
|
|
5. Run the local checks listed below before requesting review.
|
|
6. Open a pull request using the repository template and explain the user impact
|
|
clearly.
|
|
|
|
Required local checks:
|
|
|
|
```bash
|
|
npm run lint
|
|
npm run format:check
|
|
npm run test:run
|
|
npm run type-check
|
|
```
|
|
|
|
If your change affects routing, headers, cache behavior, retries, security
|
|
controls, or protocol compatibility, include test coverage for that behavior.
|
|
|
|
## Coding expectations
|
|
|
|
- Follow the existing project structure and naming conventions
|
|
- Prefer small, reviewable changes over large mixed refactors
|
|
- Preserve protocol compatibility for Git, Docker, AI, and package manager
|
|
traffic
|
|
- Avoid logging secrets, tokens, or private request data
|
|
- Document new platform prefixes and examples in [`README.md`](README.md) when
|
|
support is added
|
|
|
|
## Commit messages
|
|
|
|
This repository uses
|
|
[Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/).
|
|
Preferred format:
|
|
|
|
```text
|
|
type(scope): description
|
|
```
|
|
|
|
Examples:
|
|
|
|
- `feat(docker): normalize blob redirect handling`
|
|
- `fix(routing): preserve crates search queries`
|
|
- `docs(readme): clarify npm registry setup`
|
|
|
|
## Review and release expectations
|
|
|
|
- Maintainers review contributions on a best-effort basis
|
|
- Large design changes should start with an issue before implementation
|
|
- Merged changes may be edited, squashed, or followed up by maintainers to keep
|
|
the project consistent
|
|
- Acceptance of a contribution does not create an obligation for long-term
|
|
support, backports, or maintenance
|
|
|
|
## Community standards
|
|
|
|
By participating in this project, you agree to follow
|
|
[`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md). Please be respectful, assume good
|
|
intent, and help keep the project welcoming for users and contributors from a
|
|
wide range of backgrounds and experience levels.
|