If you want to contribute without breaking the main repo and without awkward apologies, welcome. This guide shows how to use GitFlow with a fork and a local clone, push feature branches to your fork, and open a clean pull request against upstream develop. It is short, practical, and slightly judgmental about chaotic commit histories.

Why use a fork and a clone

Forking on GitHub or another hosting service gives you a private sandbox to work in, and cloning brings that sandbox to your machine. That setup keeps origin pointing at your fork and lets you propose changes to the upstream repository with pull requests, so the maintainers do not have to babysit your local branches.

Forking on the hosting service

Use the web UI to fork the upstream repository into your personal account. This is the simplest way to avoid accidentally pushing to upstream and to keep a record of your proposed changes.

Cloning the fork

Clone your fork to start working locally. The clone will set origin to your fork by default which makes pushing straightforward.

git clone git@github.com:your-username/repo.git
cd repo

Pointing at upstream

Add the original repository as the upstream remote so you can fetch changes from the official source. This is the lifeline that keeps your fork from falling behind forever.

git remote add upstream git@github.com:upstream-owner/repo.git
git fetch upstream

Start a feature branch

Either use the git flow helper or make a branch manually from develop. Both work. GitFlow gives you conventions, the manual way is fine if you prefer being in control.

Using the git flow helper

git flow feature start my-feature

Manual branch creation from develop

git checkout develop
git checkout -b feature/my-feature

Keep commits focused and atomic, and write clear messages unless you enjoy long review cycles.

Pushing and opening a pull request

Push your feature branch to origin which is your fork, then open a pull request from your fork branch to upstream develop using the web UI. Describe the change, reference issue numbers if any, and keep the review notes polite.

git push origin feature/my-feature

On GitHub pick your fork and branch as the source and upstream develop as the target. Add a concise summary and any test steps or screenshots that make reviewers less grumpy.

Keeping your fork in sync

Falling behind upstream is a fast track to merge conflicts and shame. Regularly fetch upstream and update your local develop branch, then push the update to your fork.

Merge workflow

git fetch upstream
git checkout develop
git merge upstream/develop
git push origin develop

Rebase workflow when you want cleaner history

git fetch upstream
git checkout develop
git rebase upstream/develop
git push origin develop --force-with-lease

Use rebase only if you understand the risks of rewriting history and coordinate with any collaborators who may share branches.

Common gotchas and tips

• Always confirm which remote is origin and which is upstream with git remote -v, because assumptions are how we break things.
• If your PR needs changes, make them on the same feature branch and push to origin. The PR will update automatically.
• Use meaningful branch names like feature/add-login or fix/text-typo, and avoid feature/untitled or my-fix-2 unless you enjoy confusion.
• If you rebase public branches, let reviewers know since they might need to reset their local copies.

Wrap up

Fork and clone, add upstream, start a feature from develop, push to origin, and open a pull request against upstream develop. Keep syncing with upstream to avoid surprise conflicts and to stay a team player. This workflow keeps the main repo tidy and gives you room to experiment without causing chaos.