Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update 02-branching.md #57

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
+38 −18
Open

Update 02-branching.md #57

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 38 additions & 18 deletions episodes/02-branching.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,22 +68,28 @@ where the developers make changes.
Once the feature is done, they submit a pull request and
merge it into the `main` branch after review.
Feature branches should be relatively short-lived.
Each collaborator must be given **write** level, or higher, permissions
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Each collaborator must be given **write** level, or higher, permissions
Each collaborator must have **write** level, or higher, permissions

on the repository.
There are 2 repositories for each person to be mindful of, ***local*** and ***origin***.

#### Pros

- Each feature is developed away from `main` so you don't affect production code
- Multiple features can be developed in parallel feature branches
- It's a simple model that's easy for those new to git and your project
- Easy to set up with continuous integration testing and deployment
- Each feature is developed away from `main` so you don't affect production code.
- Multiple features can be developed in parallel feature branches.
Comment on lines +77 to +78
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- Each feature is developed away from `main` so you don't affect production code.
- Multiple features can be developed in parallel feature branches.
- Developers create each feature away from `main` so you don't affect production code.
- Developers can create many features can in parallel feature branches.

- It's a simple model that's easy for those new to git and your project.
- Easy to set up with continuous integration testing and deployment.

#### Cons

- If you don't regularly merge changes to `main` into your feature branch
it can become outdated, leading to merge conflicts
it can become outdated, leading to merge conflicts.
- You may struggle if you need to maintain multiple production versions
simultaneously in the same repository
simultaneously in the same repository.

The Feature Branch model is sometimes called GitHub Flow.
Note that all branches and commits exist within the single GitHub, ***origin***, repository
(and are therefore easily visible by anyone who has read access to the repository)
and any contributor can write to any branch that has not been explicitly protected.
Comment on lines +90 to +92
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Note that all branches and commits exist within the single GitHub, ***origin***, repository
(and are therefore easily visible by anyone who has read access to the repository)
and any contributor can write to any branch that has not been explicitly protected.
Note that all branches and commits exist within the single GitHub, origin repository.
They are visible to anyone who has read access to the repository.
Any contributor can write to any branch that is not explicitly protected.


```mermaid
---
Expand Down Expand Up @@ -142,14 +148,21 @@ to contribute to on GitHub in your personal space.
You develop your changes using this fork.
When a change is ready you open a pull request to contribute the changes
back to the original repository.
There are 3 repositories for each person to be mindful of,
***local***, ***origin*** (your fork), and ***upstream*** (the original repository).

#### Pros

- Removes the need to give all collaborators adequate permissions
on your repository
- Only project maintainers can approve new code
- Removes the need to give all collaborators write level or higher permissions
on your repository.
Anyone with read access to a repository can contribute.
- Only project maintainers can approve new code.
- You can use any other model within your main repository and
forks to develop changes
forks to develop changes.

Note that all branches and commits exist within the collaborators fork, not the ***upstream*** repository
(and are therefore less visible to anyone who has read access to the upstream repository).
Collaborators can use their fork to test more complex changes, including for example testing github actions within a dummy-PR.
Comment on lines +163 to +165
Copy link
Contributor

@wxtim wxtim Jan 31, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Note that all branches and commits exist within the collaborators fork, not the ***upstream*** repository
(and are therefore less visible to anyone who has read access to the upstream repository).
Collaborators can use their fork to test more complex changes, including for example testing github actions within a dummy-PR.
All branches and commits exist within the collaborators fork, not the ***upstream*** repository. They are harder to find for anyone who has read access to the upstream repository.
Collaborators can use their fork to test more complex changes. For example testing github actions within a dummy-PR.


-----------------------------------------

Expand All @@ -163,12 +176,12 @@ merged onto the `develop` and `main` branches.

#### Pros

- There is a clear purpose for each branch
- Handles complex projects well
- There is a clear purpose for each branch.
- Handles complex projects well.

#### Cons

- Very steep learning curve, not suitable for novices
- Very steep learning curve, not suitable for novices.
Copy link
Contributor

@wxtim wxtim Jan 31, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think that we want to word this so strongly - I expect most of our user base are perfectly capable of managing it, and I don't want people to be put off using it when appropriate, or scaring people whose projects require it.

Suggested change
- Very steep learning curve, not suitable for novices.
- Steeper learning curve, novices may require more help.


```mermaid
gitGraph
Expand Down Expand Up @@ -212,11 +225,18 @@ merged onto the `develop` and `main` branches.

## Recommendations

For small projects using a Feature Branch model is normally sufficient.
If your team is large, or you expect external collaborators to contribute
then we recommend developing using forks.
Most open source projects require you to submit new code using a fork.
The next few episodes will guide you through examples of both models.
For repositories where collaborators are a small and trusted group the Feature Branch
model is normally sufficient.

A Forking model is preferable if:
- There are more collaborators, because the number of branches may become unwieldy.
- There are external collaborators whose contribution is valued,
but the repository owners need to retain control of the original.
For this reason most open source projects use a Forking Model.

These working pattern are conventions not rules.
It is easy to switch from one working pattern to the other.
Or even to use the feature branch pattern for trusted colleagues and the forking pattern for outside contributors.

This wasn't an exhaustive list of branching models!
You can find more information using the links below:
Expand Down