Practical advice for finding GitHub issues to work on

There is countless advice on finding projects and, eventually, GitHub Issues to work on, but it's mainly repeated content. I want to approach this with a new lens and focus on practical advice to make your next meaningful contribution to open source.

Though prevalent advice, never look for good first issues first. Instead, connect with people.

The best first contribution is saying "hello" in Discord. So for the sake of this guide, I'd recommend working on projects where you can chat with the maintainers and contributors. This cuts out a lot of noise and gets you focused on projects where you can get meaningful mentorship. Some small projects don't have discords and communities, and that's ok. I suggest focusing efforts on areas you can contribute, so if you are looking for projects to contribute, look at places with many active contributors and note what they are actively working on.

In OpenSauced, you can create a custom insight page for projects you want to connect to. Check out that guide here.

Practical Steps to Find Your Next Contribution

Now if you already have the context of the project and the community, you are in a great place to start contributing. For the rest of this article, we will focus on practical advice on finding what to work on next. For those who want to know the context up front, below are the contribution areas I will recommend:

1. Running the project locally
2. Improving the developer experience
3. Establishing Credibility by Enhancing Documentation
4. Considering performance & accessibility

For the sake of providing practical advice, my examples will use the Astro project, but you should choose a project you are interested in for this exercise.

Running the project locally

This is a crucial step for anyone making code contributions or updating documentation about how to run and use the project and is often overlooked. It is impressive to meet a vegan butcher, but that is the outlier, not the norm. Be normal and try using the project first. By running the project locally, you learn more about the project, experience, and any challenges or surprises you might face.

Make it a challenge to clone the project and run the test suite. Astro provides an "Open in Codespaces" button in the CONTRIBUTING.md, which gets there as fast as possible. If you get stuck or do not have context on a concept from that experience, find a person in the contributor community to share that context.

The core project can be daunting, which is fine as well. There are countless Astro examples that you can perform the same tasks in.

Improving the Developer Experience

By using the project you're more likely to be able to improve the developer experience. Find any and every way to use Astro in a side project and run through the examples in the docs guide section. Astro already has a great guide and tutorials section that has been developed after months of feedback from folks like you. But the thing there is that after months things change.

Try walking through the guides to gain knowledge about building an Astro project. If you learn something, share those insights with the community via DEV post. Your experience is unique, and it can be very hard to know what it's like learning a new technology the first time.

Very few beginner guides for projects exist because many beginners believe that experienced community members already possess their insights. But the beginner experience can only be shared once, making it the most valuable insight a new community member can provide.

Most maintainers need more time for community support as the project grows. Community support and triage is one of the best ways to level up and learn ways to improve the developer experience for the project.

Establishing Credibility by Enhancing Documentation

In the case of Astro, they have a docs site that includes instructions on how to use the project. There are two approaches to documentation that I'll cover here, documentation that improves how the information is shared and the necessary context provided and documentation that has to do with running and using the code.

If you're adding to or revising the documentation that doesn't require you to have knowledge of the codebase, make sure you provide a clear reason for the revision or introduction to new information in the documentation. The maintainer should be able to see from the issue your write or your Pull Request description, which this is an important update to the documentation.

For example, if you're reorganizing the documentation, provide a clear description of why the reorganization is necessary and will improve the developer experience.

If you're making a contribution, I strongly suggest using the project first. If you haven't used due to a lack of context limitation, consider leveling yourself with context through a conversation with a community member or contributor.

While using the project, note any unclear installation steps and weirdness in your environment. If you are running into errors, this is an opportunity to open an issue to confirm if this is isolated to you and your environment or impacting others.

Search the issues for existing conversations before opening any new issues. Read through merged pull requests to understand the project's history and why some decisions were made. This is a great way to learn who are the decision makers too.

Some issues regarding developer experience would be enhancements for the docs sites—one regarding improving Firebase Deploy.

Stop looking at large projects and starting in a place that needs your help even more, smaller projects. Starting in a smaller project's README will likely lead to you finding areas for providing value much faster than searching endlessly through open issues in a large project. Support the little projects with your time if you have it.

note: If you say you will do something, provide an update at the end of the week. If you can't complete it, unassign yourself and provide an update for why.

If you do not experience issues, that is great. There are several technologies that Astro works alongside, and only some cases are covered in the documentation. Using the technology will eventually lead to discovering issues and perhaps good first issues you can approach.

When writing this article, the Astro docs site has a recipe section, which includes instructions on how to deploy to various services. There is no section on how to deploy to Digital Ocean within that recipe section.

I'll leave this for the reader's exercise, but that would be where I'd start: building a project in Astro,
deploying the project to a production cloud host, and

leaving notes for the next person in a findable location-probably the documentation.

Considering performance & accessibility

Once you have established credibility through content and building with Astro, I'd consider a meaningful change. I recommend not trying to add any new features but instead showing you care by looking into ways to improve the project's performance and accessibility.

Astro has some integrations in accessibility and performance. Similar to the previous sections, the tool is the best way to understand.

This requires time and even gives you a deeper understanding of the project without adding any new libraries, audit pages, and boot speeds. Identify if the project meets all standards in its documentation pages. Be genuinely helpful in places most others overlook.

The goal here is to be intentional and not simply run a lighthouse audit with any practical or actionable advice. I suggest running an audit through an Astro example site or one you have built. Look for places for improvement where individuals learn how to use Astro.

The documentation also has a section on how to build Astro integrations. Integrations and add-ons are a great place to explore providing value. Often, these enhancements live outside the repo you are trying to contribute, which makes for a great place to experiment and find things to work on.

https://astro.build/integrations

Find an existing Astro example and leverage integration to identify areas of improvement by running a quick audit to provide that actionable insight.

That wraps up this guide, but let's continue. You should look for ways to make an impact in open source beyond the green square. Consider pledging 100 days to this path and check out the #100daysOfOSS.

If you have any other tips for how to start contributing. Leave a comment with them below.