Master Open Source Contributions: Step-by-Step Guide to Your First PR on GitHub

Overview

Today I will introduce how to start participating in open source projects and get your first PR merged on GitHub.

In addition to the normal PR process, I will also cover handling conflicts, additional commits, merging commits, and other complex issues.

The article is divided into four parts:

Why contribute to open source and why I introduce PRs

How to start, find suitable projects and contribution points

How to start the PR process from fork to push

How to solve common problems after submitting a PR

Why Contribute to Open Source

I focus on improving coding ability as the main reason.

During interviews I ask candidates whether they have read the source code of an open source project or submitted a PR.

Reading and contributing to projects like Kubernetes greatly improves coding skills.

Submitting a PR that runs worldwide is exciting and opens a new world of community interaction.

Why I Want to Introduce PR Workflow

Our company open‑sourced two projects: CNCF Project DevStream and Apache DevLake.

Both projects receive many first‑time contributors, who often encounter issues such as conflicts, too many or messy commits, unsigned commits, non‑standard commit messages, CI failures, etc.

This guide aims to help newcomers and lower the contribution barrier for the DevStream and DevLake communities.

How to Start Contributing

4.1 Find a Suitable Project

If you already know which community to join, skip this section.

Otherwise, consider the following advice:

Do not start with very mature projects (e.g., Kubernetes) because it is hard to find entry‑level issues and your contribution may be overlooked.

Do not start with very small projects that lack proper processes and documentation.

Choose incubated projects from well‑known foundations such as CNCF, Apache, or Linux.

Examples include CNCF sandbox projects, CNCF incubated projects, and Apache incubating projects.

4.2 Find Contribution Points

Typical contributions are feature development or bug fixes, but documentation, test cases, and bug reports are also valuable.

Look for issues labeled “good first issue” in the repository’s Issues page.

Submitting a PR – Step by Step

5.1 Fork the Repository

Click the Fork button on GitHub to create a copy of the project under your account.

5.2 Clone the Repository Locally

Set environment variables and run the following commands:

export WORKING_PATH="~/gocode"
export USER="your-username"
export PROJECT="devstream"
export ORG="devstream-io"

Then clone the repository:

mkdir -p ${WORKING_PATH}
cd ${WORKING_PATH}
git clone https://github.com/${USER}/${PROJECT}.git
cd ${PROJECT}
git remote add upstream https://github.com/${ORG}/${PROJECT}.git
git remote set-url --push upstream no_push

5.3 Update Local Main Branch

git fetch upstream
git checkout main
git rebase upstream/main

Create a feature branch for your work:

git checkout -b feat-xxx

5.4 Write Code

Implement the changes you want to contribute.

5.5 Commit and Push

git add <file>
git commit -s -m "some description here"
git push origin feat-xxx

Commit messages should follow the project’s convention, e.g., feat: description, fix: description, docs: description, etc.

5.6 Open a Pull Request

After pushing, GitHub shows a prompt to create a Pull Request. Fill in the title (usually the same as the commit message) and complete the PR template, which typically includes sections such as Pre‑Checklist, Description, Related Issues, and New Behavior.

5.7 PR Merged

If the PR passes review and CI checks, the project maintainers will merge it.

Common PR Problems and Solutions

6.1 Updating a PR After Review

If reviewers request changes, add new commits locally and push; the PR updates automatically. To keep the commit history clean, squash commits before pushing.

6.2 Squashing Commits

Use interactive rebase to combine commits:

git rebase -i HEAD~2
# Change the second 'pick' to 's' (squash), save, edit the combined commit message
git push -f origin feat-xxx

IDE tools (e.g., Goland) can also squash commits via a graphical interface.

6.3 Resolving Conflicts

Conflicts can be resolved online via GitHub’s “Resolve conflicts” UI or locally by rebasing onto the updated main branch, fixing the files, and force‑pushing.

# Example of local conflict resolution
git checkout main
git fetch upstream
git reset --hard upstream/main
git checkout feat-xxx
git rebase main
# Fix the conflicted files, then
git add <conflicted_files>
git rebase --continue
git push -f origin feat-xxx

6.4 Fixing Commit‑Message CI Failures

If the CI rejects the commit message format, amend the commit and force‑push:

git commit --amend
# edit the message to match the required style
git push -f origin feat-xxx

6.5 Fixing DCO (Signed‑off‑by) Failures

Amend the last commit with the -s flag to add the Signed‑off‑by line, then force‑push:

git commit --amend -s
git push -f origin feat-xxx

Conclusion

This article provides a complete workflow for first‑time contributors, covering project selection, issue hunting, fork‑clone‑branch‑commit‑push, PR creation, CI checks, conflict resolution, and final merge.