How should we introduce Git branching strategies?

[40thieves]

What is the hypothesis?

In the new Git introduction, we introduce creating a branch.

Previously we structured the coursework so that there was one repo per week, and so multiple branches per repo wasn't necessary (caveat: the React coursework did not follow this structure, which caused it's own problems).

The Git introduction above only introduces creating a single branch and it will be necessary for trainees to create multiple branches (with matching PRs), for example one branch for week-1, one branch for week-2, etc. We therefore should discuss which branches strategies we want to introduce and where within the course they should brought up.

Why is this important?

Given the above, trainees will inevitably encounter multiple branches, so I think we should prepare them with basic branching strategies.

For the trainees, the simplest strategy would be to branch off from the current branch, or in other words, create the week-2 branch based on the week-1 branch. However this may mean extra "noise" in the PR diff for trainees/volunteers, making it harder to review the coursework.

[40thieves]

In a recent LDN10 class, the teachers (lead by @jasongwartz) did an ad-hoc workshop to cover branching, as discussed briefly in this Slack thread.

They covered the strategy of checking out to main before creating a new branch, i.e. the both the week-1 and week-2 branches would be based on main.

This has some advantages:

1. It's likely the most "realistic" strategy in regards to real-world Git usage
2. It produces the cleanest diff when opening a PR, since by default Github will compare against main

But has some disadvantages:

1. To switch branches, trainees must have a clean history, which may mean some trainees "get stuck" on the wrong branch. This may then even lead to committing on the wrong branch, and potentially the desire to move commits from one branch to another
2. Trainees have to remember to switch to main before creating a new branch

[40thieves]

As mentioned in the top comment, the simplest strategy is probably to always branch from the existing branch, i.e. the week-2 branch will be based on the week-1 branch.

But has some advantages:

• Trainees are unlikely to "get stuck" on the wrong branch, as they can always create a new branch

This has some disadvantages:

• It's not very "realistic" in regards to real-world Git usage
• The diff will include unrelated changes, since by default Github will compare against main not the "true" base branch. However this can be changed, as long as we teach trainees how to do this correctly

[40thieves]

Another aspect to consider here is that the React module (and potentially the Node & Databases modules) extend the work from previous weeks. In this model, checking out to main would "lose" all the work from the previous week.

Because of this we will may need to teach multiple branching strategies. But at which point in the course should we introduce each strategy?

[SallyMcGrath]

My thoughts from the call:

https://github.com/CodeYourFuture/Portfolio is a repo that they will work on for 9-12 months, so is a good opportunity to slowly introduce more git complexity.

If we create a roadmap and add one new thing per module, our roadmap will look something like

INDUCTION: fork and pr
HTML-CSS : 4 discrete projects, 1 branch per project (one a week)
JS1: ???
JS2: ???
JS3: ???
React: branch from branch, 1 project over 4 weeks
Node: ???
Databases: 3 discrete projects, 1 branch per project (one a week) PLUS : Full Stack Assessment, see #224
Final Projects: Small scoped feature branching

[40thieves]

This was discussed in a Tech Ed Syllabus team meeting on 31st Aug.

The branch-from-branch strategy isn't the most "realistic" strategy, so are we teaching trainees bad habits via this strategy? The only real benefits for React & Node to follow this strategy are that trainees don't have to npm install a bunch of dependencies each week - but this is only once per-week, so perhaps the tradeoff isn't worthwhile.

On the flip-side, the "feature branch-esque" strategy (1 branch per week) is more "realistic" and is ultimately closer to the branching strategy we want trainees to follow in final projects (1 branch per change).

We therefore concluded that the best next steps here would be to explore switching the React & Node modules to a feature branch strategy. The React module already needs some work to move to the 4 week model. However React/Node are not our focus at the moment (we want to complete the JS modules re-work first) and aren't urgent in the sense that we have any cohorts close to starting the module. So we'll park this for now.

We also decided to add some instructions to the HTML/CSS coursework to explain how to switch to main and create a new branch.