Document an issue triage workflow for the repository

.github/ISSUE_TEMPLATE/blank.yaml

@@ -0,0 +1,15 @@
+name: Blank issue
+description: Create a new issue from scratch
+labels: ["needs-triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for opening an issue for Grafana Alloy.
+
+        Please do not use GitHub issues for support questions. If you need help or support, ask a question on [Grafana Community](https://community.grafana.com/c/grafana-alloy) or join the `#alloy` channel on the [Grafana Slack](https://slack.grafana.com/).
+  - type: textarea
+    attributes:
+      label: Add a description
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/bug_report.yaml

@@ -1,6 +1,6 @@
 name: Bug report
 description: Create a report to help us improve Grafana Alloy.
-labels: ["bug"]
+labels: ["bug", "needs-triage"]
 body:
   - type: markdown
     attributes:

.github/ISSUE_TEMPLATE/community_component_proposal.yaml

@@ -1,6 +1,6 @@
 name: Community component proposal
 description: Propose a new community component.
-labels: ["community-component", "proposal"]
+labels: ["community-component", "proposal", "needs-triage"]
 body:
   - type: markdown
     attributes:

.github/ISSUE_TEMPLATE/config.yml

@@ -1,6 +1,6 @@
 # NOTE(rfratto): this file *must* have the .yml extension otherwise GitHub doesn't
 # recognize it.
-blank_issues_enabled: true
+blank_issues_enabled: false
 contact_links:
   - name: Grafana Alloy community support
     url: https://community.grafana.com/c/grafana-alloy

.github/ISSUE_TEMPLATE/docs.yaml

@@ -1,7 +1,7 @@
 name: Documentation feedback
 description: Give feedback on the Grafana Alloy documentation.
 title: "Docs feedback: "
-labels: ["type/docs"]
+labels: ["type/docs", "needs-triage"]
 body:
   - type: input
     id: url

.github/ISSUE_TEMPLATE/feature_request.yaml

@@ -1,6 +1,6 @@
 name: Feature request
 description: Suggest an idea to be added to Grafana Alloy.
-labels: ["enhancement"]
+labels: ["enhancement", "needs-triage"]
 body:
   - type: markdown
     attributes:

.github/ISSUE_TEMPLATE/proposal.yaml

@@ -1,6 +1,6 @@
 name: Proposal
 description: Propose a way to solve a problem.
-labels: ["proposal"]
+labels: ["proposal", "needs-triage"]
 body:
   - type: markdown
     attributes:

.github/workflows/generate-component-labels.yml

@@ -0,0 +1,24 @@
+name: 'Generate component labels'
+on:
+  push:
+    branches: [main]
+    paths:
+      - ./.github/workflows/generate-component-labels.yml
+      - ./.github/workflows/scripts/generate-component-labels.sh
+      # TODO - be more precise and only run if a new component readme file is created, this will also run on modifications
+      - './docs/sources/reference/components/**/*.md'
+      - '!./docs/sources/reference/components/**/_index.md'
+    workflow_dispatch:
+
+jobs:
+  generate-component-labels:
+    runs-on: ubuntu-24.04
+    if: ${{ github.repository_owner == 'grafana' }}
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+
+      - name: Generate component labels
+        run: ./.github/workflows/scripts/generate-component-labels.sh
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+

.github/workflows/needs-attention.yml

@@ -12,7 +12,7 @@ jobs:
     steps:
       - uses: actions/stale@5bef64f19d7facfb25b37b414482c7164d639639 # v9.1.0
         with:
-          days-before-stale: 30
+          days-before-stale: 90
           days-before-close: -1 # never close automatically
           stale-issue-message: >
             This issue has not had any activity in the past 30 days, so the

.github/workflows/scripts/generate-component-labels.sh

@@ -0,0 +1,39 @@
+# If run on OSX, default bash < 4 and does not support declare -A
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+declare -A COLORS
+
+COLORS["beyla"]="#483C32"
+COLORS["database_observability"]="#6666FF"
+COLORS["discovery"]="#1A8CFF"
+COLORS["faro"]="#50C878"
+COLORS["local"]="#FF794D"
+COLORS["loki"]="#B30059"
+COLORS["mimir"]="#F9DE22"
+COLORS["otelcol"]="#800080"
+COLORS["prometheus"]="#E91B7B"
+COLORS["pyroscope"]="#336600"
+COLORS["remote"]="#4B5320"
+
+FALLBACK_COLOR="#999999"
+
+for README in $(find ./docs/sources/reference/components -name '*.md' -and -not -name '*index.md' -print0); do
+    # The find ends up with an empty string in some OSes
+    if [[ -z "${README}" ]]; then
+        continue
+    fi
+    FILENAME=${README##*/}
+    LABEL_NAME="${FILENAME%.*}"
+    TYPE=$(echo "${LABEL_NAME}" | cut -f1 -d '.' )
+
+    if (( "${#LABEL_NAME}" > 50 )); then
+        echo "'${LABEL_NAME}' exceeds GitHubs 50-character limit on labels, skipping"
+        continue
+    fi
+
+    echo "Creating label '${LABEL_NAME}' for file with color ${COLORS["${TYPE}"]:-${FALLBACK_COLOR}}"
+    gh label create "${LABEL_NAME}" -c "${COLORS["${TYPE}"]:-${FALLBACK_COLOR}}" --force
+done
+

docs/developer/issue-triage.md

@@ -0,0 +1,72 @@
+# Managing issues
+
+We value community engagement with Alloy and want to encourage community members and all users to contribute to Alloy's
+development by raising issues for bugs, feature requests, proposals, and more. To ensure that issues are appropriately
+reviewed and users get the feedback they desire we have a few patterns for issue triaging.
+
+## Issue triage process
+
+Issues that are created in the Alloy repository should all begin with the `needs-triage` label.
+They may also start with other labels like `type/docs`, `proposal`, or `bug` depending on the template selected.
+
+The goal of the triage process is to collect enough information to move the issue into the right category or categories
+where it can then be most easily tracked to completion. The triage process might include asking clarifying questions of the author,
+researching the behavior of Alloy or other technologies relevant to the issue, and reproducing an issue in a test environment.
+
+### Issue states and labels
+
+After an effort has been made to triage an issue, the issue should be in one of several states
+
+* Waiting for author
+  * An issue might be waiting on more feedback from its author if
+    * There was insuffucient information available to reproduce the issue
+    * There was insufficient information available to fully define the feature requested
+    * An answer to the author's problem was proposed using existing functionality
+  * These issues should be tagged `waiting-for-author` in addition to any other categorizing tags (`bug`, `enhancement`, etc)
+* Waiting for codeowner
+  * Some issues related to community components within Alloy will be dependent on the community maintainer of the component, and other issues may be dependent on codeowners of components that are not maintained by additional teams within Grafana (beyla, pyroscope, database_observability)
+  * These issues should be tagged `waiting-for-codeowner` in addition to any other triage that is initially possible
+  * These issues should retain the `needs-triage` label until the codeowner has responded
+* Ready to implement/fix/document
+  * An issue is ready to implement or fix if the scope is well understood, and if it is an issue it should be replicatable
+  * These issues should be tagged `bug`, `enhancement`, `type/docs`, or `flaky-test`
+  * If the issue should be in the next release, it should be tagged `release-blocker`
+  * If an attempt is being made to internally prioritize the issue at Grafana, it should be tagged `backlog`. If there is a time or release commitment associated with this decision it should be in a comment on the issue.
+  * If the issue is a good candidate for a first time contributor or another interested community member, it should be tagged `good first issue`
+  * If the issue is a good candidate for a larger investment by an interested community member, it should be tagged `help wanted`
+  * *These issues should no longer have the `needs-triage` label*
+* Closed
+  * An issue might be closed after triage if
+    * a solution was offered, the issue was labelled `waiting-for-author`, and the author confirmed their need was met
+    * there is an existing duplicate issue with sufficient context to resolve the issue
+    * the issue was already solved (there should be a duplicate closed issue in most cases, link to it)
+    * based on discussion, the issue should be re-opened as a new `proposal` based on concensus in the issue comments
+  * It's unlikely an issue will be closed after first triage, unless it doesn't meet community standards.
+
+### Stale issues
+
+The `needs-attention` label is applied to issues that are seen as stale in a github action.
+This includes issues that have not been interacted with in 90 days.
+Issues with the `needs-attention` label may be closed if they are not in an actionable state.  
+
+The `keepalive` label can be applied to exempt an issue or pull request from being marked as stale.
+
+### Additional labels
+
+There are a variety of other labels that can be applied to issues and pull requests to help provide context to the issue. Wherever possible, relevant labels should be applied.
+
+* The `component-request` label can help identify requests for new components.
+* The `os:windows` should be used when changes are relevant to the Windows OS.
+Adding the label to a pull request will trigger the full suite of tests on Windows on a pull request.
+At this time there are no other OS-based labels.
+* There are various `dependencies` and language (`go`, `javascript`, etc) labels that may be applied by bots.
+* Component labels like `prometheus.remote_write` should be applied whenever possible. These labels should all be generated (but not automatically applied) by a github action.
+* The `v2.0-breaking-change` label may be applied if the issue represents a breaking change that will need to be delayed until Alloy v2.x.
+
+## Community Members
+
+Community members and other interested parties are welcome to help triage issues by investigating the root cause of bugs, adding input for
+features they would like to see, or participating in design discussions.
+
+If you are looking to contribute a pull request for an issue that has been triaged, please comment on the issue and request
+it to be assigned to you! A maintainer will set the assignment when they are able.