Here are the basic steps to submit a pull request to an open source project.

A branch lets others work inside your existing repository, which is ok if everyone in the team is part of the same organization. A fork keeps things separate from your repo. You will still use a feature branch within your fork for the feature or fix you are working on.

Step 1 - Create a fork

The exact instructions for creating a fork of a public repo vary slightly depending on whether you are using GitHub, GitLab, etc. The instructions for GitHub can be found here . This creates a personal copy of the repo and all its branches.

Step 2 - Clone repo and setup remote

Clone the forked repo. At this point you have a local copy and an origin, which is your forked repo. Add a remote named upstream to point to the public repo (FluentBit in this example). git remote -v now shows two remotes (origin for your personal copy and upstream linked to the public repo).

> git remote add upstream git@github.com:fluent/fluent-bit.git
> git remote -v
origin  git@github.com:your-username/forked-repo.git (fetch)
origin  git@github.com:your-username/forked repo.git (push)
upstream  git@github.com:fluent/fluent-bit.git (fetch)
upstream  git@github.com:fluent/fluent-bit.git (push)

Step 3 - create your feature or fix branch

Run the following commands to create a branch for the fix or feature you are working on. Typical branch naming: feat-<handle>-intro for a feature or fix-<handle>-<issue-id> for a fix. The third command pushes the branch that was created locally to the remote repository (origin) that it was created from.

> git checkout main
> git checkout -b feat-<handle>-intro
> git push -u origin feat-<handle>-intro

Step 5 - Develop fix or feature

You are ready to develop your fix or feature. When you run git log:

  • origin/main is the main branch on the remote repo
  • origin/HEAD is the active branch on the remote repo
  • main (in green) is where the local repo

Step 6 - Sync with upstream

Run the following commands when you are ready to merge or when you want to pull down changes from the upstream (i.e. public repo). This brings your default branch (main) into sync with the upstream.

git fetch upstream
git checkout main. ## <- IMPORTANT: Switch to main (not in feature or fix branch any more)
git merge upstream/main
git push

Additionally, you will need to merge changes into the feature or fix branch(es) that you have been working on.

git checkout feat-<handle>-intro
git merge main

Refer to GitHub documentation to resolve merge conflicts.

Step 7 - Create PR using your feature or fix branch

If this is your first PR, the web UI is the best place to start. Refer to the instructions here .

Step 8 - Cleanup

Delete the feature/fix branch once the PR is merged. This is done in two steps - locally and on the remote (origin).

git branch -d 
git push origin --delete feature-fix-branch-name

Other useful commands

# Shows remotes and branches available locally 
cat .git/config   

# Change most recent commit (after pushing) 
git commit --amend
git push -f

# Create a branch using a commit hash
git branch branch-name <commit-hash>

# Create a branch using a symbolic reference ("grandparent")
git branch branch-name HEAD~2