Proposal for Enhancing Issue Reporting in Openverse

[firatbezir]

Hello everyone,

As a contributor to Openverse, I've noticed that our repository has a very systematic way of starting a new issue. However, I believe we can make this process even more efficient and user-friendly, especially for those who are new to Openverse.

Problem

Currently, when an issue is raised, it doesn't necessarily contain the specific path of the necessary change to address the issue. This can make it difficult for contributors, particularly new ones, to locate where the changes need to be made.

Proposed Solution

I propose that we introduce a rule requiring issues to include the specific path where the change needs to be made. This would provide a clear direction for contributors and could potentially speed up the resolution of issues.

Additionally, if an issue comes from an end user and not from the developer team, it needs to be clearly addressed. If the issue lacks the necessary information, one of the team members will be notified to add the path.

I believe these changes could add practicality to our process and make our large repository more approachable for newcomers. I'd love to hear your thoughts on this proposal.

[sarayourfriend]

We've discussed something very similar in #2155

There are still two issues to complete that we made as a result of that discussion: https://github.com/WordPress/openverse/milestone/14

I'd encourage you to read that discussion and see if it addresses your concerns. To summarise the outcome, we decided that anything labelled "good first issue" should have clear implementation instructions, for this reason, so that contributors can work on them. Additionally, those issues should not have ambiguity, and should have appropriate technology labels, so that new contributors especially can identify issues they are interested in working on.

However, it's impractical to consider this for all issues or even the majority of issues, because solutions are not always known and often investigating the solution for an issue is 95% of the work, particularly for bugs. For issues coming from an implementation project, we often have good ideas for how to do things, but writing out the full instructions (a) takes a long time, so long that you often may as well have opened a PR to address the issue, and (b) introduces unnecessary rigidity in solutions.

For anything labelled "good first issue", it is agreed that we should have instructions for implementation. If the issue has any level of ambiguity, it should be just "help wanted", not "good first issue", assuming it's something that it's likely a contributor with an intermediate level of domain knowledge (rather than advanced) would be able to complete on their own or with only minimal assistance. Everything else is assumed to be sufficiently ambiguous in that we do not know the solution or in that it has multiple different potentially valid solutions that need to be tried and evaluated carefully by the implementer.

We may need better issue triage if there are lots of issues that could be "good first issue" but are not, I'm just not aware of that necessarily being an issue.

We can also communicate more clearly (not sure how) that anyone wishing to contribute to an issue that does not have a clear solution can propose one for discussion before attempting the issue, something like "I think this might work, what do the maintainers think". In fact, we all do this on a regular basis anyway, so it wouldn't be unusual to participate in such a discussion.

[firatbezir]

I am very glad this has been pointed out before this. I mainly meant this change for the new contributors. You're totally right about the impractibility of addressing this for all issues. It seems new contributors will move very comfortably when #2155 has been resolved. Thanks :)

[sarayourfriend]

Glad to hear that discussion is in line with what you were thinking. I'll close this one, but if you have anything to add to the issues in that milestone or nuances for the other discussion, please share anything you feel is relevant.

Thanks for thinking about how to improve the project and making this suggestion 🙏