This URL is filing a useful newcomer bug or feature report: search first, then reproduction, expected vs actual, versions, and a title a maintainer can scan. It is not how to claim a GitHub issue — that page is the one comment after the ticket already exists. It is not how to pick an issue that will get merged — that is choosing someone else’s ticket. It is not the pull request description — that is the text on a PR you already opened.

You are opening a new issue. The job is to make the next person able to reproduce or refuse the request without a ten-comment scavenger hunt.

Search first, then open New issue

GitHub search on the repo is the first five minutes. Query the error string, the CLI flag, the page title. Filter open issues. Filter closed issues. Duplicate reports get closed with a pointer; yours does not need to be the third copy of the same panic.

If you find an open ticket that already names the same failure, stop. Comment there with extra repro detail if you have it. Do not open a twin. Claiming that existing thread is how to claim a GitHub issue, not this page.

If the closed duplicate was “won’t fix” or “works as designed,” read why. Opening the same request with a friendlier title does not change the design.

Check ISSUE_TEMPLATE, .github/ISSUE_TEMPLATE/, and CONTRIBUTING.md. GitHub may force a Bug vs Feature form. Fill that form. Do not paste a second template from a blog. Empty headings look like you skipped the project.

Project rules, branch names, and the code of conduct live in contribution guidelines and the code of conduct. The issue body is not a second CONTRIBUTING.md.

Title: name the failure, not “bug”

One line. Name the behavior or the missing piece.

Bad: bug, help, doesn't work, feature request, please add.

Better:

CLI exits 1 when config.yaml is empty
Docs install page omits the retry flag
Save button has no accessible name in the settings dialog

The title is the inbox line. Repeat the error string if it is unique. Do not stamp good-first-issue or your username on it. Labels are for maintainers. Do not put Closes #12 in an issue title; that keyword belongs on a pull request.

Keep it under about 70 characters when you can. If the form has a title field, that field is the title. Do not write a second title in the first paragraph of the body.

Body: repro, expected, actual, versions

Four blocks. Short. If the template already has these headings, fill them. Do not delete them.

What I did. Numbered steps a stranger can follow on a clean checkout. Commands, URLs, clicks. Do not write “as above” and paste a screenshot of a terminal you did not transcribe.

What I expected. The documented or reasonable outcome. Quote the docs sentence or the previous version’s behavior. “It should work” is not expected.

What actually happened. The error, the wrong screen, the silent no-op. Paste the last 20–40 lines of the log, not the whole CI artifact. Redact tokens. Keep the stack frames that name this repo’s files.

Versions. OS, runtime, the project’s version or commit SHA, the browser if this is UI. “Latest” is not a version. If you built from main, paste git rev-parse HEAD.

A feature request still needs a concrete shape: the user action, the missing control or API, and why the existing path is not enough. “Would be nice” is a wishlist. Maintainers close wishlists. If you cannot name one screen or one function, you are not ready to file.

Screenshots belong when the bug is visual: a clipped button, a contrast fail, a layout break. A parser panic does not need a PNG of your editor.

What not to paste

Your resume. School, stack, “open to work.” The issue is a report, not a hiring thread.

A dump from a model. A generated essay, fake steps you did not run, a bullet list of “improvements” the project did not ask for. If you used a model to draft sentences, cut it to steps you can run again on a clean clone.

Secrets. API keys, .env files, session cookies, private URLs. Rotate anything you already pasted. Open a new issue if the first one leaked; do not edit-and-hope on a public thread.

A patch. If you already have a fix, open a pull request and put the report in the PR body, or file the issue and link the PR. Do not paste a 400-line diff into the issue and wait. How to write that PR text is how to write a pull request description.

Five problems. One report, one failure. A second bug is a second issue. Mixing a crash with a typo and a feature idea guarantees none of them get a clean close.

Feature requests: one user action

A useful feature issue names:

Who is stuck (CLI user, docs reader, maintainer running tests)
The action they cannot complete
The smallest change that would unblock them

It does not name a rewrite. It does not demand a milestone. It does not assign yourself unless the project asked you to. After it exists, if you want to implement it, pick whether it will get merged and then claim it.

If CONTRIBUTING says “discuss in Discussions first” or “RFC for new APIs,” follow that. Filing a GitHub issue against a project that moved design to a forum is noise.

After you click Submit

You wait. Do not @-mention every maintainer. Do not open a second issue “just checking.” Do not close and reopen to bump. If they ask for a log, paste the log. If they close as duplicate, take the link and stop arguing the number.

If they ask you to send a PR, that is a new job: first pull request guide. The issue you filed stays the spec. Do not silently expand the scope in the branch.

If nobody replies, the project may be quiet. Activity checks belong on how to tell if an open source project is active. Filing more issues does not wake a dead tracker.

Checklist before Submit

Searched open and closed issues for the same error or request
Used their issue template if GitHub showed one
Title names the failure or the missing action
Steps, expected, actual, versions are filled
No secrets, no resume, no second bug in the same body

That is the whole page: a report a stranger can act on. Claim, pick, and PR description are other URLs.