How to collect feedback for an open-source project

Issues and private feedback do different jobs

A GitHub issue is a public, technical conversation. It works for bugs that someone can reproduce and for proposals that contributors can discuss. It fails for everything else. Many users who love a project never open an issue, because they lack a GitHub account, they feel their question is too small or they do not want to argue in public.

Private feedback fills that gap. A short message such as "The setup guide skipped the environment variable" or "I wish the CLI printed the version" is worth reading even when it does not deserve a public thread. The maintainers can decide which items become issues, and they can reply without starting a debate in front of everyone.

Set the rule early and put it in the contributing guide. Bugs with steps to reproduce go to issues. Everything else can go to the feedback inbox, and a maintainer moves it to an issue if it needs code.

Put a widget on the docs site

Your documentation site is the best place for the widget, because readers hit problems there. Add the script to the site template, then set the allowed origins in product settings to the docs domain. Without that, the widget will not submit from the site.

<script src="https://escutaproduto.com/widget.js" data-key="pk_your_product_key" defer></script>

Most documentation generators let you add a line to a shared layout or a head include. The point is to load the script on every page, so a reader can report a confusing paragraph where they found it.

You can also add an explicit button to a page you want to highlight, such as the installation guide:

<button type="button" data-escuta-open="bug">Report a problem with this page</button>

The widget saves the page URL automatically, so the maintainer knows exactly which paragraph caused trouble. If the docs team wants a different look, use the data-color option to match the accent color of the site, and data-position to move the button away from the search bar.

Link the hosted form from the README and releases

The README cannot carry the widget, but it can link to the hosted feedback page. Add a line near the top or in the community section, such as "Questions or ideas that do not fit an issue? Send them here". The address looks like https://escutaproduto.com/f/your-product-slug.

Release notes are another good place for the link. Readers who just installed a new version are often the ones with the most useful opinions. A closing line such as "Tell us what you think of this release" works without any code, and the hosted page follows the reader's browser language.

Because the hosted page is not indexed by search engines, it stays out of search results, which suits a feedback form.

Hear from users who never open an issue

Private feedback shows you a different group of users. These are the people who run the project inside a company, who use it in a script they wrote last year, or who are new and do not yet know the contribution rules. Their messages are often vague, and that is fine. A vague message with a version number and a page URL is enough for a maintainer to ask one specific question.

Ask for an email address only when you plan to reply. Escuta Produto does not send email to people who submit feedback, so you reply from your own address, and you should say so in your privacy notice.

Review the inbox on a fixed schedule, such as once a week. Maintainers of popular projects can receive a lot of messages, and a weekly pass with clear statuses keeps the work sustainable. The article on the weekly feedback review gives you a short agenda you can copy.

Protect a public project from spam

A public form attracts spam, and open-source projects are targets. Escuta Produto protects the form in several layers. Allowed origins make sure the widget only submits from your sites. The form includes a hidden honeypot field that bots fill in and people never see. Rate limits cap submissions at 10 per minute per IP and product, and size limits reject oversized bodies. The form does not use a CAPTCHA, so real contributors never have to solve a puzzle to say thanks.

If spam gets through anyway, use the status "closed" for junk, add a short internal note and move on. Do not let spam shape your roadmap, and do not delete real messages to make the inbox look tidy.

Close the loop in public and in private

When a private message leads to a fix, say so where it helps the most. A changelog entry that mentions the report, or a comment on the linked issue, shows other users that the feedback led to a change. If the person left an email address, reply from your own mailbox with a short note.

Do not promise dates you cannot keep. A project with volunteer maintainers should say "we are looking at this" rather than "this ships next week". The article on telling customers their request shipped covers the wording for that kind of reply.

Set up Escuta Produto for your open-source project

Create a product for the project, copy the public key and add the docs domain to the allowed origins. Add the script to the docs layout, then send a test message from a page to confirm the page URL appears on the item. Link the hosted form from the README and the release notes.

Connect a Slack or Discord webhook for the maintainers, so a new message reaches the people who triage. The notifications guide explains the setup, and the widget reference lists every option. If your project ships a command-line tool, the developer tools article describes how to send feedback from a CLI, and feedback form spam protection explains the protections in more depth.