Feature requests and bug reports

Hello, Community!
We haven't had clear guidelines on when and how to create suitable tasks in our Phorge development portal for a long time. As the community grows, we need such guidelines more and more to ensure that tasks get resolved. We are also changing our policy of never closing tasks for inactivity, although we will still close them only under particular and limited circumstances.

Our task tracker has always been full of open tasks. One of the things we find appalling is open-source projects that try to keep the number of open tasks low at all costs and automatically close all tasks if there is no activity in a certain period. I've seen projects where that period was as short as two weeks. The effect is that if someone puts a lot of effort and time into creating a detailed reproducing procedure for a tricky bug and diagnosing its cause but project maintainers neglect to look at it in time, the system closes the task and pretends that the problem never existed — that is highly disrespectful towards community members who are doing their best to improve the project.

Early on, we did not close any task until it was resolved. In the early days, long-standing tasks were widespread because many features were impossible to implement in the legacy code, and that code had to be rewritten entirely first. We still close tasks from the low hundreds now that almost all of the legacy code is gone, and the path to those improvements is finally unblocked.

However, it's also essential to keep task tracker entries actionable. There are two main ways people use the task tracker. The main question for the maintainers' team and community contributors is, "What can I work on now?". For end users, it's usually either "Does anyone have the same problem?" or "Does anyone also want the feature I want?".

We developed a set of guidelines that will hopefully make it easier to answer those questions.

Feature request guidelines

You must create a task before you start working on a feature. Yes, even if it's a tiny feature — we use the task tracker to generate release notes, so everything must be reflected there.

You must include at least the following:

• A reasonably detailed description of the feature: what it is, how it's supposed to work, and how you'd use it. The maintainers aren't familiar with every feature of every protocol and tool, and community contributors who are looking for tasks to work on will also appreciate more information that helps them implement and test a feature.
• Proposed CLI syntax if the feature requires new commands. Please include both configuration and operational mode commands if both are needed.

You should include the following information:

• Is the feature supposed by the underlying component (FreeRangeRouting, nftables, Kea...) already?
• How do you configure it by hand there?
• Are there any limitations (hardware support, resource usage)?
• Are there any adverse or non-obvious interactions with other features? Should it be mutually exclusive with anything?

It's okay if you cannot provide some of that information, but if you can, it makes the work of developers considerably more straightforward, so try to research to answer those questions.

Bug report guidelines

When you create a bug, the most important thing is that it should be possible to tell if it's fixed.

You should include the following information:

• A sequence of configuration commands or a complete configuration file is required to recreate a setup where the bug occurs. Please avoid partial configs: a sequence of commands is easy to paste into the console, a complete config is easy to load in a VM, and a partial config is neither! At least not until we implement a "merge from the CLI" feature that allows pasting config file chunks into a session.
• The behavior you expect and how it's different from the behavior you observe. Don't just include command outputs or traffic dumps — try to explain at least briefly why they are wrong and what they should be.
• A sequence of actions that triggers the bug. We understand it's not always possible, but it makes the developer's job much more manageable. Also, it allows any community member to independently confirm whether the bug still exists or has already been fixed.
• If it's a regression, tell us a VyOS version where the feature still worked correctly. It's perfect if you can tell exactly which version broke it, but we understand it's not always easy or feasible — any working version is acceptable.

If you aren't sure what the correct behavior is and if what you see is really a bug, or if you don't have a reproducing procedure that reliably triggers it, please create a post on the forum or ask in the chat first — or, if you have a subscription, create a support ticket. Our team and community members can help you identify and work around the bug and create an actionable and testable bug report.

Task auto-closing

We recently added a new task status: "Needs reporter action." We will assign that status to the following:

• Feature requests that do not include required information and need clarification.
• Bug reports that lack reproducing procedures.
• Tasks implemented and tested by the implementation author but require testing in the real-world environment that only the reporter can replicate (e.g., hardware we do not have, specific network conditions...).

This is what will happen when a task is set to "Needs reporter action":

• If there is no response from the reporter within two weeks, the task bot will add a comment ("Any news?") to remind the reporter to reply.
• The task will be automatically closed if there is no response after two weeks.

We will not auto-close tasks with any other status or close tasks for the lack of maintainer activity!

Conclusion

You can find a permanent version of these guidelines in the development portal itself and in the documentation. We hope these guidelines help keep the task tracker clean and actionable.

If you have any ideas on how to improve them, tell us!

Thank you for your participation!