Add contributing doc for eyre (#99)

* Add contributing doc for eyre * update labels and remove unnecessary complexity
2025-09-27 04:50:50 +00:00 · 2023-11-07 14:02:24 -08:00 · 2023-11-07 14:02:24 -08:00 · 12479e96ef
commit 12479e96ef
parent 2ec1dff66d
1 changed files with 181 additions and 0 deletions
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@ -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: