CONTRIBUTING.md

Contributing to spellout

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.

Getting Started

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

Reporting Bugs or Requesting Features

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:

1. Navigate to the issue tracker.
2. Click the "New issue" button.
3. Choose the appropriate template for your issue (bug report or feature request).
4. Fill out the template with all the necessary details to help us understand the issue or feature request.
5. Submit the issue.

Issue Labels

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.

Setting Up a Development Environment

spellout 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/spellout.git

Install Rust Dependencies

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 check for an example usage.

Automated Installation

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

Manual Installation

If you prefer to install the required tools manually, or need more control over the installation process, follow these steps:

1. Install the required toolchains and components:

   rustup toolchain add stable --component clippy
   rustup toolchain add nightly --component rustfmt
   

2. Install the required cargo dependencies:

   cargo install cargo-insta cargo-llvm-cov cargo-nextest cargo-watch
   

Install Additional Tools

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

Contribution Guidelines

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

Testing Conventions

spellout 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 a mod 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.

Contribution Process

1. Create a new branch for your changes

Based on the main branch, create a new branch for your work:

git checkout -b your-feature-branch

2. Make and commit changes

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.

3. Keep your branch up-to-date with the upstream repo

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.

4. Push your changes and create a pull request

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.

Useful Commands

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