|
| 1 | +# Writing a Good GitHub Issue |
| 2 | + |
| 3 | +Most issues that sit without a response for weeks aren't controversial or |
| 4 | +complex. They just don't have enough to get started. |
| 5 | + |
| 6 | +All issue activity is governed by the |
| 7 | +[OpenTelemetry Code of Conduct](../../code-of-conduct.md). |
| 8 | + |
| 9 | +## Table of Contents |
| 10 | + |
| 11 | +- [Before You Open an Issue](#before-you-open-an-issue) |
| 12 | +- [Writing the Issue](#writing-the-issue) |
| 13 | + - [Title](#title) |
| 14 | + - [Description](#description) |
| 15 | + - [Linking Related Issues](#linking-related-issues) |
| 16 | +- [Connecting Issues to Pull Requests](#connecting-issues-to-pull-requests) |
| 17 | +- [Labels](#labels) |
| 18 | +- [Signaling Intent to Work on an Issue](#signaling-intent-to-work-on-an-issue) |
| 19 | + |
| 20 | +## Before You Open an Issue |
| 21 | + |
| 22 | +Search first. Duplicate issues split the conversation and make it harder to |
| 23 | +track what's already been decided. If an existing issue covers what you're |
| 24 | +seeing, react to it to signal that it affects you and add any new details |
| 25 | +as a comment, rather than opening a duplicate. OpenTelemetry uses issue |
| 26 | +reactions to assess priority; see the |
| 27 | +[issue participation guide](https://opentelemetry.io/community/end-user/issue-participation/) |
| 28 | +for details. |
| 29 | + |
| 30 | +For support questions and "is this expected behavior" checks, use |
| 31 | +[Slack](https://cloud-native.slack.com/archives/CJFCJHG4Q). Issues are for |
| 32 | +bugs and feature requests. |
| 33 | + |
| 34 | +> [!CAUTION] |
| 35 | +> If you're reporting a security vulnerability, do NOT open a public issue. |
| 36 | +> Use the repository's security policy (the "Security" tab on the repo page) |
| 37 | +> to report it privately. |
| 38 | +
|
| 39 | +If your issue is about whether a behavior is correct per the OpenTelemetry specification, link to the relevant spec section. This is especially useful for cross-language consistency questions. |
| 40 | + |
| 41 | +## Writing the Issue |
| 42 | + |
| 43 | +If the repository uses issue templates and the template includes a footer, leave it in place. |
| 44 | + |
| 45 | +### Title |
| 46 | + |
| 47 | +Describe the problem, not your reaction to it. Be specific about what and |
| 48 | +where: |
| 49 | + |
| 50 | +- `Connection retries don't honor the configured backoff interval` |
| 51 | +- `API docs don't mention the maximum allowed payload size` |
| 52 | + |
| 53 | +Titles like "it's broken" or "docs are wrong" don't help triagers and make |
| 54 | +the issue impossible to find later. |
| 55 | + |
| 56 | +If the repo has a title convention (some use a `[component/name]` prefix, |
| 57 | +others don't), follow it. |
| 58 | + |
| 59 | +### Description |
| 60 | + |
| 61 | +Use the issue template if one is provided; it includes all the fields maintainers need. |
| 62 | + |
| 63 | +When creating an issue for a bug, include: |
| 64 | + |
| 65 | +- What you expected vs. what happened |
| 66 | +- Minimal reproduction steps, written as if the reader has never seen your setup. A minimal config that still triggers the issue beats a full production config with everything redacted |
| 67 | +- Log output and stack traces in code blocks, not screenshots, because text is searchable and copyable |
| 68 | +- SDK version, language runtime version, OS |
| 69 | +- Relevant configuration (exporter, propagator, sampler) |
| 70 | + |
| 71 | +When creating an issue for a feature request, include: |
| 72 | + |
| 73 | +- Problem/motivation |
| 74 | +- Proposed solution (optional) |
| 75 | +- Alternatives considered |
| 76 | + |
| 77 | +### Linking Related Issues |
| 78 | + |
| 79 | +If your issue is a follow-up to an existing issue or a Slack thread, say so |
| 80 | +near the top of the description. GitHub renders `#NNN` as a link within the |
| 81 | +same repository. For cross-repository references, use the full URL: |
| 82 | + |
| 83 | +``` |
| 84 | +This is a follow-up to #1234. |
| 85 | +
|
| 86 | +Related: https://github.com/<org>/<other-repo>/issues/1234 |
| 87 | +``` |
| 88 | + |
| 89 | +This one habit saves a lot of time reconstructing context later. |
| 90 | + |
| 91 | +## Connecting Issues to Pull Requests |
| 92 | + |
| 93 | +If your pull request fixes an issue, use one of GitHub's |
| 94 | +[closing keywords](https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/linking-a-pull-request-to-an-issue) |
| 95 | +in the PR description: |
| 96 | + |
| 97 | +``` |
| 98 | +Fixes #1234 |
| 99 | +``` |
| 100 | + |
| 101 | +When the PR merges into the default branch, GitHub closes the issue, and |
| 102 | +anyone who finds the issue later gets a direct link to the fix. |
| 103 | + |
| 104 | +If the PR is related to an issue but doesn't fully resolve it, use a plain |
| 105 | +mention instead: |
| 106 | + |
| 107 | +``` |
| 108 | +Part of #1234 |
| 109 | +``` |
| 110 | + |
| 111 | +That creates the cross-reference without triggering auto-close. |
| 112 | + |
| 113 | +## Labels |
| 114 | + |
| 115 | +You don't need to apply labels yourself. Triagers handle that. Knowing what |
| 116 | +the common ones mean helps you find work. |
| 117 | + |
| 118 | +| Label | What it means | |
| 119 | +|---|---| |
| 120 | +| `good first issue` | A good starting point for someone new to the codebase. Maintainers have agreed to help if you get stuck. Scope should be narrow and described clearly in the issue. | |
| 121 | +| `help wanted` | Contributions welcome. Usually needs more context than a good first issue. | |
| 122 | +| `bug` | Confirmed or suspected unintended behavior. | |
| 123 | +| `enhancement` | New capability, or an improvement to existing behavior. | |
| 124 | +| `question` | Needs clarification before anyone can act on it. You can also use the Discussion tab for this case. | |
| 125 | + |
| 126 | +If a `good first issue` turns out to be larger than it looked, say so in a |
| 127 | +comment. Maintainers can re-label it and help adjust the scope. |
| 128 | + |
| 129 | +## Signaling Intent to Work on an Issue |
| 130 | + |
| 131 | +Issues can only be assigned to org members and repository collaborators, |
| 132 | +because of how GitHub permissions work. If you want to take something on, |
| 133 | +leave a comment: |
| 134 | + |
| 135 | +> I'd like to work on this. I'll have a draft up by end of next week. |
| 136 | +
|
| 137 | +That's enough to claim it without blocking anyone. If you get stuck or can't |
| 138 | +continue, drop a note in the thread so others know it's available again. If you claim an issue and go quiet for 2–3 weeks, maintainers may reassign it. |
0 commit comments