diff --git a/Makefile b/Makefile index 45fcd6ad150..2ca9f84dec7 100644 --- a/Makefile +++ b/Makefile @@ -60,3 +60,10 @@ install: .PHONY: clean clean: rm -rf integration/testdata/fixtures/ + +$(GOBIN)/labeler: + GO111MODULE=off go get github.com/knqyf263/labeler + +.PHONY: label +label: $(GOBIN)/labeler + labeler apply misc/triage/labels.yaml -r aquasecurity/trivy -l 5 diff --git a/docs/contrib/help-wanted.md b/docs/contrib/help-wanted.md new file mode 100644 index 00000000000..41111731a9f --- /dev/null +++ b/docs/contrib/help-wanted.md @@ -0,0 +1,78 @@ +# Overview + +We use two labels [help wanted](#help-wanted) and [good first +issue](#good-first-issue) to identify issues that have been specially groomed +for new contributors. The `good first issue` label is a subset of `help wanted` +label, indicating that members have committed to providing extra assistance for +new contributors. All `good first issue` items also have the `help wanted` +label. + +## Help Wanted + +Items marked with the `help wanted` label need to ensure that they are: + +- **Low Barrier to Entry** + + It should be tractable for new contributors. Documentation on how that type of + change should be made should already exist. + +- **Clear Task** + + The task is agreed upon and does not require further discussions in the + community. Call out if that area of code is untested and requires new + fixtures. + + API / CLI behavior is decided and included in the OP issue, for example: "The + new command syntax is `trivy --format yaml IMAGE_NAME`"_ with + expected validations called out. + +- **Goldilocks priority** + + Not too high that a core contributor should do it, but not too low that it + isn't useful enough for a core contributor to spend time to review it, answer + questions, help get it into a release, etc. + +- **Up-To-Date** + + Often these issues become obsolete and have already been done, are no longer + desired, no longer make sense, have changed priority or difficulty , etc. + + +## Good First Issue + +Items marked with the `good first issue` label are intended for _first-time +contributors_. It indicates that members will keep an eye out for these pull +requests and shepherd it through our processes. + +These items need to ensure that they follow the guidelines for `help wanted` +labels (above) in addition to meeting the following criteria: + +- **No Barrier to Entry** + + The task is something that a new contributor can tackle without advanced + setup, or domain knowledge. + +- **Solution Explained** + + The recommended solution is clearly described in the issue. + +- **Provides Context** + + If background knowledge is required, this should be explicitly mentioned and a + list of suggested readings included. + +- **Gives Examples** + + Link to examples of similar implementations so new contributors have a + reference guide for their changes. + +- **Identifies Relevant Code** + + The relevant code and tests to be changed should be linked in the issue. + +- **Ready to Test** + + There should be existing tests that can be modified, or existing test cases + fit to be copied. If the area of code doesn't have tests, before labeling the + issue, add a test fixture. This prep often makes a great `help wanted` task! + diff --git a/docs/contrib/triage.md b/docs/contrib/triage.md new file mode 100644 index 00000000000..f75151e0f4d --- /dev/null +++ b/docs/contrib/triage.md @@ -0,0 +1,195 @@ +Triage is an important part of maintaining the health of the trivy repo. +A well organized repo allows maintainers to prioritize feature requests, fix bugs, and respond to users facing difficulty with the tool as quickly as possible. + +Triage includes: +- Labeling issues +- Responding to issues +- Closing issues + +# Daily Triage +Daily triage has two goals: + +1. Responsiveness for new issues +1. Responsiveness when explicitly requested information was provided + +It covers: + +1. Issues without a `kind/` or `triage/` label +1. Issues without a `priority/` label +1. `triage/needs-information` issues which the user has followed up on, and now require a response. + +## Categorization + +The most important level of categorizing the issue is defining what type it is. +We typically want at least one of the following labels on every issue, and some issues may fall into multiple categories: + +- `triage/support` - The default for most incoming issues +- `kind/bug` - When it’s a bug or we aren’t delivering the best user experience + +Other possibilities: +- `kind/feature`- Identify new feature requests +- `kind/testing` - Update or fix unit/integration tests +- `kind/cleanup` - Cleaning up/refactoring the codebase +- `kind/documentation` - Updates or additions to trivy documentation + +If the issue is specific to a driver for OS packages or libraries: + +**co/[driver for OS packages]** + + - `co/alpine` + - `co/amazon` + - `co/debian` + - `co/oracle` + - `co/photon` + - `co/redhat` + - `co/suse` + - `co/ubuntu` + +**co/[driver for libraries of programming languages]** + + - `co/bundler` + - `co/cargo` + - `co/composer` + - `co/npm` + - `co/yarn` + - `co/pipenv` + - `co/poetry` + + +**Help wanted?** + +`Good First Issue` - bug has a proposed solution, can be implemented w/o further discussion. + +`Help wanted` - if the bug could use help from a contributor + + +## Prioritization +If the issue is not `triage/support`, it needs a priority label. + +`priority/critical-urgent` - someones top priority ASAP, such as security issue, user-visible bug, or build breakage. Rarely used. + +`priority/important-soon`: in time for the next two releases. It should be attached to a milestone. + +`priority/important-longterm`: 2-4 releases from now + +`priority/backlog`: agreed that this would be good to have, but no one is available at the moment. Consider tagging as `help wanted` + +`priority/awaiting-more-evidence`: may be useful, but there is not yet enough support. + + +# Weekly Triage + +Weekly triage has three goals: + +1. Catching up on unresponded issues +1. Reviewing and closing PR’s +1. Closing stale issues + + +## Post-Release Triage + +Post-release triage occurs after a major release (around every 4-6 weeks). +It focuses on: + +1. Closing bugs that have been resolved by the release +1. Reprioritizing bugs that have not been resolved by the release +1. Letting users know if we believe that there is still an issue + +This includes reviewing: + +1. Every issue that hasn’t been touched in the last 2 days +1. Re-evaluation of long-term issues +1. Re-evaluation of short-term issues + + +## Responding to Issues + +### Needs More Information +A sample response to ask for more info: + +> I don’t yet have a clear way to replicate this issue. Do you mind adding some additional details. Here is additional information that would be helpful: +> +> \* The exact `trivy` command line used +> +> \* The exact image you want to scan +> +> \* The full output of the `trivy` command, preferably with `--debug` for extra logging. +> +> +> Thank you for sharing your experience! + + +Then: Label with `triage/needs-information`. + +### Issue might be resolved +If you think a release may have resolved an issue, ask the author to see if their issue has been resolved: + +> Could you please check to see if trivy addresses this issue? We've made some changes with how this is handled, and improved the trivy logs output to help us debug tricky cases like this. + +Then: Label with `triage/needs-information`. + + +## Closing with Care + +Issues typically need to be closed for the following reasons: + +- The issue has been addressed +- The issue is a duplicate of an existing issue +- There has been a lack of information over a long period of time + +In any of these situations, we aim to be kind when closing the issue, and offer the author action items should they need to reopen their issue or still require a solution. + +Samples responses for these situations include: + +### Issue has been addressed + +>@author: I believe this issue is now addressed by trivy v1.0.0, as it . If you still see this issue with trivy v1.0 or higher, please reopen this issue. +> +>Thank you for reporting this issue! + +Then: Close the issue + +### Duplicate Issue + +>This issue appears to be a duplicate of #X, do you mind if we move the conversation there? +> +>This way we can centralize the content relating to the issue. If you feel that this issue is not in fact a duplicate, please re-open it. If you have additional information to share, please add it to the new issue. +> +>Thank you for reporting this! + +Then: Label with `triage/duplicate` and close the issue. + +### Lack of Information +If an issue hasn't been active for more than four weeks, and the author has been pinged at least once, then the issue can be closed. + +>Hey @author -- hopefully it's OK if I close this - there wasn't enough information to make it actionable, and some time has already passed. If you are able to provide additional details, you may reopen it at any point. +> +>Here is additional information that may be helpful to us: +> +>\* Whether the issue occurs with the latest trivy release +> +>\* The exact `trivy` command line used +> +>\* The exact image you want to scan +> +>\* The full output of the `trivy` command, preferably with `--debug` for extra logging. +> +> +>Thank you for sharing your experience! + +Then: Close the issue. + +## Help Wanted issues + +We use two labels [help wanted](https://github.com/aquasecurity/trivy/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22) +and [good first issue](https://github.com/aquasecurity/trivy/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22) +to identify issues that have been specially groomed for new contributors. + +We have specific [guidelines](/docs/help-wanted.md) +for how to use these labels. If you see an issue that satisfies these +guidelines, you can add the `help wanted` label and the `good first issue` label. +Please note that adding the `good first issue` label must also +add the `help wanted` label. + +If an issue has these labels but does not satisfy the guidelines, please +ask for more details to be added to the issue or remove the labels. \ No newline at end of file diff --git a/misc/triage/labels.yaml b/misc/triage/labels.yaml new file mode 100644 index 00000000000..ca33927aa66 --- /dev/null +++ b/misc/triage/labels.yaml @@ -0,0 +1,136 @@ +--- +repo: aquasecurity/trivy +labels: + +# kind +- name: kind/api-change + color: e11d21 + description: Categorizes issue or PR as related to adding, removing, or otherwise changing an API +- name: kind/bug + color: e11d21 + from: bug + description: Categorizes issue or PR as related to a bug. +- name: kind/cleanup + color: c7def8 + description: Categorizes issue or PR as related to cleaning up code, process, or technical debt. +- name: kind/deprecation + color: e11d21 + from: enhancement + description: Categorizes issue or PR as related to a feature/enhancement marked for deprecation. +- name: kind/documentation + color: c7def8 + description: Categorizes issue or PR as related to documentation. +- name: kind/feature + color: c7def8 + description: Categorizes issue or PR as related to a new feature. +- name: kind/testing + color: c7def8 + description: Categorizes issue or PR as related to a unit/integration test. +- name: kind/regression + color: e11d21 + description: Categorizes issue or PR as related to a regression from a prior release. +- name: kind/security + color: f4dddc + description: security issues + +# lifecycle +- name: lifecycle/frozen + color: d3e2f0 + description: Indicates that an issue or PR should not be auto-closed due to staleness. +- name: lifecycle/stale + color: "795548" + description: Denotes an issue or PR has remained open with no activity and will be auto-closed. + +# priority +- name: priority/critical-urgent + color: e11d21 + description: Highest priority. Must be actively worked on as someone's top priority right now. +- name: priority/important-soon + color: eb6420 + description: Must be staffed and worked on either currently, or very soon, ideally in time for the next release. +- name: priority/important-longterm + color: eb6420 + description: Important over the long term, but may not be staffed and/or may need multiple releases to complete. +- name: priority/backlog + color: fbca04 + description: Higher priority than priority/awaiting-more-evidence. +- name: priority/awaiting-more-evidence + color: fef2c0 + description: Lowest priority. Possibly useful, but not yet enough support to actually get it done. + +# triage +- name: triage/discuss + color: faff84 + description: Items for discussion +- name: triage/duplicate + color: d455d0 + from: duplicate + description: Indicates an issue is a duplicate of other open issue. +- name: triage/needs-information + color: d455d0 + description: Indicates an issue needs more information in order to work on it. +- name: triage/not-reproducible + color: d455d0 + description: Indicates an issue can not be reproduced as described. +- name: triage/obsolete + color: faff84 + description: Bugs that no longer occur in the latest stable release +- name: triage/support + color: d455d0 + from: question + description: Indicates an issue that is a support question. +- name: triage/unresolved + color: d455d0 + description: Indicates an issue that can not or will not be resolved. + +# component +- name: co/alpine + color: d9ead3 + description: Issues relating to Alpine image +- name: co/amazon + color: d9ead3 + description: Issues relating to Amazon Linux image +- name: co/debian + color: d9ead3 + description: Issues relating to Debian image +- name: co/oracle + color: d9ead3 + description: Issues relating to Oracle Linux image +- name: co/photon + color: d9ead3 + description: Issues relating to Photon OS image +- name: co/redhat + color: d9ead3 + description: Issues relating to RHEL/CentOS image +- name: co/suse + color: d9ead3 + description: Issues relating to openSUSE/SUSE Linux Enterprise image +- name: co/ubuntu + color: d9ead3 + description: Issues relating to Ubuntu image +- name: co/bundler + color: d9ead3 + description: Issues relating to Bundler +- name: co/cargo + color: d9ead3 + description: Issues relating to Cargo +- name: co/npm + color: d9ead3 + description: Issues relating to Npm +- name: co/yarn + color: d9ead3 + description: Issues relating to Yarn +- name: co/pipenv + color: d9ead3 + description: Issues relating to Pipenv +- name: co/poetry + color: d9ead3 + description: Issues relating to Poetry + +# others +- name: good first issue + color: 7057ff + description: Denotes an issue ready for a new contributor, according to the "help wanted" guidelines. +- name: help wanted + color: 006b75 + description: Denotes an issue that needs help from a contributor. Must meet "help wanted" guidelines.