Table of Contents

Before diving in, make sure to check with the repo’s contribution guide (if they have one) —it’s like the OG roadmap for how to make an impact. This is your shot to connect with the team and even get some senior devs to notice your work.

Pro tip: many contributors land gigs just by being active and bringing their A-game. 🛠️

Leveling Up: Your First Issue

This is a general guide for working on your first issue in a repo, in case the repo doesn't have a guide of its own. Following these guidelines will help ensure that your pull request (PR) gets approved.

• Get the Lay of the Land

  Understand the repo’s architecture and what it’s all about. For example, if it’s about EIPs, make sure you’ve cracked the structure of EIPs before jumping in.

• Hunt your Issue

  Scope out the repo’s existing issues and zero in on the tags or labels. Keep an eye out for gems like:
  🚀 Scout Game
  🏷️ good first issue
  🙋‍♂️ help wanted
  Find an open issue that matches your skill set and proceed.

• Decode the Issue

  Read the reported issue and be crystal clear on what’s being asked.

• Get the Green Light

  Reach out to the repository maintainer to assign the issue to you.
  - Add a comment outlining your plan and timeline.
  - If someone is already assigned, check with the repo maintainer to make sure they are still working the issue.
  - Ensure no duplicate issues exist for the work you're planning.
  Once the issue is yours to solve, you are ready to dive in!

• Fork It, Clone It, Own It

  Fork the repo and clone your version locally. No write access to the main repo? No worries—that’s what forks are for.

• Recreate the Issue

  Run the code and replicate the behavior mentioned in the issue. Now you’re ready to troubleshoot.

• Ask Smart Questions

  Dive deep into the repo before pinging anyone, but don’t waste hours going in circles. Most of the time, just phrasing your question unlocks the answer.

• Brush Up on the Code

  If the language feels foreign, take a crash course. No shame in leveling up your toolkit.

• Test-Driven FTW

  Try writing a test first to confirm the bug exists. Once that’s locked in, go ahead and implement your fix.

• Wrap It Up

  - Add tests (if you haven’t already).
  - Write clean, concise documentation that vibes with the repo’s style.

• Submit a PR

  Link the issue, and explain your solution like a pro.

Stay consistent, and who knows—your next big gig might just slide into your DMs. 🚀

Submitting an Issue

Before Submitting an Issue

Confirm it’s legit.

• Reproduce the problem using the latest version of the software.

• Check the documentation—you might uncover the root cause and fix it yourself.

• Search existing issues in the project. If it’s already reported and still open, drop your insights in the comments instead of creating a new issue.

How to Submit a Solid Issue

Issues are how bugs get tracked, so be detailed to help maintainers troubleshoot faster. Here's the playbook:

• Nail the Basics

  - Write a clear, descriptive title that sums up the problem.
  - Lay out the exact steps to reproduce the issue. Include all the gritty details—commands, processes, or whatever triggered it.

• Show the Work

  - Provide specific examples: links, code snippets (formatted with ```), or anything that shows the problem in action.
  - Share screenshots or recordings that clearly demonstrate what’s happening.

• Describe the Situation

  - What happened? What’s the issue with that behavior?
  - What should have happened instead?

• Provide Context

  - Did this issue pop up recently (e.g., after an update), or has it always been there?
  - Can you replicate it in an older version? If so, what’s the last version where it worked fine?
  - How often does the issue occur? Under what conditions?

• Include Environment Details

  - Software Version: Which version are you using?
  - Operating System: Include the OS and version.
  - Virtualization: Are you in a VM? If yes, which software and versions for the host and guest?
  - Docker: If applicable, what’s your Docker version?
  - Cloud: Running on the cloud? Drop the provider and VM details (type/size).
  - Java Version: Share your Java version if it’s relevant.

• Label It

  Add relevant labels to categorize the issue.

By following this guide, you’ll make it easier for maintainers to solve the problem faster. 💡