Your First Open-Source Pull Request: What I Wish I Knew Before Mine

Your First PR Does Not Need To Be Impressive

The hardest part of making your first open-source contribution is often not the code. It is opening a repository full of unfamiliar folders, checks, and people who seem to know exactly what they are doing.

My first thought was not, I am ready to help.

It was closer to: What if I touch something and embarrass myself in public?

If that is where you are, remember this: your first pull request does not need to be impressive. It needs to be focused, understandable, tested, and easy to review. A PR is a proposal, not proof that you already understand the entire codebase.

The Small Fix That Changed Where I Put My Energy

I found BetterGov PH, a community-led project making Philippine government information and services more usable through technology, transparency, and collaboration. That mission mattered to me. Government information should be accessible to everyone, not only to people who already know where to look.

My first contribution was PR #597: Fix year filter capped 1k. I opened it on February 8, 2026. It fixed a year filter that stopped at 1,000 results and eventually contained five commits across three files.

On March 20, 2026, it was merged, becoming my first real open-source contribution. That one merge encouraged me to join the Data Engineering Pilipinas leadership team and work on the Builders Open Track. Today, I also contribute to Nous Research's Hermes Agent. Along the way, I found a new passion: harness engineering, building the systems around agents that help them work well.

When I opened the branch, I was only trying to fix one bounded problem without breaking anything else. That is a good place to begin.

Choose A Project You Actually Care About

Do not start with the most famous repository you can find. Start with a purpose that matters to you. Interest gives you patience when setup or review takes longer than expected.

Before choosing an issue, check for recent activity, a readable README, contribution instructions, a code of conduct, and a place to ask questions. Open source is not limited to application code. BetterGov also accepts ideas, bug reports, translations, documentation, and data-scraping contributions. A documentation correction can be a better first contribution than a feature touching half the application.

Read Before You Code

Treat the contribution guide as part of the codebase. Check the required runtime, package manager, branch convention, commit format, tests, and PR expectations. Search existing work to avoid duplication, and ask a maintainer about unclear scope before implementing it.

Run the project before changing anything. If it already fails on your machine, you want to know before your change gets blamed.

For BetterGov, the current contributing guide recommends Node.js 22 or later, npm 10 or later, Git, and a code editor. The local setup uses .env.example, the Node version in .nvmrc, npm install, and npm run dev. Work involving search may also require Meilisearch.

A Reusable First-PR Workflow

The exact commands vary by project, but the usual GitHub flow looks like this.

1. Fork And Clone

Fork the repository through GitHub, then clone your copy:

git clone https://github.com/<your-username>/<repository>.git
cd <repository>
git remote add upstream https://github.com/<original-owner>/<repository>.git

2. Sync And Create A Branch

Start from the latest version of the project's main branch:

git checkout main
git fetch upstream
git merge upstream/main
git push origin main
git checkout -b fix/short-description

Use the project's branch convention.

3. Make One Focused Change

Resist cleaning everything you notice. Unrelated formatting, dependency upgrades, and refactors make the PR harder to review.

While working, inspect what Git sees:

git status
git diff

Run the repository's checks and test the behavior you changed. Add screenshots or logs when they make the result easier to review.

4. Commit And Push

Stage only the files that belong to the change:

git add path/to/changed-file
git commit -m "fix(search): correct year filter results"
git push -u origin fix/short-description

BetterGov follows Conventional Commits, where messages begin with types such as feat, fix, docs, test, or refactor. Other projects may use different rules, so follow the repository in front of you.

5. Open A Pull Request

A useful PR description answers what a reviewer needs to know:

Problem

What is wrong, missing, or difficult today?

Change

What did you change, and what did you intentionally leave out?

Validation

Which tests or manual checks did you run?

Evidence

Add screenshots, logs, or reproduction steps when relevant.

Related Issue

Closes #123

AI Assistance

Disclose significant AI-generated or AI-modified work when required.

Keep the title specific. Link the issue. Do not claim tests you did not run.

Ask AI When You Do Not Understand Something

You do not get bonus points for staying confused. If a term, command, test failure, or unfamiliar file blocks you, ask an AI assistant to explain it. Use AI to reduce confusion, not to hide it.

These prompts are safer than immediately asking for a finished patch:

• "Explain this contribution guide to a first-time contributor. Turn it into a checklist, and do not invent commands."
• "This command failed with the following error. Explain the likely cause and ask me for missing context before suggesting changes."
• "Explain what this function does line by line and what could break if I change this condition."
• "Review my git diff for unrelated changes, missing tests, and possible secrets."

Verify every answer against the repository. Read the change, run the tests, and ask questions until you can explain the code in your own words.

Never paste credentials, private code, personal data, or confidential logs into a model. Do not submit a generated patch just because it compiles. You must be able to discuss the decisions and revise them.

BetterGov explicitly asks contributors to disclose AI-generated or significantly AI-modified code in the PR description. Treat that disclosure as useful review context, not an admission of failure.

I Made My Repository Contribution Agent Skill Public

An AI agent can read code quickly and still miss how a repository's maintainers expect people to contribute.

So I built an agent skill that studies the repository before changing it.

You can use my public z-repo-contribution-guide skill for open-source contributions.

It tours a Git repository, reads files such as AGENTS.md and CONTRIBUTING.md, examines CI checks and PR templates, and learns recurring commit and PR patterns. It separates written requirements from automated enforcement, observed conventions, and uncertain conclusions. On GitHub, it can compare merged PRs with closed-without-merge work instead of relying on one example.

The skill can turn that evidence into a private repo guide and detect guidance changes after an upstream update. It gives an agent better evidence before helping you plan, code, test, or prepare a PR.

Try asking:

Use $z-repo-contribution-guide to tour this repository and explain how its maintainers expect contributions to be made.

Review Is Part Of The Contribution

Opening the PR is not the finish line. A maintainer may ask for a smaller scope, another test, or a different implementation.

Read the comment carefully. If you do not understand it, ask. Make the change on the same branch, commit it, and push again:

git add path/to/changed-file
git commit -m "refactor: address review feedback"
git push

The pull request updates automatically. You do not need to open a new one.

Review can feel personal. Usually, the maintainer is protecting the project while showing you how it defines quality.

Mistakes That Make A First PR Harder

Most difficult first contributions become difficult because the scope or communication drifted. Avoid starting with a large feature, coding before reading the instructions, mixing unrelated cleanup into the fix, submitting AI output you cannot explain, skipping tests, or disappearing after review. A small PR with clear evidence is easier to trust.

If You Want Help With Your First PR

If you still feel stuck, message me on LinkedIn. Send the repository, target issue, what you tried, and where you got blocked.

If I am free, I am willing to hold a mentorship session and walk through the process. I will not write the contribution for you, but I can help narrow the issue, work through Git, and prepare something reviewable.

If BetterGov's mission resonates with you, start with the repository, read the contribution guide, and choose one useful problem.

Your first PR does not need to change the world. It needs to teach you how to contribute to one.