-
Notifications
You must be signed in to change notification settings - Fork 66
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
* Add contributing doc for eyre * update labels and remove unnecessary complexity
- Loading branch information
Showing
1 changed file
with
181 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,181 @@ | ||
| # Welcome to the eyre contributing guide | ||
|
|
||
| Thank you for investing your time in contributing to our project! Eyre is a | ||
| community owned and maintained project dedicated to improving the error | ||
| handling and error reporting experience of users of the Rust programming | ||
| language. | ||
|
|
||
| Check out our community's[^1] [Code of | ||
| Conduct](https://www.rust-lang.org/policies/code-of-conduct) and feel free to | ||
| say hi on [Discord] if you'd like. It's a nice place to chat about eyre | ||
| development, ask questions, and get to know the other contributors and users in | ||
| a less formal setting. | ||
|
|
||
| ## The Eyre Organization | ||
|
|
||
| The Eyre Organization is the group of people responsible for stewarding the | ||
| Eyre project. It handles things like merging pull requests, choosing project | ||
| direction, managing bugs / issues / feature requests, controlling access to | ||
| secrets, defining and enforcing best practices, etc. | ||
|
|
||
| The eyre organization's governance is based on and inspired by | ||
| [sociocracy](https://www.sociocracyforall.org/sociocracy/), the Rust Project, | ||
| and the Bevy Organization. Many thanks to their great examples and resources. | ||
|
|
||
| Note that you *do not* need to be a member of the Eyre Organization to | ||
| contribute to Eyre. Community contributors (this means you) can freely open | ||
| issues, submit pull requests, and review pull requests. | ||
|
|
||
| ### New contributor guide | ||
|
|
||
| To get an overview of the project, read the [README](README.md). Here are some | ||
| resources to help you get started with open source contributions: | ||
|
|
||
| - [Finding ways to contribute to open source on GitHub](https://docs.github.com/en/get-started/exploring-projects-on-github/finding-ways-to-contribute-to-open-source-on-github) | ||
| - [Set up Git](https://docs.github.com/en/get-started/quickstart/set-up-git) | ||
| - [GitHub flow](https://docs.github.com/en/get-started/quickstart/github-flow) | ||
| - [Collaborating with pull requests](https://docs.github.com/en/github/collaborating-with-pull-requests) | ||
|
|
||
| Your first PR will be merged in no time! | ||
|
|
||
| No matter how you're helping: thank you for contributing to Eyre! | ||
|
|
||
| ### Classifying PRs | ||
|
|
||
| We use labels to organize our issues and PRs. | ||
|
|
||
| Each [label](https://github.com/eyre-rs/eyre/labels) has a prefix denoting its category: | ||
|
|
||
| * A: Area or subcrate (e.g. A-eyre, A-color-eyre, A-color-spantrace) | ||
| * C: Category (e.g. C-Breaking-Change, C-Code-Quality, C-Docs) | ||
| * P: Priority (e.g. P-Urgent, P-Important) | ||
| * S: Status (e.g. S-Blocked, S-Controversial, S-Needs-Design) | ||
| * Misc (e.g. "good first issue", "help wanted", "duplicate", "invalid", "wontfix") | ||
|
|
||
| ## Making changes to Eyre | ||
|
|
||
| Most changes don't require much process. If your change is relatively straightforward, just do the following: | ||
|
|
||
| 1. A community member (that's you!) creates one of the following: | ||
| * [GitHub Discussions]: An informal discussion with the community. This is | ||
| the place to start if you want to propose a feature or specific | ||
| implementation and gathering community wisdom and advice before jumping | ||
| to solutions. | ||
| * [Issue](https://github.com/eyre-rs/eyre/issues): A formal way for us to | ||
| track a bug or feature. Please look for duplicates before opening a new | ||
| issue and consider starting with a Discussion. | ||
| * [Pull Request](https://github.com/eyre-rs/eyre/pulls) (or PR for short): | ||
| A request to merge code changes. This starts our "review process". You | ||
| are welcome to start with a pull request, but consider starting with an | ||
| Issue or Discussion for larger changes (or if you aren't certain about a | ||
| design). We don't want anyone to waste their time on code that didn't | ||
| have a chance to be merged! But conversely, sometimes PRs are the most | ||
| efficient way to propose a change. Just use your own judgement here. | ||
| 2. Other community members review and comment in an ad-hoc fashion. Active | ||
| subject matter experts may be pulled into a thread using `@mentions`. If | ||
| your PR has been quiet for a while and is ready for review, feel free to | ||
| leave a message to "bump" the thread, or bring it up on [Discord] | ||
| 3. Once they're content with the pull request (design, code quality, | ||
| documentation, tests), individual reviewers leave "Approved" reviews. | ||
| 4. After consensus has been reached (typically two approvals from the community | ||
| or one for extremely simple changes) and CI passes, the | ||
| [S-Ready-For-Final-Review](https://github.com/eyre-rs/eyre/issues?q=is%3Aopen+is%3Aissue+label%3AS-Ready-For-Final-Review) | ||
| label is added. | ||
| 5. When they find time, someone with merge rights performs a final code review | ||
| and queue the PR for merging. | ||
|
|
||
| ## How you can help | ||
|
|
||
| If you've made it to this page, you're probably already convinced that Eyre is | ||
| a project you'd like to see thrive. But how can *you* help? | ||
|
|
||
| No matter your experience level with Eyre or Rust or your level of commitment, | ||
| there are ways to meaningfully contribute. Take a look at the sections that | ||
| follow to pick a route (or five) that appeal to you. | ||
|
|
||
| If you ever find yourself at a loss for what to do, or in need of mentorship or | ||
| advice on how to contribute to Eyre, feel free to ask in [Discord] and one of | ||
| our more experienced community members will be happy to help. | ||
|
|
||
| ### Writing Handlers | ||
|
|
||
| You can improve Eyre's ecosystem by building your own | ||
| [EyreHandler](https://docs.rs/eyre/0.6.8/eyre/trait.EyreHandler.html) crates | ||
| like [color-eyre](https://github.com/eyre-rs/color-eyre/). The customizable | ||
| reporting of `eyre` is it's secret sauce, using that customizability in | ||
| creative ways and sharing your work is one of the best ways you can inspire | ||
| others and help grow our community. | ||
|
|
||
| ### Fixing bugs | ||
|
|
||
| Bugs in Eyre are filed on the issue tracker using the [`C-bug`](https://github.com/eyre-rs/eyre/issues?q=is%3Aissue+is%3Aopen+label%3AC-Bug) label. | ||
|
|
||
| If you're looking for an easy place to start, take a look at the [`good first | ||
| issue`](https://github.com/eyre-rs/eyre/labels/good%20first%20issue) label, and | ||
| feel free to ask questions on that issue's thread in question or on [Discord]. | ||
| You don't need anyone's permission to try fixing a bug or adding a simple | ||
| feature, but stating that you'd like to tackle an issue can be helpful to avoid | ||
| duplicated work. | ||
|
|
||
| When you make a pull request that fixes an issue, include a line that says | ||
| `Fixes #X` (or "Closes"), where `X` is the issue number. This will cause the | ||
| issue in question to be closed when your PR is merged. | ||
|
|
||
| General improvements to code quality are also welcome! | ||
| Eyre can always be safer, better tested, and more idiomatic. | ||
|
|
||
| ### Writing docs | ||
|
|
||
| This is incredibly valuable, easily distributed work, but requires a bit of guidance: | ||
|
|
||
| * Inaccurate documentation is worse than no documentation: prioritize fixing | ||
| broken docs. | ||
| * Code documentation (doc examples and in the examples folder) is easier to | ||
| maintain because the compiler will tell us when it breaks. | ||
| * Inline documentation should be technical and to the point. Link relevant | ||
| examples or other explanations if broader context is useful. | ||
|
|
||
| ### Reviewing others' work | ||
|
|
||
| Reviewing others work with the aim of improving it is one of the most helpful | ||
| things you can do. You don't need to be an Elder Rustacean to be useful here: | ||
| anyone can catch missing tests, unclear docs, logic errors, and so on. If you | ||
| have specific skills (e.g. advanced familiarity with `unsafe` code, rendering | ||
| knowledge or web development experience) or personal experience with a problem, | ||
| try to prioritize those areas to ensure we can get appropriate expertise where | ||
| we need it. | ||
|
|
||
| Focus on giving constructive, actionable feedback that results in real | ||
| improvements to code quality or end-user experience. If you don't understand | ||
| why an approach was taken, please ask! | ||
|
|
||
| Provide actual code suggestions when that is helpful. Small changes work well | ||
| as comments or in-line suggestions on specific lines of codes. Larger changes | ||
| deserve a comment in the main thread, or a pull request to the original | ||
| author's branch (but please mention that you've made one). | ||
|
|
||
| Once you're happy with the work and feel you're reasonably qualified to assess | ||
| quality in this particular area, leave your `Approved` review on the PR. If | ||
| you're new to GitHub, check out the [Pull Request Review | ||
| documentation](https://docs.github.com/en/github/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/about-pull-request-reviews). | ||
| Anyone can leave reviews ... no special permissions are required! | ||
|
|
||
| There are three main places you can check for things to review: | ||
|
|
||
| 1. Pull request which are ready and in need of more reviews on | ||
| [eyre](https://github.com/eyre-rs/eyre/pulls?q=is%3Aopen+is%3Apr+-label%3AS-Ready-For-Final-Review+-draft%3A%3Atrue+-label%3AS-Needs-RFC+-reviewed-by%3A%40me+-author%3A%40me) | ||
| 2. Pull requests on [eyre](https://github.com/eyre-rs/eyre/pulls) and the | ||
| [color-eyre](https://github.com/eyre-rs/color-eyre/pulls) repos. | ||
|
|
||
| Not even our Circle Members are exempt from reviews! By giving feedback on this | ||
| work (and related supporting work), you can help us make sure our releases are | ||
| both high-quality and timely. | ||
|
|
||
| Finally, if nothing brings you more satisfaction than seeing every last issue | ||
| labeled and all resolved issues closed, feel free to message any Eyre Circle | ||
| Member (currently @yaahc) for the triage role to help us keep things tidy. This | ||
| role only requires good faith and a basic understanding of our development | ||
| process. | ||
|
|
||
| [Discord]: https://discord.gg/z94RqmUTKB | ||
| [^1]: Okay, I'll admit it, it's really just the Rust Project's CoC :sweat_smile: |