Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
111 lines (95 loc) · 5.43 KB

CONTRIBUTING.md

File metadata and controls

111 lines (95 loc) · 5.43 KB

Contributing to Hyperlite

Thanks for your interest in contributing to Hyperlite! This project is a lightweight HTTP framework built on hyper, tokio, and tower, and we welcome contributions of all kinds. By participating in this project, you agree to follow the Code of Conduct described below.

Ways to Contribute

  • Report bugs and unexpected behaviour
  • Suggest new features or enhancements
  • Improve documentation and examples
  • Write code for new capabilities or fixes
  • Review pull requests and share feedback

Getting Started

  1. Install Rust 1.75 or newer and ensure you are comfortable with async/await and the Tower ecosystem.
  2. Clone the repository: git clone https://github.com/kriyaetive/hyperlite.git
  3. Build the project: cargo build
  4. Run the full test suite: cargo test
  5. Explore the examples: cargo run --example hello_world

Development Workflow

  1. Fork the repository and create a branch: git checkout -b feature/your-feature-name
  2. Make changes in small, logical commits with clear messages.
  3. Add or update tests for your changes.
  4. Update documentation and examples as needed.
  5. Run checks locally:
    • cargo fmt
    • cargo clippy -- -D warnings
    • cargo test
  6. Push your branch and open a pull request when ready.

Code Style Guidelines

  • Follow Rust's standard formatting using cargo fmt.
  • Choose descriptive names for types, functions, and variables.
  • Add rustdoc comments for all public APIs, including usage examples when practical.
  • Keep functions focused and single-purpose; prefer small, composable components.
  • Handle errors explicitly rather than panicking in library code.
  • Use #[must_use] for return values that callers should not ignore.

Testing Requirements

  • Every new feature or regression fix must include tests.
  • Aim for at least 80% coverage on new code paths.
  • Place integration tests in the tests/ directory and reuse test_helpers.rs where possible.
  • Test both success and error paths, including edge cases and boundary conditions.
  • Use descriptive test names such as test_router_handles_multiple_path_params.

Documentation Standards

  • Add rustdoc comments for all public items.
  • Include runnable examples in documentation where it helps clarify behaviour.
  • Update the README for major features or workflow changes.
  • Add examples under examples/ for significant new capabilities.
  • Remember to update CHANGELOG.md as described below.

Pull Request Process

  • Complete every section of the pull request template.
  • Link related issues using phrases like Fixes #123 or Closes #456.
  • Ensure CI checks pass (tests, clippy, formatting, docs, security audits).
  • Request reviews from maintainers when the PR is ready.
  • Address review feedback promptly and squash commits if requested.
  • Use descriptive PR titles such as Add support for HTTP/2 connections.

Commit Message Guidelines

  • Prefer Conventional Commit prefixes: type(scope): description.
  • Supported types include feat, fix, docs, test, refactor, perf, and chore.
  • Examples:
    • feat(router): add support for wildcard routes
    • fix(extract): handle empty query strings correctly
    • docs(readme): update installation instructions
    • test(response): add tests for correlation ID propagation

Changelog Updates

  • Edit CHANGELOG.md and add entries beneath the [Unreleased] section.
  • Follow the Keep a Changelog format with categories: Added, Changed, Deprecated, Removed, Fixed, Security.
  • Include a reference to the pull request number, e.g. - Add HTTP/2 support (#42).

Issue Reporting

  • Use the provided issue templates for bugs, features, or questions.
  • Search existing issues before opening a new one to avoid duplicates.
  • Provide a minimal reproducible example for bugs, along with logs when possible.
  • Include Rust version (rustc --version), operating system, architecture, and hyperlite version.
  • Keep conversations respectful and constructive.

Code of Conduct

  • Treat all contributors with respect and empathy.
  • Welcome newcomers and offer guidance where possible.
  • Focus on constructive, actionable feedback.
  • Assume good intentions and work collaboratively to resolve disagreements.
  • Harassment or discrimination will not be tolerated.
  • Report violations privately to the maintainers for review.
  • This project follows the principles of the Contributor Covenant Code of Conduct v2.1.

Review Process

  • Maintainers strive to review pull requests within one week.
  • If feedback is not addressed within two weeks, the PR may be closed to keep the queue manageable.
  • At least one maintainer approval is required before merging.
  • CI must pass before a PR can be merged.
  • Open an issue for discussion before submitting a breaking change.

Release Process (Maintainers)

  1. Update CHANGELOG.md with the release date and contents.
  2. Bump the version in Cargo.toml.
  3. Tag the release: git tag -a vX.Y.Z -m "Release X.Y.Z".
  4. Push the tag: git push origin vX.Y.Z.
  5. Publish to crates.io: cargo publish.
  6. Create a GitHub release with highlights from the changelog.

Questions and Support

  • Open a GitHub issue with the "Question" label for help.
  • Review existing documentation and examples first.
  • Clearly describe what you are trying to accomplish and include code snippets when helpful.

License

By contributing to Hyperlite, you agree that your contributions will be licensed under the MIT License. Please ensure you have the right to submit your work under this license.