Thank you for your interest in contributing to our open source project! This document will guide you through the process. To maintain a respectful and welcoming community, please adhere to the Code of Conduct.
RustOps Blueprint uses the GitHub issue tracker to manage bugs and feature requests. If you'd like to work on a specific issue, leave a comment, and we will assign it to you. For general questions and open-ended conversations, use the dedicated community discussions space instead.
Please submit contributions through GitHub pull requests. Each PR will be reviewed by a core contributor (someone with permission to approve patches), and either merged or provided with feedback for any required changes. This process applies to all contributions, including those from core contributors.
If your intended contribution is complex or requires discussion, open a new ideas discussion about the change before starting the work. We're more than happy to mentor contributors and provide guidance or clarification when needed.
We appreciate your help in identifying issues or suggesting new features for our project. To gather all relevant information and streamline the process, we use built-in issue templates on GitHub.
Before opening a new issue, please search the existing issues to see if your concern has already been reported or a similar feature has been requested. This helps us avoid duplicate issues and ensures that we can focus on addressing unique concerns effectively.
When reporting a bug or requesting a feature, please follow these steps:
- Navigate to the issue tracker.
- Click the "New issue" button.
- Choose the appropriate template for your issue (bug report or feature request).
- Fill out the template with all the necessary details to help us understand the issue or feature request.
- Submit the issue.
Built-in issue templates will automatically apply some labels, but we also rely on GitHub's default labels to categorize issues and pull requests further. Familiarize yourself with these labels to better understand the organization and prioritization of tasks within the project.
RustOps Blueprint follows the "fork and pull" workflow model. After installing Rust, fork this repository and create a local clone of your fork.
To facilitate tracking changes in the upstream repository, add it as a remote:
git remote add upstream https://github.com/EarthmanMuons/rustops-blueprint.git
The project is developed using the latest stable release of Rust, but it also
requires a couple of additional toolchain components. We use the lint tool
clippy
for extra checks on common mistakes and stylistic choices, as well
as the nightly version of rustfmt
for automatic code formatting.
Additionally, our project utilizes cargo-insta
for snapshot testing,
cargo-llvm-cov
to generate code coverage reports, and cargo-nextest
as an enhanced test runner. It displays each test's execution time by default,
and can help to identify performance outliers in the test suite.
For faster feedback loops during development, we recommend using
cargo-watch
. This tool watches for changes in project files and
automatically triggers specified Cargo commands when they occur. See
cargo xtask dev
for an example usage.
We've provided an xtask script to automatically install all required toolchain components and cargo dependencies. To use this, run the following command:
cargo xtask install
If you prefer to install the required tools manually, or need more control over the installation process, follow these steps:
-
Install the required toolchains and components:
rustup toolchain add stable --component clippy rustup toolchain add nightly --component rustfmt
-
Install the required cargo dependencies:
cargo install cargo-insta cargo-llvm-cov cargo-nextest cargo-watch
To maintain consistency and avoid bikeshedding, our project also uses automated tools to enforce formatting and style conventions for non-Rust files. Ensure that you have the following tools installed:
- actionlint for linting GitHub Actions workflow files
- Prettier for formatting Markdown files
- typos for spell checking all files
-
Adhere to the coding style conventions used in the project, which are enforced by the automated tools mentioned earlier. (Hint: Run
cargo xtask fixup
to edit repository files in-place and apply all automated fixes.) -
Write clear and concise commit messages.
-
Update documentation as necessary.
-
Follow the Keep a Changelog format when updating the changelog.
-
Ensure your changes are thoroughly tested. Our continuous integration (CI) pipeline extensively tests all pull requests, and to be merged, a PR must have no warnings or errors.
RustOps Blueprint follows standard Rust testing conventions, which includes:
-
Unit tests: Located alongside the source code files they test. Unit tests focus on individual functions or modules and should be placed in the same file, usually at the bottom, under a
#[cfg(test)]
attribute and amod tests { ... }
block. -
Integration tests: Located in the top-level
tests/
directory. Integration tests cover the interaction between multiple components or the behavior of the whole system. -
Snapshot tests: We use
cargo-insta
for maintaining snapshot tests. These tests compare the output of your code against a previously recorded "snapshot" to ensure consistent results. Follow the upstream documentation for creating and updating snapshots as needed.
When contributing, ensure that your changes are well-tested by including appropriate unit, integration, and snapshot tests as necessary.
Based on the main
branch, create a new branch for your work:
git checkout -b your-feature-branch
Use the stacked commit approach, where each commit represents a single change, including all applicable documentation, tests, and so on. This simplifies the pull request review process and maintains a clean commit history.
Regularly rebase your branch to stay current with the latest changes in the upstream repository:
git fetch upstream
git rebase upstream/main
Resolve any conflicts that may occur during the rebase process.
When your changes are ready for review, push your branch to your fork:
git push -u origin your-feature-branch
Create a pull request on GitHub, comparing your fork's branch with the original
repository's main
branch. If changes are requested, rewrite the branch rather
than adding commits on top, and then force push them to your repository. As you
update your PR and apply changes, mark each conversation as resolved.
Once your changes have been discussed and approved, we use GitHub merge
queues to enforce the not rocket science rule of software engineering,
ensuring that tests on the main
branch always pass.
There are some helpful xtask scripts in the repository for running common tasks and replicating CI jobs locally. You can view the details and available commands by running:
cargo xtask --help
For example:
-
Generate and open an HTML code coverage report
cargo xtask coverage.html
-
Run all tests/doctests and generate Insta snapshots
cargo xtask test
Most other commands are the same as any standard Rust project:
-
Lint the code
cargo clippy
-
Format the code
cargo +nightly fmt
-
Run the tests
cargo nextest run
-
Run the doctests
cargo test --doc
-
Build and run the binary:
cargo run --bin mybin --