When To Branch When To Fork

Github and development workflow

With git and Github development, there are a number of possible workflows available for the developer to choose. Remember however that by using git and github, some of the stereotypes associated with forking and branching are completely different compared to subversion.

Forks are a common part of normal project workflow.

Developers typically fork into their own repository, work to their satisfaction, and then submit a pull request into the project repository. This appears to be the way that many github projects operate. Github "Network" view provides a quick look at who has forked a repository. Since most everything on github is public, anyone can look at the forked repository and offer to collaborate.

Branches are lightweight pointer into the history

Branches are a good way to deal with interruptions, stage partially completed work, etc. Unlike subversion where a branch was a copy of the code, branches in git are just a pointer and take only a few seconds to create.

Factors that influence when to fork:

This decision tree looks at two factors:

1. What type of developer are you?:
   • An experienced developer with Core checkin rights:
   • An experienced extension developer
   • A casual contributor new to the foswiki project

The casual contributor should create a fork on github, create a task, and then propose their fix by generating a pull request. A foswiki core developer will review your request and either suggest changes, or apply your change.

The experience developer, could work within the foswiki project, or create a fork into their own github account. Using the fork based workflow keeps the noise down and helps keep the master branches stable.

1. What type of work are you planning
   • Core / default extension changes:
     • Major changes to the project core or default extensions that are liable to break something
     • Minor changes / small bugfixes to core or default extensions
     • Documentation updates
   • Changes to a Extension marked CoordinateWithAuthor
   • Changes to an extension marked PleaseFeelFreeToModify

TBD...

---

Note that when you `git clone`, you are making a fork. So if you're using git, you're forking.

If you edit a GitHub repository file using the GitHub web UI, it first makes a fork of that repository into your account - this is normal.

Typically, when you make changes, you fork first on Github, then push your changes to your repo, and make a pull request - giving others something to review and collaborate about. See https://help.github.com/articles/fork-a-repo

Most projects on GitHub seem to gravitate towards everyone using the same workflow - personally, I like the review and merge via GitHub UI workflow.

-- SvenDowideit - 27 Aug 2014

There is one very important aspect of forks, be it git or not: it limits the number of people working on that fork on both ends the origin and the copy you just created. This is good and bad at the same time as it

• keeps the noise down,
• lets you do what you want, but also
• hinders others from joining in on the features being developed.

No matter how you code, either

• by using forks,
• by just hacking the foswiki/distro master branch or
• by creating an experimental feature branch

What counts is that your contributions end up in the main upstream repository and branch as quick as possible.

I agree. Forking does need a concerted effort to merge the forks back in. That said, I believe that the core developers have an obligation to review and merge in pull requests. There are probably many factors that contribute to the many bit-rotting forks.

• Forker just scratches the itch and walks away, fails or refuses to share. ... That happens today with svn as well. but we have no visibility. We don't even know that the fork happened unless it's mentioned on irc or the like.
• Forker submits a pull request and core ignores it. That happens as well today. People attach patches to tasks that get ignored, We have 2 pull requests sitting out there already that need a knowledgeable core dev. to merge them in.
• Fork just bit rots on it's own. (Our own ext. repository has some of that, with no GH involved)

.-- GeorgeClark - 27 Aug 2014

The great danger of forks is that they drift apart gradually while nobody merges back into a commonly shared repo again. This can be observed on github for a lot of projects: there are great features in each of the forks, yet they are all incompatible. Examples: fullcallendar, jquery.gantt. It is a shame that we still have no cool fullcalendar that combines the merits from all of its forks, some of them are held privately or even as part of a commercial product. Same for jquery.gantt. This is really a PITA. To be fair, I am not sure whether or not work on these open source projects would have not been stalled if it was harder to fork. But there are reasonable doubts that forking easily is part of the problem. In the end it boils down to the different "repository maintainers" not talking to each other while quietly working on their code silos.

In the end being forced to work on the same repository and branch also forces us geeks to talk to each other.

Here I disagree. The forking happens, we just don't know about it. And nobody is forced to actually commit back into svn. -- GeorgeClark - 27 Aug 2014

With forking a repository made so easy using git(hub) we see a growing number of repositories that rarely are taken down once their initial purpose has been fulfilled. Repositories are created but are rarely disassembled even though deleting a repository should be even easier than creating it in the first place. In effect this creates a massive pile of code rot on github ... which is not a good thing at all for the open source movement in general as well as for github having to host all of this unused data. At some point in the future I expect github will add a kind of expiration timer or similar to identify abandoned repositories. Or they just throw more hardware at it.

So when forking Foswiki as part of a development, please make sure

• that your changes are merged back upstream and
• that you delete any redundant private forks once that happened.

And btw. don't be afraid of breaking things on foswiki/distro master branch. There are others to rescue you. Not so when you break your own repo.

To your two bullet points. ++10 But to not breaking master ... --5 Branching is making copy without forking. ... comments below

-- MichaelDaum - 27 Aug 2014

So ignoring the whole forking argument, we come to branching.. With git, I'd certainly like to see the workflow for anything other than minor changes be something like:

git checkout -b myNewItch
do until satisfied:
   commit... break... commit... commit... SomeSUCCESS
   git push origin myNewItch   
git checkout master
git merge myNewItch
git push

That gives everyone the chance to see your work but doesn't completely toast master for extended periods of time.

-- GeorgeClark - 27 Aug 2014

One misconception that is worth clearing up:

Forking (on GitHub) does not stop others from working on your branch - they can add your new forked repo to their remotes, and then can use GH to make pull requests against your branch. This can later be merged into the master repo.

-- SvenDowideit - 29 Aug 2014

Recommendation:

• push rights for repo:
  • foswiki/distro -> use branches, hack master
  • foswiki/extension
    • extension is flagged CoordinateWithAuthor -> use branches or fork and create pull request
    • extension is flagged FeelFreeToModify -> use branches, hack master
• no push rights -> fork and create pull request

-- MichaelDaum - 29 Aug 2014