How to Evaluate and Write Feature Requests

A feature request proposes a change to what the software can do. A useful request explains the user problem, affected workflow, alternatives tried, expected benefit, scope, tradeoffs, and whether the requester can help.

For maintainers, a good feature request is not a promise to implement. It is evidence for deciding whether the idea fits the project, belongs on the roadmap, needs more design work, or should be declined.

Feature request or bug report

A bug report says existing behavior is failing. A feature request asks for new behavior, a changed workflow, broader compatibility, an option, an integration, or a different default.

The boundary is not always obvious. If documentation says a file type is supported and it fails, that is likely a bug. If a user wants support for a new file type, that is a feature request. If an older version behaved differently, the report may be a regression bug or a deliberate product change.

When in doubt, describe the expectation and why you had it. Maintainers can then relabel the issue without losing the useful context.

Start with the user problem

Strong feature requests begin with the problem, not the implementation. "Teams need to export project data for offline review" gives maintainers more room than "Add a button that creates this exact spreadsheet format."

The problem statement should identify:

• who is affected;
• what task they are trying to complete;
• what blocks them today;
• why existing workarounds are not enough;
• what happens if the request is not implemented.

Implementation ideas are still welcome when they are clearly labeled as suggestions. The maintainer may know a simpler path, a safer design, or a reason the proposed implementation conflicts with existing architecture.

Include scope and acceptance criteria

Scope prevents a feature request from becoming an endless idea thread. Describe the smallest useful version of the feature and any limits that would still solve the problem.

Acceptance criteria help maintainers and contributors know when the request is complete. They can be simple: "Import files up to 100 MB," "Preserve headings and links," "Work on Linux and Windows," or "Document the new option in the settings page."

Avoid writing a full product specification unless the project asks for it. Open source maintainers often need enough detail to judge fit, not a rigid design they must adopt unchanged.

Show alternatives and tradeoffs

Feature requests are stronger when they show what the requester already tried. Alternatives may include existing settings, plugins, scripts, export paths, command-line flags, or external tools.

Tradeoffs matter because every feature has a maintenance cost. A new option can complicate testing. A new integration can add dependency risk. A new file format can require long-term compatibility work. A new default can help some users and disrupt others.

Naming those tradeoffs makes the request easier to evaluate. It also shows maintainers that the request is about project fit, not only personal preference.

User template

Use this template when a project does not provide one:

1. Problem: what workflow is blocked or harder than it needs to be?
2. Users affected: who benefits, and how often?
3. Current workaround: what do people do today?
4. Requested outcome: what should become possible?
5. Scope: what is the smallest useful version?
6. Tradeoffs: what compatibility, settings, documentation, or maintenance cost might change?
7. Contribution: can you test, document, design, or implement part of it?

The expected outcome is a focused discussion. If maintainers need more information, they should be able to ask about one missing detail instead of rebuilding the whole request from scratch.

Maintainer evaluation

Maintainers can evaluate requests with the same criteria each time:

This evaluation does not need to be formal. It gives maintainers a consistent way to accept, defer, redirect, or decline requests.

Roadmap and milestone fit

Accepted feature requests still need prioritization. A feature may fit the project but not the next release. It may need design discussion, a prototype, test coverage, documentation, or a contributor before it can move.

Link accepted requests to roadmap themes or milestones only when they are genuinely part of planned work. If a request is interesting but not scheduled, use labels such as needs design, help wanted, future, or under discussion.

The important distinction is honesty. Users can handle uncertainty better than vague optimism that never turns into a release.

Decline or defer clearly

Declining a feature request is part of maintaining scope. A short, clear reason is better than leaving an issue open indefinitely.

Common reasons include project scope, maintenance burden, compatibility risk, security or privacy concerns, lack of maintainer capacity, unresolved design questions, or overlap with existing behavior.

When possible, offer a next step: a plugin approach, documentation improvement, design discussion, third-party extension, or a smaller version of the request. Do not create a workaround when there is no realistic path.

Weak and useful requests

A useful request does not guarantee acceptance. It gives maintainers the information needed to make a responsible decision.