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.

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

Branching v. Forking #54

Open
wxtim opened this issue Jan 30, 2025 · 6 comments · May be fixed by #57
Open

Branching v. Forking #54

wxtim opened this issue Jan 30, 2025 · 6 comments · May be fixed by #57
Assignees
Labels
documentation Improvements or additions to documentation

Comments

@wxtim
Copy link
Contributor

wxtim commented Jan 30, 2025

This text from chapter 2 attempts to define when branching and forking models are appropriate.

I don't think it's quite right, and that the choice is often more about securuty than size.

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.

@wxtim
Copy link
Contributor Author

wxtim commented Jan 30, 2025

My proposed alt.

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.

@wxtim wxtim added the documentation Improvements or additions to documentation label Jan 30, 2025
@ehogan
Copy link
Member

ehogan commented Jan 30, 2025

Thanks @wxtim! 🎉

Would it be worth stating some facts about the different approaches first? For example:

A decision-makers guide!

With the Feature Branch model:

  • all contributors must be provided with at least write permissions to the repository so they have permission to push their changes
  • all branches and commits exist within the repository (and are therefore easily visible by anyone who has read access to the repository)
  • any contributor can write to any branch that has not been explicitly protected

With the Forking model:

  • anyone with read access to a repository can contribute, without requiring write permissions
  • all branches and commits exist within the contributor's fork, not the upstream repository (and are therefore less visible to anyone who has read access to the upstream repository)

Then follow with:

A Feature Branch model might be preferable if:

  • contributors to the repository work collaboratively together on a single branch (for example, remotely or via pair programming)
  • there is a need for oversight of changes

A Forking model might be preferable if the repository owner(s):

  • do not wish to provide write permissions to any contributors
  • do not wish to manage a potentially large number of branches from contributors
  • there is no need for oversight of changes

?

I would argue that it doesn't matter whether a contributor is internal or external, so I have used the term "contributor" above :)

@mo-marqh
Copy link
Member

@mo-marqh
Copy link
Member

There are notes that i use a lot in the https://github.com/MetOffice/GitAndGitHubCoP/blob/main/repositories.md CoP page; please feel free to use these (and propose improvements in situ)

i like Tim's brief summary, it captures things well.

it might be a useful point to re-iterate the value of CONTRIBUTING.md

whatever one is doing at present, agree it, write it down, and change it in writing when useful.

some thoughts regarding to Emma's post (cherry-pick at will)

With the Feature Branch model:

  • There are 2 repositories for each person to be mindful of, local and origin
  • all contributors must be provided with at least write permissions to the repository so they have permission to push their changes
  • all branches and commits exist within the repository (and are therefore easily visible by anyone who has read access to the repository)
  • any contributor can write to any branch that has not been explicitly protected

With the Forking model:

  • There are 3 repositories for each person to be mindful of, local, origin & upstream
    • naming of these is not enforced, consistency of language can be useful
  • anyone with read access to a repository can contribute, without requiring write permissions
  • all branches and commits exist within the contributor's fork, not the upstream repository (and are therefore less visible to anyone who has read access to the upstream repository)
  • contributors can use their fork to stage changes, including for example testing github actions within a dummy-PR
  • Adopted code is cleanly segregated from development / proposal / investigation code

Then follow with:

A Feature Branch model might be preferable if:

  • contributors to the repository work collaboratively together on a single branch (for example, remotely or via pair programming)
  • there is a need for oversight of changes (there is always need for oversight of change, the model doesn't affect this, imho, e.g. everything should PR)

A Forking model might be preferable if the repository owner(s):

  • do not wish to provide write permissions to all contributors (especially permission in advance)
    • keeping write permissions to a smaller core team, with merge rights
    • it's useful for all contributors to propose from forks, keeping merge rights only for adopting proposals
  • do not wish to manage a potentially large number of branches from contributors , which can scale badly, especially over time
  • there is no need for oversight of changes *(there is always need for oversight of change, the model doesn't affect this, imho, everything must PR for forks (maybe I missed some other intent here tho) ) *
  • wish to benefit from a model that scales more effectively for code complexity, release management, etc. as well as number and range of contributors.

** It may also be worth noting that moving from a feature branch model to a forking model isn't too hard, so it's not a for-ever choice. It's also not a strict either-or choice, facets of both models can be combined. (refer back to contributor guide being documented)**

( aside: I would advocate against enforcing a no fork option in the settings, except in cases of strictly single owner, no share code bases.
Letting the forking model be used by people, even if the default operating model is feature branch, is really useful; it enables occasional users to provide input proposals swiftly, where those users may simply not engage if the overhead of getting let in with permissions is too high)

finally, to paraphrase personal forks are one honking great idea ; )

@wxtim
Copy link
Contributor Author

wxtim commented Jan 31, 2025

Would it be worth stating some facts about the different approaches first? For example:

Aren't these further up the page here?

Any points not already made in that document and made in the above comments should be added to those pros and cons.

I'm inclined to add the following to my original summary.

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).

@wxtim
Copy link
Contributor Author

wxtim commented Jan 31, 2025

My suggestion having run my og suggestion through a reading-age checker

For small projects using a Feature Branch model is often enough. If your team is large, or external collaborators will add to the code then we recommend using forks. Most open source projects need you to submit new code using a fork. The next few episodes will guide you through examples of both models.

These working pattern are conventions not rules. It is easy to switch from one working pattern to the other. You can even mix patterns. For example, allowing colleagues to branch but making external contributors fork.

@astroDimitrios astroDimitrios linked a pull request Jan 31, 2025 that will close this issue
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation
Projects
None yet
Development

Successfully merging a pull request may close this issue.

3 participants