Skip to content

Commit 42dfd0a

Browse files
actions-useractions-user
committed
markdown source builds
Auto-generated via `{sandpaper}` Source : e3cd0be Branch : main Author : Dimitrios Theodorakis <[email protected]> Time : 2024-11-19 16:45:09 +0000 Message : Adds in the pre-commit and rebase episode updates (MetOffice#3) * Adds instructions for instructors on how to set up the git-training-demo repo * Adds in the optional episode 09 on pre-commit hooks.
1 parent 70deb76 commit 42dfd0a

File tree

82 files changed

+3979
-0
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

82 files changed

+3979
-0
lines changed

Diff for: ‎01-issues.md

+53
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
---
2+
title: Issues
3+
teaching: 10
4+
exercises: 0
5+
---
6+
7+
::::::::::::::::::::::::::::::::::::::: objectives
8+
9+
- Create an Issue with the correct labels.
10+
- Assign yourself to an Issue.
11+
12+
::::::::::::::::::::::::::::::::::::::::::::::::::
13+
14+
:::::::::::::::::::::::::::::::::::::::: questions
15+
16+
- What information should go on an Issue?
17+
18+
::::::::::::::::::::::::::::::::::::::::::::::::::
19+
20+
GitHub Issues (tickets) are where you plan and track work.
21+
You can assign individuals to Issues and label them with a
22+
relevant tag such as `bug` or `enhancement`.
23+
Before opening a new Issue check whether there is already
24+
one open for the feature or bug by using GitHub's search.
25+
26+
Here's some advice for writing good Issues:
27+
28+
- Be clear and concise, provide plenty of detail
29+
- State the expected outcomes
30+
- Tag relevant collaborators
31+
- Break up large Issues into several small ones and or
32+
use checklists to track tasks in the Issue
33+
34+
![](fig/github-issue.png){alt='A screenshot of a GitHub Issue.'}
35+
36+
::::::::::::::::::::::::::::::::::::::: challenge
37+
38+
## Creating an Issue
39+
40+
Practice opening up an Issue on your `weather` repository.
41+
Your Issue will be a feature request for the shipping forecast.
42+
43+
1. Make sure you give the Issue an accurate title and description
44+
2. Assign a label to the Issue
45+
3. Assign yourself to the Issue
46+
47+
::::::::::::::::::::::::::::::::::::::::::::::::::
48+
49+
:::::::::::::::::::::::::::::::::::::::: keypoints
50+
51+
- Issues are used to track and plan work
52+
53+
::::::::::::::::::::::::::::::::::::::::::::::::::

Diff for: ‎02-branching.md

+234
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,234 @@
1+
---
2+
title: Branching Models
3+
teaching: 10
4+
exercises: 0
5+
---
6+
7+
::::::::::::::::::::::::::::::::::::::: objectives
8+
9+
- Describe the Feature Branch and Forking models.
10+
11+
::::::::::::::::::::::::::::::::::::::::::::::::::
12+
13+
:::::::::::::::::::::::::::::::::::::::: questions
14+
15+
- Which branching model is best for me?
16+
17+
::::::::::::::::::::::::::::::::::::::::::::::::::
18+
19+
In the git-novice lesson you learnt how to develop features
20+
on a branch and use a pull-request to merge the changes
21+
back into the `main` branch. You were unknowingly using
22+
a Git branching model called **feature branch workflow**.
23+
24+
As a reminder, we develop on branches to ensure that our development code
25+
doesn't affect the production code on the `main` branch.
26+
Branches also allow your team to develop features in parallel.
27+
28+
A branching model (sometimes also called strategies or workflows) is the model your team adopts when writing, merging and deploying code when using a version control system.
29+
It is a set of rules that you must follow which outline how
30+
your team and collaborators interact with a shared codebase.
31+
32+
Having a clear model helps avoid merge conflicts, more on that later,
33+
and clearly sets out to new collaborators how they can contribute
34+
to your repository.
35+
36+
In this and the following episodes, we will outline some of the branching models that teams use in order to organize their work.
37+
We will look at their pros and cons and help decide which model you should
38+
choose based on your teams needs.
39+
40+
A branching model aims to:
41+
42+
- Enhance productivity by ensuring proper coordination among developers
43+
- Enable parallel development
44+
- Help organize a series of planned, structured releases
45+
- Map a clear path when making changes from development through to production
46+
- Maintain a bug-free code where developers can quickly fix issues and get these changes back to production without disrupting the development workflow
47+
48+
## Git Branching Models
49+
50+
Some version control systems are more geared towards certain branching models.
51+
When using git you have a wide range of models to pick from.
52+
This means the first rule when collaborating using git is:
53+
“Talk about your branching model.”
54+
55+
A repositories `CONTRIBUTING` file may include details of their branching model.
56+
This information might also be in a repositories `README` file.
57+
If in doubt ask!
58+
You can also look at how other people appear to be contributing to the repository.
59+
60+
Below are a few models:
61+
62+
-----------------------------------------
63+
64+
### Feature Branch
65+
66+
In this model every small change or “feature” gets its own branch
67+
where the developers make changes.
68+
Once the feature is done, they submit a pull request and
69+
merge it into the `main` branch after review.
70+
Feature branches should be relatively short-lived.
71+
72+
#### Pros
73+
74+
- Each feature is developed away from `main` so you don't affect production code
75+
- Multiple features can be developed in parallel feature branches
76+
- It's a simple model that's easy for those new to git and your project
77+
- Easy to set up with continuous integration testing and deployment
78+
79+
#### Cons
80+
81+
- If you don't regularly merge changes to `main` into your feature branch
82+
it can become outdated, leading to merge conflicts
83+
- You may struggle if you need to maintain multiple production versions
84+
simultaneously in the same repository
85+
86+
The Feature Branch model is sometimes called GitHub Flow.
87+
88+
```mermaid
89+
---
90+
config:
91+
gitGraph:
92+
showCommitLabel: false
93+
---
94+
gitGraph
95+
accDescr {A git graph showing four branches including the default
96+
<code>main</code> branch.
97+
Each circle is a commit.
98+
A circle with an outline but no fill colour is a merge commit
99+
where one branch has been merged into another.
100+
The two feature branches and the <code>bug_fix</code> branch
101+
all branch off of <code>main</code> at the same commit.
102+
The <code>bug_fix</code> and <code>small_feature</code> branches
103+
are merged back into <code>main</code> after
104+
being developed on their branches.
105+
The <code>large_feature</code> branch merges in the
106+
changes to <code>main</code> to fix any conflicts
107+
before the feature is ready to be merged
108+
back into the <code>main</code> branch via a pull request.}
109+
commit
110+
branch bug_fix
111+
checkout main
112+
branch small_feature
113+
checkout main
114+
branch large_feature
115+
checkout bug_fix
116+
commit
117+
checkout large_feature
118+
commit
119+
checkout main
120+
merge bug_fix
121+
checkout small_feature
122+
commit
123+
checkout large_feature
124+
commit
125+
checkout small_feature
126+
commit
127+
checkout main
128+
merge small_feature
129+
checkout large_feature
130+
commit
131+
merge main
132+
checkout main
133+
merge large_feature
134+
```
135+
136+
-----------------------------------------
137+
138+
### Forking
139+
140+
In this model you make a [**fork**](https://gitprotect.io/blog/git-forking-workflow/) (copy) of the whole repository you want
141+
to contribute to on GitHub in your personal space.
142+
You develop your changes using this fork.
143+
When a change is ready you open a pull request to contribute the changes
144+
back to the original repository.
145+
146+
#### Pros
147+
148+
- Removes the need to give all collaborators adequate permissions
149+
on your repository
150+
- Only project maintainers can approve new code
151+
- You can use any other model within your main repository and
152+
forks to develop changes
153+
154+
-----------------------------------------
155+
156+
### Git Flow
157+
158+
In this model the main development occurs in a `develop` branch.
159+
Feature branches are created from this `develop` branch.
160+
When the `develop` branch is ready for a release,
161+
you create a `release` branch which is then tested and
162+
merged onto the `develop` and `main` branches.
163+
164+
#### Pros
165+
166+
- There is a clear purpose for each branch
167+
- Handles complex projects well
168+
169+
#### Cons
170+
171+
- Very steep learning curve, not suitable for novices
172+
173+
```mermaid
174+
gitGraph
175+
accDescr {A git graph showing the GitFlow model.}
176+
commit tag:"0.1"
177+
branch hotfix
178+
checkout main
179+
branch release
180+
branch develop
181+
checkout hotfix
182+
commit
183+
checkout develop
184+
commit
185+
branch small_feature
186+
checkout develop
187+
merge hotfix
188+
branch large_feature
189+
checkout small_feature
190+
commit
191+
checkout large_feature
192+
commit
193+
commit
194+
checkout main
195+
merge hotfix tag:"0.2"
196+
checkout small_feature
197+
commit
198+
checkout develop
199+
merge small_feature
200+
checkout release
201+
merge develop
202+
checkout large_feature
203+
commit
204+
checkout release
205+
commit
206+
commit
207+
checkout main
208+
merge release tag:"1.0"
209+
checkout develop
210+
merge release
211+
```
212+
213+
## Recommendations
214+
215+
For small projects using a Feature Branch model is normally sufficient.
216+
If your team is large, or you expect external collaborators to contribute
217+
then we recommend developing using forks.
218+
Most open source projects require you to submit new code using a fork.
219+
The next few episodes will guide you through examples of both models.
220+
221+
This wasn't an exhaustive list of branching models!
222+
You can find more information using the links below:
223+
224+
- [From Novice to Pro: Understanding Git Branching Strategies, GitProtect](https://gitprotect.io/blog/from-novice-to-pro-understanding-git-branching-models/)
225+
- [What is a Git workflow?, GitLab](https://about.gitlab.com/topics/version-control/what-is-git-workflow/#forking-git-workflow)
226+
227+
:::::::::::::::::::::::::::::::::::::::: keypoints
228+
229+
- A clearly communicated branching model helps developers
230+
- For small projects use the Feature Branch flow
231+
- For larger projects or those with external collaborators use
232+
forks with feature branches
233+
234+
::::::::::::::::::::::::::::::::::::::::::::::::::

0 commit comments

Comments
 (0)