First Open-Source Contribution: Portfolio Guide

Your first open-source contribution can show more than a line of code. It can demonstrate how you understand an unfamiliar codebase, communicate with maintainers, test a change, and explain your decisions. But choosing an issue that is too broad—or coding before you understand the project—can make the experience frustrating.

This guide walks Indian students and junior developers through selecting a manageable issue, reproducing it, making and testing a focused change, discussing it with maintainers, and documenting the work honestly for a portfolio. A contribution may not be merged, and it does not guarantee an interview or job. The process and the evidence you preserve are still valuable learning outcomes.

Key takeaways

Start with a project you can run and understand, not just an issue labeled “good first issue.”
Read the project’s contribution guide and issue discussion before changing code.
Reproduce the problem and record the steps and expected behavior.
Keep the change focused, add or update relevant tests, and follow the project’s review process.
Turn the work into a portfolio case study that distinguishes what you did from what the project accepted.

Choose a project before choosing an issue

Pick a project connected to a technology you already use or want to learn. A small library, student-focused tool, documentation site, or web application can all be suitable. Your first goal is to understand the project’s workflow—not to select the most impressive-sounding repository.

Before committing to an issue, check:

Activity: Are issues and pull requests being reviewed? Look at recent project activity, but remember that active repositories can still have limited maintainer capacity.
Setup: Can you install dependencies and run the project using its documented instructions?
Contribution guidance: Read CONTRIBUTING.md, the README, code of conduct, and any issue or pull-request templates. Projects set their own expectations for tests, formatting, branches, and communication.
Issue context: Is the problem clearly described? Are there maintainer comments, design decisions, or related issues that affect the proposed solution?
Scope: Can you state the change in one or two sentences and identify a likely place in the codebase to investigate?

A “good first issue” label can help you find candidates, but it is not a promise that the task is simple, available, or ready for someone new. The issue may need clarification, may already be in progress, or may depend on broader changes.

Select a manageable first issue

A good first task has a visible outcome, a bounded scope, and a way to check whether the change works. Examples include correcting a reproducible documentation error, improving a small validation message, fixing a narrowly defined UI behavior, or adding a test for an existing bug.

Be cautious with issues that:

Ask for a broad redesign or use phrases such as “improve performance” without a specific target.
Depend on credentials, paid services, hardware, or production data you cannot access.
Have no reproduction steps and require assumptions about expected behavior.
Touch several unrelated components or introduce a new architecture.
Have recent comments suggesting that the approach or requirement is still being discussed.

If the issue looks suitable, search the repository for related code and tests. Then leave a concise comment before doing substantial work. For example:

Hi, I’d like to investigate this. I can reproduce the behavior using the steps in the issue and plan to update the form validation and add a regression test. Is that approach consistent with the project’s expectations?

This is not a request for permission in every project—follow its stated process—but it helps prevent duplicated effort and makes your assumptions visible. Do not treat silence as approval or reserve an issue indefinitely. If you cannot continue, tell the maintainers and release any claim you made.

Reproduce the issue before changing code

A reproduction gives you a baseline and helps separate the reported problem from your assumptions.

Read the issue and linked discussions completely. Note the expected behavior, actual behavior, and any unanswered questions.
Follow the project’s documented setup instructions. Use the required runtime and package-manager versions where specified.
Run the existing tests or checks before editing. Record failures that already exist so you do not attribute them to your change.
Follow the issue’s steps with a minimal example. Write down the environment and exact inputs that matter.
If the report is unclear or you cannot reproduce it, ask a specific question and share what you tried. Do not invent missing requirements.

For a user-interface bug, a concise reproduction might state the route, the action taken, and the visible result. For a library bug, include a small input and the output or error. Avoid sharing private data, secrets, or personal information in an issue or public test fixture.

Make a focused change and add tests

Once the expected behavior is clear, make the smallest change that addresses it. Follow the project’s existing conventions instead of introducing a new style or dependency for a small task. Keep unrelated cleanup out of the same pull request; a focused diff is easier to review and explain.

Tests should check the behavior that was broken, not merely repeat the implementation. Depending on the project, that may mean adding a unit test, updating an integration test, or documenting a manual verification step when automated coverage is not practical. Run the tests and checks requested by the contribution guide. If a check cannot run locally, say so clearly rather than implying it passed.

A typical Git workflow might look like this, but use the project’s instructions if they differ:

# Start from an up-to-date copy of your fork's default branch
git switch main
git pull --ff-only origin main

# Create a branch named for the task
git switch -c fix/clear-validation-message

# After editing, inspect the change before committing
git diff --check
git diff

# Stage only the files relevant to this change
git add path/to/changed-file path/to/test-file
git commit -m "Fix validation message for empty input"

Branch names and the default branch can vary. Do not copy commands blindly if the project uses a different workflow. Before pushing, inspect the staged diff and make sure it contains no credentials, local configuration, generated files, or unrelated changes.

Open a useful pull request and discuss the change

A pull request is a proposal for review, not a declaration that the change is complete or will be accepted. Use the project’s template and include the information reviewers need:

The issue or problem being addressed.
The behavior before and after the change.
What you changed and why you chose that approach.
Tests or checks run, with the result of each.
Any known limitations or questions for reviewers.
Screenshots or a short recording for visual changes, if appropriate and safe to share.

Keep the description factual. If a test fails because of an existing environment issue, explain that. If maintainers request a different approach, ask questions and revise the proposal where appropriate. Review comments are part of collaboration: respond to them, push updates to the same branch when the project expects that, and explain when you disagree respectfully.

A pull request may be declined, deferred, or closed because priorities and project constraints change. That does not make the work worthless, but it does mean your portfolio must accurately state the outcome. Never describe an unmerged patch as part of the released project.

Turn the contribution into a portfolio story

A useful portfolio entry explains your reasoning and evidence, not just the repository name. Write it for someone who may not know the project or its internal terminology.

A clear case study can follow this outline:

Context: What does the project do, and what problem did the issue describe?
Investigation: How did you reproduce the behavior? Which parts of the code or documentation did you inspect?
Decision: What approach did you choose, and what alternatives or constraints mattered?
Implementation: What changed? Link to the issue, pull request, or relevant commit if public and appropriate.
Verification: Which tests and checks did you run? State their results precisely.
Outcome: Was the pull request merged, still under review, revised, or closed? Include the status and date you last checked it.
Reflection: What did you learn, and what would you improve next time?

For example, a short summary might say: “I reproduced an incorrect empty-input message in a form component, traced it to the validation branch, and proposed a focused fix with a regression test. The pull request is under review; the local unit test passed.” This describes work and status without claiming acceptance or impact you cannot verify.

For an Indian student or junior developer, a contribution can complement coursework, internships, or personal projects by showing work in a shared codebase. Keep the evidence accessible: a public issue or pull request, a concise write-up, and a clear explanation of your own role. If the repository is private or the contribution cannot be shared, do not publish its code or confidential details; describe the experience only with permission and within applicable confidentiality rules.

Common mistakes and how to avoid them

Choosing by label alone: Read the full issue, recent comments, and project guidance before starting.
Starting without reproducing the problem: Establish the existing behavior first so you can verify the change.
Making a large first pull request: Split unrelated work and ask maintainers about broader changes before investing heavily.
Skipping tests or overstating them: Run the relevant checks and report exactly what did and did not pass.
Ignoring local instructions: Projects differ in setup, formatting, commit, and review expectations. Their contribution guide takes precedence over generic advice.
Treating review as a personal judgment: Review is about the proposed change and project needs. Ask for clarification and use the feedback to learn.
Presenting a proposal as an accepted result: State the pull request’s current status accurately and update your portfolio if it changes.
Sharing sensitive information: Check diffs, screenshots, logs, and test data before publishing them.

A practical checklist

Before picking the issue, confirm that you understand its scope and have read the project’s contribution instructions. Before coding, reproduce the behavior and identify how you will verify a fix. Before opening a pull request, review the diff, run relevant checks, and write a clear description. After review, respond professionally and record the outcome accurately in your portfolio.

Conclusion

Your first open-source contribution is best treated as a small, collaborative engineering exercise. Choose a bounded issue, learn the project’s workflow, reproduce the problem, test a focused change, and communicate clearly throughout review. Whether the pull request is merged or not, a truthful portfolio story can show how you approached the work, what evidence you gathered, and what you learned—without promising that one contribution will lead to a job.