|
| 1 | +# Contributing to Phylo |
| 2 | + |
| 3 | +Hey there! First off, thank you for considering contributing to the `phylo` crate! This is a young crate in active development, so any contributions are welcome. |
| 4 | + |
| 5 | +To keep the code clean and good quality, please check out the [Rust API guidelines]( https://rust-lang.github.io/api-guidelines/about.html ) and try to follow them when contributing to the codebase. |
| 6 | + |
| 7 | +And just as a gentle reminder, all contributors are expected to follow [Rust's Code of Conduct]( https://www.rust-lang.org/policies/code-of-conduct ). |
| 8 | + |
| 9 | +We welcome all types of contributions: |
| 10 | + |
| 11 | +- **🐛 Bug fixes**: Help us squash bugs! |
| 12 | +- **✨ New features**: Enhance the crate's functionality; |
| 13 | +- **📚 Documentation**: Improve docs, examples, or guides; |
| 14 | +- **🔧 Performance**: Optimise existing code; |
| 15 | +- **🧪 Tests**: Add test coverage; |
| 16 | +- **🎨 Code quality**: Refactoring and cleanup. |
| 17 | + |
| 18 | +[Bug Reports](#bug-reports-and-feature-requests) • [Getting Started](#getting-started) • [Code Quality](#ensuring-code-quality) • [Code Review](#code-review-process) • [Support](#community--support) |
| 19 | + |
| 20 | +## Bug Reports and Feature Requests |
| 21 | + |
| 22 | +For questions, bug reports, or feature requests, please go to [rust-phylo discussion page]( https://github.com/acg-team/rust-phylo/discussions ) and/or open an issue on [GitHub]( https://github.com/acg-team/rust-phylo/issues ). |
| 23 | + |
| 24 | +In case you would like to add a feature to the crate, please open an issue first and then tackle it with a pull request. |
| 25 | + |
| 26 | +## Getting Started |
| 27 | + |
| 28 | +### Prerequisites |
| 29 | + |
| 30 | +- **Rust**: install the latest stable Rust toolchain via [rustup](https://rustup.rs/); |
| 31 | +- **Git**: for version control; |
| 32 | +- **A GitHub account**: for submitting pull requests. |
| 33 | + |
| 34 | +### Setting Up Your Development Environment |
| 35 | + |
| 36 | +1. **Fork the repository** on GitHub |
| 37 | +2. **Clone your fork** locally: |
| 38 | + ```bash |
| 39 | + git clone https://github.com/YOUR_USERNAME/rust-phylo.git |
| 40 | + cd rust-phylo/phylo |
| 41 | + ``` |
| 42 | +3. **Add the upstream remote**: |
| 43 | + ```bash |
| 44 | + git remote add upstream https://github.com/acg-team/rust-phylo.git |
| 45 | + ``` |
| 46 | +4. **Install development dependencies**: |
| 47 | + ```bash |
| 48 | + rustup component add rustfmt clippy |
| 49 | + ``` |
| 50 | +5. **Run the test suite** to make sure everything works: |
| 51 | + ```bash |
| 52 | + cargo test --features deterministic |
| 53 | + ``` |
| 54 | + |
| 55 | +### Contribution Workflow |
| 56 | + |
| 57 | +1. **Create a new branch** for your feature/fix: |
| 58 | + ```bash |
| 59 | + git checkout -b feature/your-feature-name |
| 60 | + ``` |
| 61 | +2. **Make your changes** following the guidelines below |
| 62 | +3. **Test thoroughly**: |
| 63 | + ```bash |
| 64 | + cargo test --features deterministic |
| 65 | + cargo clippy |
| 66 | + cargo fmt --check |
| 67 | + ``` |
| 68 | +4. **Commit your changes** with clear, descriptive commit messages |
| 69 | +5. **Push to your fork**: |
| 70 | + ```bash |
| 71 | + git push origin feature/your-feature-name |
| 72 | + ``` |
| 73 | +6. **Open a Pull Request** on GitHub with a clear description of your changes |
| 74 | + |
| 75 | +## Ensuring Code Quality |
| 76 | + |
| 77 | +If you decide to tackle an issue from our [issue list]( https://github.com/acg-team/rust-phylo/issues ), please follow these guidelines to make the review process go smoothly. We recommend reading [Rust crate guidelines]( https://rust-lang.github.io/api-guidelines/about.html ) to make sure your contribution is up to scratch! |
| 78 | + |
| 79 | +When you submit a pull request, it will be automatically tested and code coverage will run with GitHub Actions. We are aiming to maintain our current code coverage percentage, so if the report claims that some new features are missing tests, please add some! Bear in mind that the code coverage report will take around 1.5 hours to generate, so please be patient. In addition to running the tests, GitHub Actions runs Clippy and `rustfmt` on each PR. |
| 80 | + |
| 81 | +### Running Tests |
| 82 | + |
| 83 | +Before submitting a pull request, please run the test suite locally. To run the tests you will need to enable the `deterministic` feature: |
| 84 | + |
| 85 | +```bash |
| 86 | +cargo test --features deterministic |
| 87 | +``` |
| 88 | + |
| 89 | +For faster test runs during development, you can also use: |
| 90 | + |
| 91 | +```bash |
| 92 | +cargo test --features "deterministic,precomputed-test-results" |
| 93 | +``` |
| 94 | + |
| 95 | +### Formatting Code with `rustfmt` |
| 96 | + |
| 97 | +Before you make your pull request to the project, please run it through the `rustfmt` utility. This will ensure we have good quality source code that is better for us all to maintain. |
| 98 | + |
| 99 | +1. Install it (`rustfmt` is usually installed by default via [rustup](https://rustup.rs/)): |
| 100 | + ``` |
| 101 | + rustup component add rustfmt |
| 102 | + ``` |
| 103 | +2. You can now run `rustfmt` on a single file simply by... |
| 104 | + ``` |
| 105 | + rustfmt src/path/to/your/file.rs |
| 106 | + ``` |
| 107 | + ... or you can format the entire project with |
| 108 | + ``` |
| 109 | + cargo fmt |
| 110 | + ``` |
| 111 | + When run through `cargo` it will format all bin and lib files in the current package. |
| 112 | +
|
| 113 | +**Visual Studio Code users**: the [rust-analyzer]( https://rust-analyzer.github.io/ ) extension will automatically run `rustfmt` for you when you save the files. |
| 114 | +
|
| 115 | +### Finding Issues with Clippy |
| 116 | +
|
| 117 | +[Clippy]( https://doc.rust-lang.org/clippy/ ) is a code analyser/linter detecting mistakes, and therefore helps to improve your code. Like formatting your code with `rustfmt`, running clippy regularly and before your pull request will help us maintain awesome code. |
| 118 | +
|
| 119 | +1. To install |
| 120 | + ``` |
| 121 | + rustup component add clippy |
| 122 | + ``` |
| 123 | +2. Running clippy |
| 124 | + ``` |
| 125 | + cargo clippy |
| 126 | + ``` |
| 127 | +
|
| 128 | +**Visual Studio Code users**: you can set Clippy as your default linter if you install the [rust-analyzer]( https://rust-analyzer.github.io/ ) extension and set its `rust-analyzer.check.command` to `clippy`. This will highlight all of Clippy lints in your workspace. |
| 129 | +
|
| 130 | +### Documentation |
| 131 | +
|
| 132 | +Good documentation is crucial for users and maintainers. For your PR, please ensure: |
| 133 | +
|
| 134 | +- **Public APIs** have comprehensive doc comments with doctests; |
| 135 | +- **Complex algorithms** include explanatory comments; |
| 136 | +- **New features** are documented in relevant modules; |
| 137 | +- **Breaking changes** are noted in commit messages. |
| 138 | +
|
| 139 | +<!-- To check documentation: |
| 140 | +```bash |
| 141 | +cargo doc --open |
| 142 | +``` |
| 143 | + |
| 144 | +### Benchmarks |
| 145 | + |
| 146 | +If your changes affect performance, please run benchmarks: |
| 147 | +```bash |
| 148 | +cargo bench |
| 149 | +``` |
| 150 | + |
| 151 | +Add new benchmarks for significant new functionality. --> |
| 152 | + |
| 153 | +## Code Review Process |
| 154 | + |
| 155 | +### What to Expect |
| 156 | + |
| 157 | +- **Automated checks**: Your PR will be tested with GitHub Actions; |
| 158 | +- **Review timeline**: We aim to provide initial feedback within a few days; |
| 159 | +- **Iterative process**: Expect suggestions and requests for changes; |
| 160 | +- **Learning opportunity**: Reviews are collaborative - ask questions! |
| 161 | + |
| 162 | +### Review Criteria |
| 163 | + |
| 164 | +We look for: |
| 165 | +- **Correctness**: Does the code work as intended? |
| 166 | +- **Performance**: Are there obvious performance issues? |
| 167 | +- **API design**: Is the interface intuitive and consistent? |
| 168 | +- **Tests**: Are edge cases covered? |
| 169 | +- **Documentation**: Is the code well-documented? |
| 170 | +- **Style**: Does it follow Rust conventions? |
| 171 | + |
| 172 | +## Community & Support |
| 173 | + |
| 174 | +- **Questions about contributing**: Open a [discussion](https://github.com/acg-team/rust-phylo/discussions); |
| 175 | +- **Technical questions**: Check existing [issues](https://github.com/acg-team/rust-phylo/issues) or open a new one; |
| 176 | +- **Be patient**: Reviews take time; |
| 177 | +- **Be collaborative**: We're all here to make the crate better together! |
| 178 | + |
| 179 | +--- |
| 180 | + |
| 181 | +Thank you for contributing to `phylo`! 🦀 |
0 commit comments