GitHub Flow

The GitHub Flow is an industry-standard workflow for continuous delivery and collaboration. It’s lightweight, branch-based, and supports teams of any size working on projects of any complexity.

The Seven Key Steps
  1. Fork and clone the repository URL: Fork the repository on GitHub
  2. Clone the repository URL: Clone your fork locally so you can start working on changes
  3. Pull latest from main branch: Always start with the most recent code
  4. Create a feature branch: Make a new branch for your work
  5. Make commits on your branch: Save your changes regularly
  6. Push branch and open Pull Request: Share your work and request feedback
  7. Discuss and review code: Collaborate with teammates on improvements
  8. Merge to main and delete branch: Integrate approved changes and clean up

Step 1: Fork a repository

If you want to contribute to a repository where you haven’t been added as a collaborator you need to fork it.

Navigate to the repository on GitHub, e.g. https://github.com/Bristol-Training/demo-calc-lib.

Click “Fork” in the top-right corner This creates a copy under your GitHub account (https://github.com/YOUR-USERNAME/demo-calc-lib)

Step 1: Clone the repository URL

On your repository page in GitHub, click the green “Code” button and copy the HTTPS URL (it should look like https://github.com/YOUR-USERNAME/demo-calc-lib.git).

git clone https://github.com/YOUR-USERNAME/demo-calc-lib.git
cd demo-calc-lib

Step 2: Pull Latest from Main Branch

Before starting new work, ensure you have the latest version of the main branch. This ensures you’re building on the most recent stable version, reducing the chance of conflicts later.

git checkout main
git pull origin main

Step 3: Create a Feature Branch

Create a new branch for your feature or fix:

git checkout -b feature/add-power-function

Branch naming conventions help teams stay organised:

  • feature/ — for new features (e.g., feature/add-power-function)
  • fix/ or bugfix/ — for bug fixes (e.g., fix/correct-calculation-error)
  • docs/ — for documentation updates (e.g., docs/update-readme)
  • refactor/ — for code improvements (e.g., refactor/simplify-database-queries)

Use descriptive names that explain what the branch does. Avoid vague names like my-branch or updates.

Step 4: Make Commits on Your Branch

Work on your changes and commit regularly:

# Make changes to files
git add .
git commit -m "Add login form component"

# Make more changes
git add .
git commit -m "Add authentication validation logic"

Good commit practices:

  • Commit small, logical chunks of work
  • Write clear, descriptive commit messages
  • Use present tense (“Add feature” not “Added feature”)
  • Explain what and why, not how

Step 5: Push Branch and Open Pull Request

Push your branch to GitHub:

git push origin feature/add-power-function

Then, on GitHub:

  1. Navigate to your repository
  2. Click “Compare & pull request” (appears after pushing)
  3. Write a clear title and description
  4. Request reviewers
  5. Click “Create pull request”

Step 6: Discuss and Review Code

This is where collaboration happens:

  • Reviewers examine the code, suggest improvements, and ask questions
  • Author responds to comments and makes requested changes
  • Discussion happens directly on the Pull Request

To make changes based on feedback:

# Still on your feature branch
# Make the requested changes
git add .
git commit -m "Address review comments: improve error handling"
git push origin feature/add-power-function

The Pull Request automatically updates with your new commits.

Step 7: Merge to Main and Delete Branch

Once approved, merge the Pull Request via GitHub’s interface:

  1. Click “Merge pull request”
  2. Confirm the merge
  3. Delete the branch (GitHub prompts you to do this)

Then, locally:

git checkout main
git pull origin main
git branch -d feature/add-power-function
Why This Matters

GitHub Flow enables teams to:

  • Ship code safely and frequently: Small, reviewed changes are less risky
  • Work in parallel: Multiple features can be developed simultaneously
  • Maintain code quality: Code review catches bugs and improves design
  • Preserve project stability: The main branch always contains working code
  • Document decisions: Pull Request discussions provide context for future developers