Skip to content

Latest commit

 

History

History
153 lines (103 loc) · 16.5 KB

CONTRIBUTING.md

File metadata and controls

153 lines (103 loc) · 16.5 KB
Raw

✨ Welcome

Thank you for your interest in Openverse! We're so excited to bring new contributors into the fold in WordPress, Openverse and FOSS in general.

❤️ Code of Conduct

Please be aware that as a project of the WordPress Foundation, Openverse follows the WordPress Etiquette, a code of conduct that you should read and agree to abide by before contributing to WordPress projects. This applies to all Openverse respositories.

🎨 Design contributions

How to contribute with 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 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 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.

📖 Translation contributions

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

☁️ Provider contributions

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.

💻️ Code contributions

⛳️ How to contribute with code

Any issues labeled as "good first issue" or "help wanted" in our repositories are all up for grabs. Just add a comment with @WordPress/openverse-maintainers on the issue with questions or requesting the issue be assigned to you when you're ready to work on it. We also regularly discuss Openverse development issues outside the meeting times (like debugging problems we're having while working through an issue).

⛺ Keeping in Touch

For folks who'd like to be involved in our regular development conversations, please feel free to join us in the WordPress make chat (https://make.wordpress.org/chat/). You'll find us in the #openverse channel, of course! We have weekly community meetings to discuss ongoing work and assign new issues and, every four weeks, a prioritization meeting to review our current projects and roadmap. The sessions are on Tuesdays at 15:00 UTC (https://everytimezone.com/s/d1d42c7b) and all are welcome! Attendance is not mandatory to contribute, however.

You can also keep in touch with progress and the latest updates to the project with our WordPress contributor group.

🎯 Choosing an issue

Below is a link to a list of issues that encompass a variety of different technologies, from Airflow to Django to GitHub Actions to Vue.js. You're welcome to take on any of the issues. Most require development environment set up, but some do not. Expect development environment set up to take 1 to 2 hours depending on experience and how much software you've already got installed. If you have git, a text editor/IDE, Python or Node and Docker set up, things will go a little more smoothly. If not, that's totally fine! We're here to help and our repositories all have README files that should include helpful instructions for self-guided environment set up.

Once you've picked an issue to work on, please leave a comment saying so on the issue and include @openverse-maintainers in the comment. That way one of us will get a notification and can assign the issue to you.

🤓 Initial set up

🪟 Note for Windows users

Windows Subsystem for Linux can be a much more versatile and familiar environment for software development on Windows. Everything from installing git and other dependencies to using command line tools that will be familiar to the wider community of software developers are more likely to be easier under WSL. While some parts of some Openverse projects may be able to be developed under native Windows, you will have a much smoother time with WSL as our command runners (just and pnpm) assume a unix-type environment (Linux and macOS). We would like to support native Windows development, but we do not currently have any active contributors who use Windows on a daily basis and do not have the time to spend supporting it. Likewise, many other OSS projects will not be configured to allow easy local development under Windows. WSL can help there as well.

Installation instructions for WSL on Windows 10 and 11 can be found here on Microsoft's official documentation website.

Of course, if you would like to contribute to Openverse by making our projects work natively on Windows, PRs for this are always welcome.

✍️ General set up

Skip any steps you've already completed on your own. This is meant as an exhaustive list for brand-new devs who might not have these tools yet.

  1. Install git
    • Most Linux distributions and macOS will already have this installed. Open up your terminal app and type which git. If the response is anything other than git not found then you've already got it installed.
    • If you need to install it, follow the official instructions here: https://git-scm.com/downloads
  2. Install a text editor.
    • VSCode is an option with good out-of-the-box support for our entire stack.
    • PyCharm is another very popular option with lots of bells and whistles.
    • Sublime Text is a minimalistic option that can get you off the ground quickly with lots of room for expansion through it's package system.
    • vim and emacs are ubiquitous terminal-based options.
  3. Create a GitHub account https://github.com/signup
  4. Install pyenv or Anaconda
  5. Install volta
    • Similar to pyenv/Anaconda but for Node.js
    • Skip this if you only want to do a Python issue
    • https://volta.sh/
  6. Install Docker
  7. Choose an issue from the list below and add a comment as described in the second paragraph of the "Choosing an issue" section above
  8. Fork the repository for the issue you chose
    • Go to the repository page on GitHub and find the "Fork" button in the upper corner of the page. Click this and GitHub will guide you through the process of forking the repository
  9. Clone the repository into your computer
    • On the page for your fork, find the "<> Code" dropdown button. Click it and copy the link provided under the "Local" tab of the dropdown.
    • Open up your terminal app and type git clone <copied URL> replacing <copied URL> with the URL you copied from the GitHub website.
  10. Follow the environment set up instructions in the README or CONTRIBUTING document in the repository
  11. Start working on the issue you chose 🎉

🏃 Good first issues

Most of these issues are potentially able to be completed in less than 4 hours, development environment set up included. It may take significantly more or less than 4 hours depending on experience and how smoothly development environment set up goes. Unfortunately sometimes dev env set up can sometimes be tricky! In these cases it would be helpful to the Openverse project to share your experience in an issue so we can try to remove any roadblocks for future contributors. You can make meaningful contributions to the project in the form of valuable feedback about the development experience!

List of Good First Issues

🤗 Friendly note for new comers

  1. It is totally ok and even encouraged to do more than one "good first issue"
  2. All are welcome to write issues and the Openverse maintainers have deep gratitude for those who do. If you see something that could be worked on, each repository has a set of issue templates to help you get started writing issues:
  3. 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.
  4. Don't hesitate to ask for help! In WordPress Make Slack or in a draft PR, if you're stuck, we're here for you. Everyone is learning and thinking things through all the time. Each Openverse repository has an @ alias you can ping for help in any issue or pull request, draft or otherwise:
    • @WordPress/openverse-api
    • @WordPress/openverse-catalog
    • @WordPress/openverse-frontend
    • etc.
  5. On the technical side, there are a ton of just recipes to help you out. If you run just on its own in any Openverse repository, it will show you what recipes are available and what they do. just lint, just test, just recreate, we all run these so frequently! 
    # Run `just` in any of the Openverse repositories to see a list of available commands.
# This example is for the `WordPress/openverse` repository.
> just
Available recipes:
    default   # Show all available recipes
    install   # Install Python dependencies in Pipenv environments and JS dependencies
    precommit # Setup pre-commit as a Git hook
    lint      # Run pre-commit to lint and reformat all files

🏔️ Other non-code contributions

There are a number of other ways to contribute to the project that don't involve writing Python or Javascript.

📑 Text improvements

Our documentation and copy text could always use improvement! The following links can be useful for finding text issues to tackle:

🩹 Bug reproduction & triage

Openverse has a large list of open bugs: all issues with the label "goal: fix". In many cases these bugs can be out of date, or their reproduction criteria may no longer be accurate. It's 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.

🫱🏿‍🫲🏽 Recruit

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.