Contributing to open source: what developers should know

Contributing to open source: what developers should know

Open source contributions can feel intimidating the first time, but they're one of the most rewarding ways to grow as a developer. Whether you're fixing a bug in a library your team uses daily or adding a feature to a project you admire, the process follows a predictable path that becomes second nature after your first pull request.

By day 55 of mastering Git and GitHub professionally, you've built solid fundamentals around commits, branches, and collaboration. This article walks you through your first open source contribution step by step—from finding the right project through handling reviewer feedback with grace.

Find a project — Look for good first issue labels

The hardest part of contributing is often deciding where to start. Browsing random repositories can waste hours. Instead, look for projects that explicitly welcome new contributors.

Most established open source projects tag beginner-friendly issues with labels like good first issue, beginner-friendly, help wanted, or first-timer-only. GitHub's "Explore" section and sites like goodfirstissue.dev and firsttimersonly.com aggregate these across thousands of projects.

Choose a project strategically. Early in your open source journey, prioritize:

• Projects you already use. You understand the pain points and have real-world context for your contribution.
• Active maintainers. Check the last commit date and recent issue responses. A project with activity in the last week is more likely to review your work promptly than one dormant for a year.
• Clear issue descriptions. A well-written issue tells you exactly what's needed. Vague issues often signal maintainers who won't respond quickly to your PR.
• Technologies you're comfortable with. Contributing to a Node.js project feels different from a Go or Python project. Match your strengths initially to build confidence.

Once you find an issue that resonates, read the comments. Someone might have already attempted a fix, and maintainers may have added context since the issue opened. If the issue is already being worked on, either ask if help is needed or move to the next one.

Read the guidelines — CONTRIBUTING.md and code of conduct

Before you write a single line of code, invest 10 minutes in reading the project's contribution guidelines. Most mature projects keep these in a CONTRIBUTING.md file at the repository root.

Here's what you'll typically find:

• Development setup. Exact commands to get the project running locally—Node version, environment variables, database setup.
• Branch naming conventions. Some projects want feature/thing-you-added, others prefer fix/issue-number.
• Commit message format. Conventional commits (feat:, fix:, docs:) are increasingly standard. A project might enforce fix: #123 description to auto-link commits to issues.
• Testing requirements. What percentage of test coverage is expected? Do you run tests before pushing? Is there a specific test framework?
• Code style and linting. ESLint config, prettier settings, naming conventions. Many projects run these automatically on pull requests.
• PR review process. Who reviews? How many approvals before merge? Are there automated checks (CI/CD pipelines) that must pass first?

Also read the CODE_OF_CONDUCT.md if it exists. It sets the tone for how the community interacts. Respectful, inclusive projects explicitly say so. Disagreements will happen in code review; the code of conduct tells you how they're handled.

A real example: React's CONTRIBUTING.md specifies that you should work from the main branch, follow their commit message format exactly, and all pull requests go through automated testing before a human reviewer even looks. Skipping this means your PR gets rejected immediately, wasting everyone's time.

Fork, branch, commit — Small focused changes with tests

Now you're ready to code. Create a fork of the repository by clicking the "Fork" button on GitHub. This gives you your own copy where you can push branches freely.

Clone your fork locally:

git clone https://github.com/your-username/project-name.git
cd project-name

Add the original repository as an upstream remote so you can stay synced:

git remote add upstream https://github.com/original-owner/project-name.git

Create a feature branch with a descriptive name. If you're fixing issue #456 about incorrect date formatting:

git fetch upstream
git checkout -b fix/456-date-format upstream/main

Now make your changes. Here's the critical part: keep your commits small and focused. If an issue asks you to fix date formatting, don't refactor the entire file or update dependencies. Stay in scope.

A good commit message for this scenario:

git commit -m "fix: #456 use locale-aware date formatting in user profile"

Write tests for your change. If the project has a test suite (most do), add or update tests that verify your fix works. In a Node.js project, this might look like:

// Before: test fails
test('should format date in user locale', () => {
  const date = new Date('2024-01-15');
  expect(formatUserDate(date, 'de-DE')).toBe('15.01.2024');
});

// After: you implement the fix, test passes
export function formatUserDate(date, locale) {
  return new Intl.DateTimeFormat(locale).format(date);
}

Run the test suite locally before pushing:

npm test

Confirm existing tests still pass and your new test passes. This is non-negotiable. A PR that breaks tests gets rejected immediately, regardless of how good the idea is.

Keep your branch ahead of the upstream main branch. If time passes between your fork and your PR, rebase to pick up new changes:

git fetch upstream
git rebase upstream/main

Push to your fork:

git push origin fix/456-date-format

Open a PR — Explain the change and respond to feedback patiently

After pushing, GitHub prompts you to open a pull request. Click that button. You'll see a template (many projects provide one). Fill it out completely.

A strong PR description includes:

• What. Concisely, what does this PR change?
• Why. Link to the issue number. Explain the problem you're solving.
• How. Briefly describe your approach. Don't paste code; say what you changed and why that approach works.
• Testing. What tests did you add or update? How did you verify this works locally?

Example PR description:

Fixes #456

The user profile date was always formatted in English regardless of user locale settings. This change uses the Intl.DateTimeFormat API to format dates according to the user's selected locale.

I've added a test case that verifies German locale formatting (de-DE) and confirmed the existing date formatting tests still pass locally.

Now comes the part that separates professionals from beginners: responding to feedback patiently. A maintainer will likely request changes. Comments like "can you add a comment explaining this?" or "this could break in edge case X, consider handling it" aren't criticism. They're maintainers protecting code quality.

Make requested changes on your branch and push again. The PR automatically updates:

git add .
git commit -m "fix: #456 add error handling for unsupported locales"
git push origin fix/456-date-format

Reply to each comment with context if needed ("I've updated the function to handle unsupported locales by falling back to en-US, as discussed in the thread"). This shows professionalism and keeps the conversation clear.

If feedback is critical (e.g., "we're reconsidering this approach"), ask clarifying questions respectfully. Sometimes a maintainer realizes mid-review that the issue itself was misunderstood. That's not your fault. Adapt gracefully.

Eventually, your PR gets approved and merged. A maintainer will typically squash your commits or merge as-is, depending on the project's workflow. Either way, you've successfully contributed to open source.

Common mistakes

Avoid these pitfalls your first time around:

• Skipping the CONTRIBUTING.md. You'll miss required test coverage, branch naming, or commit message formats. The PR gets rejected for procedural reasons, not code quality. Reading takes 10 minutes; reworking the entire PR takes 30.
• Making sweeping changes. The issue asks you to fix a bug, so you also refactor the module and update three dependencies. Maintainers want focused PRs that are easy to review and revert if needed. Big changes invite big debates.
• Getting defensive in code review. "This approach is fine" or "Other projects do it this way" doesn't work. Maintainers control the project. If they ask for changes, change respectfully. This is how you build a reputation as someone easy to work with.
• Writing tests after the fact. Or worse, not at all. Tests should be part of your solution from the start. They prove your fix works and prevent regressions.
• Pushing to main instead of your fork. If you're a new contributor, you shouldn't have write access to main anyway. Always push to your fork, then open a PR.
• Ignoring CI failures. GitHub Actions or Travis CI runs automatically on your PR. If tests fail, fix them before asking for review. A red build means reviewers won't even look at your code.

Key takeaways

• Find beginner-friendly issues on projects you already use or want to learn. Check that maintainers are actively responding.
• Read CONTRIBUTING.md and CODE_OF_CONDUCT.md fully before writing code. Setup time is never wasted.
• Keep commits small, focused, and well-tested. Stay in scope. Rebase to stay current with upstream.
• Write clear PR descriptions linking to issues. Explain your approach and testing strategy.
• Respond to feedback professionally and promptly. No defensiveness, just problem-solving.
• Your first contribution is about proving you can collaborate within the project's norms, not impressing with elegant code.