Issues for feature and bug tracking

[dcuccia]

I came to the repo today intending to catch up on the latest work, and perhaps propose some new work in the context of the project's roadmap and/or ongoing efforts. So, I clicked on "Issues", but saw only 4-year old tickets. This was a bit unexpected, as I expected a 1:1 mapping between Issues and PRs, and the ability to read through Issues as a statement of the up-front intent of a feature/bug. I thought I'd offer a suggestion on how, as an OSS developer, I would expect to be able to see and contribute to work, and hopefully it's helpful!

Based on my experience with GitHub (professionally and via OSS work), it's generally quite useful to have Issues be the "source of truth" for new work, and for Discussions before that be the progenitor for new ideas. Before something becomes promoted to an Issue, a Discussion item can be created to discuss a new idea. Then, a project lead can decide whether it should be promoted to an Issue at all (there is a hyperlink in a Discussion item to create an issue from a Discussion item). The creation of Items can be restricted to a specific person or group. Each Issue, then, is controlled/allowed by a project lead, and subsequently can have its own dedicated repository branch (which can be created by clicking a hyperlink within the Issue's page). That way:

1. there is context for what the new feature/bug fix will do
2. there is control over which items get "green-lit" for new work, and a tacit agreement that the manager agrees with the scope and approach
3. there is traceability to the work from Issue to code branch to PR, so everyone can see what happened to each idea (some get cancelled or redesigned or postponed)
4. there is an ability to break up work into multiple issues with links between them (automated "bread crumbs" are added between the tickets when another is referenced, so you have click-through navigation between them)
5. there is an ability for others "listening" to the project to propose ideas/tweaks that may be helpful, as a feature is being planned.

GitHub makes this workflow quite straightforward, so it doesn't add much organizational overhead. What the workflow adds, though, is a) the ability of outsiders to see and contribute effectively, and b) the ability of leads/managers to control the work that gets done. Even within a "closed" team, the ability to gate and track specific work items (and also to prioritize work and/or decide what not to work on yet) is immensely valuable.

There is a whole new "Projects" level of project management as well, but this Issues suggestion is a basic need building block that Projects could build upon someday when we were ready for that.

[lmalenfant]

Hi David,

Thank you for stopping by! I appreciate your feedback and yes, we do need to make improvements in this area.

We created the discussions here on GitHub but we still have our Google group and this is where most of the issues are posted:
https://groups.google.com/g/virtual-photonics

With such a small development team, most of our recent work has focused on unit test code coverage and code cleanup and this is ongoing. I can see where it would be beneficial posting our plans so other developers could join in. Up until now though we have had limited engagement by other developers, hopefully with your post, that is about to change. We will do anything we can to facilitate that process.

[dcuccia]

Fantastic! I hope only to submit ideas that could improve others ability to contribute, without adding too much unnecessary burden on the internal team, and I'm happy to be a guinea pig :).

If it's ok with you @lmalenfant, perhaps I can submit a few discussion items for "small" features/bugs/documentation additions that could be promoted to Issues/tickets (and worked on by me), and we could work our way through the process with a "trial balloon" effort? In parallel, with your permission, I might chime in on existing Issues that could/should be closed/postponed, so that we have good signal-to-noise?

[lmalenfant]

Yes! That would be great and yes we would love to be able to close some of the existing issues or update them so that they have the most current information. Just a heads up, we are currently working on our next release which will go out in the next few days. Once that is complete we will have more time to get things cleaned up in here.

[dcuccia]

Sounds great, thank you, will do!

[dcuccia]

I know this was closed, but just wanted to bump my thoughts above about workflow. Discussions are great to help hone an idea, link to (or inline) protoype code changes for discussion, and decide how narrow/broad an issue/ticket should be. Perhaps one effort/idea can be broken up into multiple tickets, for example. More importantly, perhaps the prioritization of that work/idea can be put in the context of a general roadmap of the project, where the ranking/ordering is based on impact to the stakeholders of the project. This last part (sometimes run by a "Product Manager" at a company, but generally applicable) is critical to make sure limited resources are being directed at the most relevant problems affecting the user and/or developer base (usually called Features and Tech Debt, respectively).