Thank you for your interest in Openverse! We’re so excited to introduce new contributors to Openverse, WordPress and free and open-source software (FOSS) in general. This document is a set of guidelines to help you contribute to this project.
Code of Conduct#
You should read and agree to abide by the code of conduct before contributing to WordPress projects. This applies to all Openverse repositories because Openverse is a WordPress Foundation project.
Keep in touch#
Don’t hesitate to ask for help; if you’re stuck, we’re here for you! You can ping us via any of our communication channels.
If programming is not your cup of tea, there are ways to contribute to Openverse that do not involve working with code at all. Some of them are listed below.
If you’d like to contribute to the design, feel free to propose a solution to an existing problem labeled with Needs Design, or share an idea if you think it meets Openverse’s goals.
The WordPress Design team uses Figma to collaborate and share work for all WordPress projects. If you are not familiar with designing for WordPress, please carefully read the design handbook. Once you have a WordPress Slack account, join the #design channel and ask the team to set you up with a free Figma account.
This will give you access to all projects and files used in WordPress.
Before designing a proposal, browse the Design Library file to understand how Openverse has been built, and take a look at the created work to get a glance at how design ideas are made. As the design onboarding section in the design library file is constantly being added to and improved, some documentation may be missing. If you have doubts, ask on #design channel for clarification. If you discover new information that is yet to be documented, contributing this information back to the documentation is very much appreciated.
Once you are done and ready to share your idea,
create an issue with the
design label and fill in the template.
Please be as specific and concise as possible and feel free to add mockups,
prototypes, videos, sketches, and anything that makes your idea easier to
After creating the issue, it will be labeled with
aspect: design. Please
existing design issues
as a guide for how to describe your solution and to understand how the
discussion evolves before implementation begins.
You can also contribute to Openverse by translating it.
An overview of Openverse translations is here: https://translate.wordpress.org/projects/meta/openverse/
A getting started guide for translating on GlotPress (the software behind translate.wordpress.org) is here: https://make.wordpress.org/polyglots/handbook/translating/glotpress-translate-wordpress-org/#getting-started
Openverse is powered by upstream providers of openly licensed media. You can help expand Openverse by identifying sources of Creative Commons licensed media - we’re always looking to broaden our dataset.
You can use the New Source Suggestion for Openverse issue template to submit whatever sources you find.
Feedback like reporting bugs and missing features is big help for Openverse. We want Openverse to be a bug-free app with great user experience and providing feedback is a way to put any shortcomings on our radar and get them resolved.
You can report bugs, request features and see all other forms of feedback we would like to receive by submitting a new issue on GitHub. All are welcome to write issues and the Openverse maintainers have deep gratitude for those who do. Note that you will need a GitHub account to create new issues.
You can also provide feedback via any of our other communication channels.
If you know folks who have expertise in any of the above areas who you think might be interested in contributing to open source, send them our way! We’re happy to help onboard folks to the project itself, as well as the tools and technologies we use.
Issue backlog maintenance#
The Openverse issue backlog requires regular maintenance and upkeep. Issues can become stale or unworkable for a variety of reasons. For example, they can:
be duplicates of other issues
have been silently fixed
have been explicitly fixed but accidentally left open
require additional context before they can be worked on
refer to implementation details that are no longer relevant due to infrastructural or design changes
require changes in prioritisation
These conditions cannot be easily identified automatically and require regular, ongoing work from contributors. Additionally, important issues can be accidentally ignored due to the breadth of our backlog and it is critical for maintainers to dig through the oldest issues to ensure that issue prioritisation still makes sense.
The following sections give hints on how to manage certain common scenarios. Generally speaking, for any scenario where an issue is being closed, it is good to ping at least one other maintainer for advice or to corroborate your understanding of the situation. If you find issues that don’t seem right for any reason, ping any of the communication aliases and someone will help clear up any doubts.
Issues that need more information#
Issues may not have all the context required for them to be worked on. This can be caused by someone opening issues in a hurry, by the context around an issue changing over time, by outdated or broken links, and other myriad reasons. If you identify an issue that needs more context, there are two options:
You can research and add the context yourself. In this case, it is a good idea to ping the person who originally opened the issue or other folks discussing the issue to confirm that the additional information you’ve added is accurate.
If for any reason you do not have the ability to research the issue yourself, you should add the “ticket work required” label.
Building off the second option, the ticket work required label identifies issues that require research or explanation before they can be worked on. If you are able to clarify any of these issues, please do so and ping a relevant maintainer to confirm the changes and remove the ticket work required label.
Additionally, if you find issues that you’re able to contribute context towards such that they would be good candidates for “good first issue” or “help wanted”, please add those labels as well after you make your changes. This especially helps the new contributor experience as issues with clear instructions and good context are the most pleasant to work on when you first contribute to a project.
In the course of this work, you may find issues that should be closed because they are no longer valid. Please see the linked section for how to handle those issues and keep in mind the important caveat with regard to reproducibility covered in that section. See also bug reproduction reproduction and triage above.
Clicking through a few pages of the issue backlog and scanning titles can sometimes reveal issues that are either duplicative or so closely related that they could be merged into a single issue. When doing so, always close the newer issues and copy any relevant information from the newer issues into the older issues. The reason to keep the oldest issue open is to accurately reflect the age of the issue. This is especially relevant for bugs as if we closed the oldest issues in favour of the newest ones, we wouldn’t have accurate, easily queryable information about bug age.
If you identify issues that appear to be duplicates or closely related such that they should be fixed at the same time, ping the folks who opened or have discussed the issues to confirm that before merging the issues.
Closing no longer valid issues#
Issues may become invalid for many reasons. The most common are:
The issue refers to a feature which no longer exists. For example, a bug issue for an endpoint or a page that no longer exists or is deprecated
The issue is no longer reproducible, i.e., the issue identified has been fixed
The work is no longer desired, either because it is part of an abandoned project or because it contradicts other decisions that have been made since the issue was opened
In all of these cases it is important to ping the author of the issue and the people discussing it. For clarification on whether an issue is still desired, it is especially helpful to ping the communication alias relevant for the part of the stack in question. Please heed
Keep in mind that some issues may appear like they are no longer valid due to irreproducibility. Take care when approaching these issues to confirm absolutely that the environment reported in the issue (if one is reported) is not relevant. Always ping the original author of the issue to confirm irreproducibility before jumping to the conclusion that the issue should be closed. Additionally, after pinging the author of the issue, add the “ticket work required” label.
Openverse does not close issues strictly due to age. Issues should only be closed if they meet the criteria described above, not merely because they are old. Old issues should be treated following the prioritisation update guidelines described below.
Issues are often prioritised at the moment or within the week that they are opened. Therefore, the priority labels for issues must be considered relevant to their age. Issues opened with a medium or low priority are not necessarily issues that can go forever without being addressed. These prioritisations merely indicate issues that do not need to be immediately addressed. With that in mind, the oldest issues in our backlog, even if they have a low priority designation, should be re-evaluated on a regular basis to ensure that it doesn’t make sense to start implementing them. Old issues are often overlooked for a variety of reasons:
They don’t appear in our regular scans of the backlog because they’re on the final pages
They can sometimes be tricky or ambiguous issues and have been avoided by even by contributors who are looking through old issues in favour of more straight-forward ones
If you find an old issue that looks like it could be worked on, if you are sure that it can be immediately worked on, add it to the weekly dev chat agenda for prioritisation. Maintainers will discuss the issue and decide whether it should be assigned for the following week or if can continue to be delayed. Leave a comment on the issue if you add it to the agenda document. Alternatively, if you are unsure whether it makes sense to start working on the issue, ping the author or relevant communication alias for help making a decision.