eyre/CONTRIBUTING.md

# 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: