Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
132 lines (100 loc) · 4.38 KB

CONTRIBUTING.md

File metadata and controls

132 lines (100 loc) · 4.38 KB

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:

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 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:

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:

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 when support is added

Commit messages

This repository uses Conventional Commits. Preferred format:

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. 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.