Update issue triage, feature request, and contributions policies (#877)
Adopt ghostty's policy for using issues to track actionable bug reports or feature requests, and discussions for triaging issues or discussing potential feature requests.
This commit is contained in:
Aram Akhavan
GitHub
+140
-2
@@ -1,6 +1,144 @@
|
||||
# Contributing
|
||||
# Contributing to scrutiny
|
||||
|
||||
**Please see our [AI policy](./AI_POLICY.md).**
|
||||
This document describes the process of contributing to scrutiny. It is intended
|
||||
for anyone considering opening an **issue**, **discussion** or **pull request**.
|
||||
|
||||
> [!NOTE]
|
||||
>
|
||||
> The intention of these policies is not to be difficult, and
|
||||
> contributions are greatly appreciated. The goal is to streamline
|
||||
> and simplify the efforts of both contributers and maintainers.
|
||||
|
||||
## AI Usage
|
||||
|
||||
scrutiny has strict rules for AI usage. Please see
|
||||
the [AI Usage Policy](AI_POLICY.md). **This is very important.**
|
||||
|
||||
## Quick Guide
|
||||
|
||||
### I'd like to contribute
|
||||
|
||||
[All issues are actionable](#issues-are-actionable). Pick one and start
|
||||
working on it. Thank you. If you need help or guidance, comment on the issue.
|
||||
Issues that are extra friendly to new contributors are tagged with
|
||||
["contributor friendly"].
|
||||
|
||||
["contributor friendly"]: https://github.com/AnalogJ/scrutiny/issues?q=is%3Aissue%20is%3Aopen%20label%3A%22contributor%20friendly%22
|
||||
|
||||
### I have a bug! / Something isn't working
|
||||
|
||||
First, search the issue tracker and discussions for similar issues. Tip: also
|
||||
search for [closed issues] and [discussions] — your issue might have already
|
||||
been fixed!
|
||||
|
||||
> [!NOTE]
|
||||
>
|
||||
> If there is an _open_ issue or discussion that matches your problem,
|
||||
> **please do not comment on it unless you have valuable insight to add**.
|
||||
>
|
||||
> GitHub has a very _noisy_ set of default notification settings which
|
||||
> sends an email to _every participant_ in an issue/discussion every time
|
||||
> someone adds a comment. Instead, use the handy upvote button for discussions,
|
||||
> and/or emoji reactions on both discussions and issues, which are a visible
|
||||
> yet non-disruptive way to show your support.
|
||||
|
||||
If your issue hasn't been reported already, open an ["Issue Triage"] discussion
|
||||
and make sure to fill in the template **completely**. They are vital for
|
||||
maintainers to figure out important details about your setup.
|
||||
|
||||
> [!WARNING]
|
||||
>
|
||||
> A _very_ common mistake is to file a bug report either as a Q&A or a Feature
|
||||
> Request. **Please don't do this.** Otherwise, maintainers would have to ask
|
||||
> for your system information again manually, and sometimes they will even ask
|
||||
> you to create a new discussion because of how few detailed information is
|
||||
> required for other discussion types compared to Issue Triage.
|
||||
>
|
||||
> Because of this, please make sure that you _only_ use the "Issue Triage"
|
||||
> category for reporting bugs — thank you!
|
||||
|
||||
[closed issues]: https://github.com/AnalogJ/scrutiny/issues?q=is%3Aissue%20state%3Aclosed
|
||||
[discussions]: https://github.com/AnalogJ/scrutiny/discussions?discussions_q=is%3Aclosed
|
||||
["Issue Triage"]: https://github.com/AnalogJ/scrutiny/discussions/new?category=issue-triage
|
||||
|
||||
### I have an idea for a feature
|
||||
|
||||
Like bug reports, first search through both issues and discussions and try to
|
||||
find if your feature has already been requested. Otherwise, open a discussion
|
||||
in the ["Feature Requests, Ideas"] category.
|
||||
|
||||
["Feature Requests, Ideas"]: https://github.com/AnalogJ/scrutiny/discussions/new?category=feature-requests-ideas
|
||||
|
||||
### I've implemented a feature
|
||||
|
||||
1. If there is an issue for the feature, open a pull request straight away.
|
||||
2. If there is no issue, open a discussion and link to your branch.
|
||||
3. If you want to live dangerously, open a pull request and
|
||||
[hope for the best](#pull-requests-implement-an-issue).
|
||||
|
||||
### I have a question which is neither a bug report nor a feature request
|
||||
|
||||
Open a [Q&A discussion].
|
||||
|
||||
> [!NOTE]
|
||||
> If your question is about a missing feature, please open a discussion under
|
||||
> the ["Feature Requests, Ideas"] category. If scrutiny is behaving
|
||||
> unexpectedly, use the ["Issue Triage"] category.
|
||||
>
|
||||
> The "Q&A" category is strictly for other kinds of discussions and do not
|
||||
> require detailed information unlike the two other categories, meaning that
|
||||
> maintainers would have to spend the extra effort to ask for basic information
|
||||
> if you submit a bug report under this category.
|
||||
>
|
||||
> Therefore, please **pay attention to the category** before opening
|
||||
> discussions to save us all some time and energy. Thank you!
|
||||
|
||||
[Q&A discussion]: https://github.com/AnalogJ/scrutiny/discussions/new?category=q-a
|
||||
|
||||
## General Patterns
|
||||
|
||||
### Issues are Actionable
|
||||
|
||||
The scrutiny [issue tracker](https://github.com/AnalogJ/scrutiny/issues)
|
||||
is for _actionable items_.
|
||||
|
||||
Unlike some other projects, scrutiny **does not use the issue tracker for
|
||||
discussion or feature requests**. Instead, we use GitHub
|
||||
[discussions](https://github.com/AnalogJ/scrutiny/discussions) for that.
|
||||
Once a discussion reaches a point where a well-understood, actionable
|
||||
item is identified, it is moved to the issue tracker. **This pattern
|
||||
makes it easier for maintainers or contributors to find issues to work on
|
||||
since _every issue_ is ready to be worked on.**
|
||||
|
||||
If you are experiencing a bug and have clear steps to reproduce it, please
|
||||
open an issue. If you are experiencing a bug but you are not sure how to
|
||||
reproduce it or aren't sure if it's a bug, please open a discussion.
|
||||
If you have an idea for a feature, please open a discussion.
|
||||
|
||||
### Pull Requests Implement an Issue
|
||||
|
||||
Pull requests should be associated with a previously accepted issue.
|
||||
**If you open a pull request for something that wasn't previously discussed,**
|
||||
it may be closed or remain stale for an indefinite period of time. I'm not
|
||||
saying it will never be accepted, but the odds are stacked against you.
|
||||
|
||||
Issues tagged with "feature" represent accepted, well-scoped feature requests.
|
||||
If you implement an issue tagged with feature as described in the issue, your
|
||||
pull request will be accepted with a high degree of certainty.
|
||||
|
||||
> [!NOTE]
|
||||
>
|
||||
> **Pull requests are NOT a place to discuss feature design.** Please do
|
||||
> not open a WIP pull request to discuss a feature. Instead, use a discussion
|
||||
> and link to your branch.
|
||||
|
||||
# Developer Guide
|
||||
|
||||
> [!NOTE]
|
||||
>
|
||||
> **The remainder of this file is dedicated to developers actively
|
||||
> working on scrutiny.** If you're a user reporting an issue, you can
|
||||
> ignore the rest of this document.
|
||||
|
||||
The Scrutiny repository is a [monorepo](https://en.wikipedia.org/wiki/Monorepo) containing source code for:
|
||||
- Scrutiny Backend Server (API)
|
||||
|
||||
Reference in New Issue
Block a user