Get started with contributions

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.

The documents below provide more exhaustive information about contributing beyond the basics.

• GitHub contribution practices
• Development workflow
• Current maintainers
• Communication aliases
• Becoming a Committer
• Regular maintainer tasks
• Codespell Configuration : spellcheck pre-commit hook
• Maintainer guidelines for “Good first” and “Help wanted” issues

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.

Code and code-related contributions

Get started

Detailed help for contributing code can be found in the developer documentation, which also includes the following subfolders.

The following resources are preferred reading for starting your Openverse contribution journey in the code and code-related space.

• GitHub contribution practices

• Dev flow

• General setup guide

Friendly notes

It’s totally acceptable to work on more than one “good first issue”.

On GitHub, you can ping us on any issue you would like to work on or triaging and on PRs that you’ve opened or are giving feedback on. You can ping a specific person using their GitHub handle, or even the entire Openverse team using @WordPress/openverse-maintainers.

Text and documentation

Our documentation and copy text could always use improvement. If you spot any scope for improvement, from the smallest punctuation error to the largest factual inaccuracy, you can file an issue or fix an already open one.

• Good first issues with the “📄 aspect: text” label

• Issues wanting help with the “📄 aspect: text” label

Bug reproduction & triage

Openverse has a large list of open bugs. In many cases these bugs can be out of date, or their reproduction criteria may no longer be accurate. It is useful information for maintainers to know whether the issue mentioned can still be reproduced on recent versions of the code or if the issue can no longer be replicated.

• Issues with the “🛠 goal: fix” label

See also the section below on issue backlog maintenance for related ways to help.

Pull request review

New contributors are welcome and invited to provide feedback on pull requests. You can start by just asking questions! It’s great to get to know the project and helps PR authors by uncovering unspoken or undocumented assumptions that exist about the project. It is frequently folks who know the least about and are newest to a project that ask the most helpful questions in this regard.

• Non-draft open PRs

Programming

Any issues labeled as “good first issue” or “help wanted” in our repositories are all up for grabs. Just add a comment tagging the maintainers using @WordPress/openverse-maintainers on the issue with questions or requesting the issue be assigned to you when you’re ready to work on it.

• Good first issues

• Issues wanting help

Non-code contributions

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.

Design

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 deeply 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 understand.

After creating the issue, it will be labeled with aspect: design. Please reference existing design issues as a guide for how to describe your solution and to understand how the discussion evolves before implementation begins.

Translations

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 https://translate.wordpress.org) is here: https://make.wordpress.org/polyglots/handbook/translating/glotpress-translate-wordpress-org/#getting-started

Providers

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.

Our currently list of providers which have been identified but are not yet being ingested can be found here.

You can use the New Source Suggestion for Openverse issue template to submit whatever sources you find.

Feedback

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.

Referrals

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.

Useful issue query links

• Ticket work required; see the section below for actionability

• Medium and low priority sorted by oldest first; see the section below for actionability

• All issues sorted by oldest first

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:

1. 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.

2. 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 and triage above.

Merging issues

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.

Warning

Reproducibility

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.

Updating prioritisation

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.