Skip to content

Commit e1cf5ee

Browse files
actions-userpwhybrawxtimrcomer
committed
markdown source builds
Auto-generated via `{sandpaper}` Source : b7dca18 Branch : main Author : Dimitrios Theodorakis <[email protected]> Time : 2025-03-12 17:04:51 +0000 Message : MetOffice#94 Adds discussion FAQs * Adds discussion FAQs * Emphasise origin and upstream Co-authored-by: pwhybra <[email protected]> * Spelling and word choice fixes Co-authored-by: Tim Pillinger <[email protected]> Co-authored-by: Ruth Comer <[email protected]> * Apply reading age suggestions Co-authored-by: Tim Pillinger <[email protected]> * Add a GitHub docs link for git fetch --------- Co-authored-by: pwhybra <[email protected]> Co-authored-by: Tim Pillinger <[email protected]> Co-authored-by: Ruth Comer <[email protected]>
1 parent f90b55d commit e1cf5ee

14 files changed

+236
-30
lines changed

‎02-branching.md

+103-4
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
title: Branching Models
3-
teaching: 10
4-
exercises: 0
3+
teaching: 15
4+
exercises: 5
55
---
66

77
::::::::::::::::::::::::::::::::::::::: objectives
@@ -91,6 +91,38 @@ Note that all branches and commits exist within the single GitHub, origin reposi
9191
They are visible to anyone who has read access to the repository.
9292
Any contributor can write to any branch that is not explicitly protected.
9393

94+
```mermaid
95+
---
96+
title: Feature Branch Model
97+
---
98+
flowchart TD
99+
accDescr {A flowchart showing the feature branch model.
100+
Here developers work on their local copies of the
101+
GitHub repository. All developers have write access
102+
or higher. Developers work on feature branches,
103+
and push these branches to the origin repository.}
104+
subgraph subGraph0["Remote Server (GitHub)"]
105+
r1[("MetOffice/git-training-demo Origin Repository")]
106+
end
107+
subgraph subGraph1["<div style=margin-top:>Computer 3</div>"]
108+
r2[("Local Repository")]
109+
end
110+
subgraph subGraph2["<div style=margin-top:>Computer 2</div>"]
111+
r3[(" Local Repository")]
112+
end
113+
subgraph subGraph3["<div style=margin-top:>Computer 1</div>"]
114+
r4[("Local Repository")]
115+
end
116+
r1 -- fetch/pull --> r2 & r3 & r4
117+
r2 -. push .-> r1
118+
r3 -. push .-> r1
119+
r4 -. push .-> r1
120+
121+
style subGraph1 fill:#A9640A
122+
style subGraph2 fill:#A9640A
123+
style subGraph3 fill:#A9640A
124+
```
125+
94126
```mermaid
95127
---
96128
config:
@@ -164,6 +196,38 @@ All branches and commits exist within the collaborators fork, not the ***upstrea
164196

165197
Collaborators can use their fork to test more complex changes. For example testing github actions within a dummy-PR.
166198

199+
```mermaid
200+
---
201+
title: Forking + Feature Branch
202+
---
203+
flowchart TB
204+
accDescr {A flowchart showing the use of forks
205+
and the feature branch model.
206+
Here developers work on their forks (GitHub copies, labelled origin) of the
207+
main GitHub repository (upstream).
208+
Developers work on feature branches in their fork,
209+
and push these branches to the origin repository.
210+
Pull requests are used to contribute changes from
211+
the origin to the upstream repository.
212+
Only one developers fork and local repository
213+
are shown in this diagram.}
214+
subgraph top["Remote Server (GitHub)"]
215+
direction LR
216+
r1[("MetOffice/git-training-demo Upstream Repository")]
217+
r2[("username/git-training-demo Origin Repository")]
218+
219+
r2 -. Pull Request .-> r1
220+
end
221+
subgraph bottom["Computer"]
222+
r3[("Local Repository")]
223+
end
224+
r1 -- fetch/pull --> r3
225+
r3 -- push --> r2
226+
r2 -- fetch/pull --> r3
227+
228+
style bottom fill:#A9640A
229+
```
230+
167231
-----------------------------------------
168232

169233
### Git Flow
@@ -226,9 +290,10 @@ merged onto the `develop` and `main` branches.
226290
## Recommendations
227291

228292
For repositories where collaborators are a small and trusted group the Feature Branch
229-
model is normally sufficient.
293+
model is normally sufficient.
294+
295+
A Forking model may be preferable if:
230296

231-
A Forking model is preferable if:
232297
- There are more collaborators, because the number of branches may become unwieldy.
233298
- There are external collaborators whose contribution is valued,
234299
but the repository owners need to retain control of the original.
@@ -244,6 +309,40 @@ You can find more information using the links below:
244309
- [From Novice to Pro: Understanding Git Branching Strategies, GitProtect](https://gitprotect.io/blog/from-novice-to-pro-understanding-git-branching-strategies/)
245310
- [What is a Git workflow?, GitLab](https://about.gitlab.com/topics/version-control/what-is-git-workflow/#forking-git-workflow)
246311

312+
::::::::::::::::::::::::::::::::::::::: challenge
313+
314+
## Terminology
315+
316+
Use the glossary to explain the differences between the following:
317+
318+
- A branch
319+
- A remote
320+
- A fork
321+
322+
::::::::::::::: solution
323+
324+
## Solution
325+
326+
Learners are often confused by the difference
327+
between branches, remotes, and forks.
328+
329+
- Branches are pointers to commits in a repository.
330+
A repository will have multiple branches where
331+
developers can work on features in parallel.
332+
- Remotes are **links** to other repositories.
333+
These remotes usually link to repositories on
334+
cloud platforms such as GitHub.
335+
A repository typically has one or more remotes,
336+
with the first called **origin**.
337+
- A fork is a copy of a repository created on GitHub.
338+
When linking your local repository your fork becomes
339+
the origin remote. The original repository you forked from
340+
becomes the upstream remote.
341+
342+
:::::::::::::::::::::::::
343+
344+
::::::::::::::::::::::::::::::::::::::::::::::::::
345+
247346
:::::::::::::::::::::::::::::::::::::::: keypoints
248347

249348
- A clearly communicated branching model helps developers.

‎03-feature-branch.md

+22
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,28 @@ $ git clone [email protected]:metoffice/git-training-demo.git
5353

5454
Make sure to navigate to the `Desktop` folder first.
5555

56+
::: spoiler
57+
58+
### Commands that communicate between repositories
59+
60+
In the Introduction to Version Control with Git and GitHub
61+
course you learnt that only certain git commands
62+
communicate between repositories.
63+
64+
They were:
65+
66+
- `git fetch`: To fetch changes from a remote.
67+
- `git pull`: To fetch changes from a remote
68+
and merge them into a branch.
69+
- `git push`: To push changes to a remote.
70+
71+
`git clone` also communicates with a remote.
72+
However it is only used once to make a local copy of a remote.
73+
74+
There are also other git commands that interact with remote repositories (e.g. `git ls-remote`), but none that appear in this course.
75+
76+
:::
77+
5678
## Feature Branches
5779

5880
You can now make changes to the `git-training-demo` repository

‎04-review.md

+17-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: Review
3-
teaching: 30
3+
teaching: 60
44
exercises: 10
55
---
66

@@ -89,6 +89,18 @@ Click on the line to add an inline comment:
8989

9090
![](fig/pr-4.png){alt='A screenshot of a PR showing the diff in the Files changed tab. A line has been highlighted to show how to add an inline comment.'}
9191

92+
Inline comments can cover multiple lines.
93+
Click on the first line number then drag your mouse down
94+
to the last line your comment covers.
95+
96+
::::::::::::::::::::::::::::::::::::: instructor
97+
98+
Ensure you show learners how to create multiline comments.
99+
It doesn't matter if learners choose to leave a single
100+
or multiline comment/suggestion for their review.
101+
102+
::::::::::::::::::::::::::::::::::::::::::::::::
103+
92104
You can make suggested changes using inline comments.
93105
Click on the file icon or press <kbd>Ctrl+g</kbd>:
94106

@@ -230,6 +242,10 @@ You should update your local main branch and use `git log --oneline --graph`
230242
to demonstrate the messy history that has been created due to
231243
each learner selecting a random merge strategy in their PRs.
232244

245+
You can also show learners the Network Graph on the Insights tab
246+
in GitHub. This will show the history of the repository and
247+
can be contrasted with forking in the afternoon sessions.
248+
233249
::::::::::::::::::::::::::::::::::::::::::::::::
234250

235251
::::::::::::::::::::::::::::::::::::::: challenge

‎05-forks.md

+4-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: Forks
3-
teaching: 30
3+
teaching: 45
44
exercises: 0
55
---
66

@@ -183,6 +183,9 @@ Take a break here!
183183
This will give you and your co-instructor time
184184
to approve, and squash and merge the PRs.
185185

186+
Show learners the Insights -> Network Graph on GitHub again.
187+
Contrast this to the section of the graph from the morning sessions.
188+
186189
::::::::::::::::::::::::::::::::::::::::::::::::
187190

188191
## Updating a Fork

‎06-conflict.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: Conflicts
3-
teaching: 15
3+
teaching: 30
44
exercises: 0
55
---
66

‎08-rebase.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
title: 'Rebasing'
3-
teaching: 15
4-
exercises: 10
3+
teaching: 60
4+
exercises: 15
55
---
66

77
::::::::::::::::::::::::::::::::::::::: objectives

‎09-pre-commit.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: 'Pre-commit'
3-
teaching: 10
3+
teaching: 15
44
exercises: 10
55
---
66

‎Break.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: Break
3-
teaching: 0
3+
teaching: 60
44
exercises: 0
55
---
66

‎End.md

+23-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: End
3-
teaching: 0
3+
teaching: 10
44
exercises: 0
55
---
66

@@ -15,6 +15,28 @@ if time permits.
1515
Otherwise feel free to work through the episodes
1616
in your own time.
1717

18+
### Decision Time
19+
20+
What will the working practices look like for your repositories?
21+
Things to think about:
22+
23+
- Who needs access to your repos? Should there be a second admin to help you?
24+
Review [Episode 1](../episodes/00-repo-access.md) Repository Access.
25+
- What branching model will you use?
26+
Review [Episode 3](../episodes/03-feature-branch.md) Branching Models.
27+
- Will you use forks with your branching model?
28+
Review [Episode 3 Forks](../episodes/02-branching.md#forking)
29+
- Who presses the merge button as part of a Pull Request,
30+
the developer or the reviewer?
31+
- Will you need Issue and Pull Request templates
32+
or other project management features such as milestones and Projects?
33+
- What automated tests might help your development process?
34+
35+
Don't try and make all these decisions at once!
36+
Revisit the material and seek out further advice if needed before deciding.
37+
Remember you can change your mind anytime and evolve your working practices
38+
as your projects grow.
39+
1840
### Where to next?
1941

2042
We've covered a lot over the last two workshops

‎config.yaml

+3-3
Original file line numberDiff line numberDiff line change
@@ -8,10 +8,10 @@
88
# lc: Library Carpentry
99
# cp: Carpentries (to use for instructor training for instance)
1010
# incubator: The Carpentries Incubator
11-
carpentry: 'swc'
11+
carpentry: 'incubator'
1212

1313
# Overall title for pages.
14-
title: 'Git Working Practices'
14+
title: 'Git and GitHub Working Practices'
1515

1616
# Date the lesson was created (YYYY-MM-DD, this is empty by default)
1717
created: '2024-11-11'
@@ -21,7 +21,7 @@ keywords: 'software, data, lesson, The Carpentries, Git, GitHub'
2121

2222
# Life cycle stage of the lesson
2323
# possible values: pre-alpha, alpha, beta, stable
24-
life_cycle: 'alpha'
24+
life_cycle: 'stable'
2525

2626
# License of the lesson materials (recommended CC-BY 4.0)
2727
license: 'CC-BY 4.0'

‎discuss.md

+26
Original file line numberDiff line numberDiff line change
@@ -4,3 +4,29 @@ title: Discussion
44

55
## Frequently Asked Questions
66

7+
1. Does Git default to origin if you run `git fetch` without origin/upstream?
8+
From the [GitHub documentation](https://git-scm.com/docs/git-fetch):
9+
When no remote is specified, by default the origin remote will be used, unless there’s an upstream branch configured for the current branch.
10+
2. Can you rename the upstream remote?
11+
Yes see the [spoiler on remotes](../episodes/03-feature-branch.md#some-more-about-remotes).
12+
You should note that the names `origin` and `upstream` are just conventions.
13+
You may use any name for the remotes but it may be confusing
14+
for new collaborators who expect origin/upstream.
15+
3. What do you do if you add the wrong remote link?
16+
Change the remote url, or remove the remote and add the remote again.
17+
See the [spoiler on remotes](../episodes/03-feature-branch.md#some-more-about-remotes) for the relevant Git commands.
18+
4. How often should you commit changes?
19+
You learnt in the Introduction to Version Control with Git and GitHub
20+
lesson that commits should occur often and be atomic.
21+
That is contain one small change at a time.
22+
Committing often (at most every couple of hours) and pushing straight after
23+
committing helps avoid losing any work.
24+
5. Can you have chains of forks? Or a colleagues fork as a remote?
25+
Yes to both! Although the latter would be an unusual working practice,
26+
we'd recommend seeking advice before adding a colleague's fork
27+
as another remote on your local repository.
28+
Chains of forks are common. If a GitHub user has read access to your
29+
repository they can create a fork.
30+
6. How many repositories can I have?
31+
"With GitHub Free for personal accounts and organizations, you can work with unlimited collaborators on unlimited public repositories with a full feature set, or unlimited private repositories with a limited feature set."
32+
[About repositories - GitHub Docs](https://docs.github.com/en/repositories/creating-and-managing-repositories/about-repositories)

‎instructor-notes.md

+6
Original file line numberDiff line numberDiff line change
@@ -84,6 +84,12 @@ link Issues they create on the `git-training-demo` repository to.
8484
You can name this Project **Git & GitHub WP**.
8585
Give the `git-and-github-training` team permissions on the GitHub Project.
8686

87+
### Timings
88+
89+
You will find there is more content before the break than after.
90+
This means for a days workshop Episode 5 Review will spill
91+
over into the afternoon.
92+
8793
### [Introduction](../index.md)
8894

8995
Use the following text as a guide for your intro,

‎md5sum.txt

+13-13
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,23 @@
11
"file" "checksum" "built" "date"
22
"CODE_OF_CONDUCT.md" "c93c83c630db2fe2462240bf72552548" "site/built/CODE_OF_CONDUCT.md" "2024-11-19"
33
"LICENSE.md" "b24ebbb41b14ca25cf6b8216dda83e5f" "site/built/LICENSE.md" "2024-11-19"
4-
"config.yaml" "a0157ab76adc733800b01dccf01125b6" "site/built/config.yaml" "2025-02-26"
4+
"config.yaml" "599542a1187010d5f84b19fc56d69116" "site/built/config.yaml" "2025-03-12"
55
"index.md" "4f0b01239324c43e254def95f89923a9" "site/built/index.md" "2025-01-20"
66
"episodes/00-repo-access.md" "2467b2af26577b9c11ac300706e8558c" "site/built/00-repo-access.md" "2025-03-03"
77
"episodes/01-issues.md" "f22fad38ef9a49a94df0d58619afdf2c" "site/built/01-issues.md" "2025-02-26"
8-
"episodes/02-branching.md" "4c1ea5d3b2a27714d1063d0c552ee7e9" "site/built/02-branching.md" "2025-02-27"
9-
"episodes/03-feature-branch.md" "da5cd3362da0d68d23730ad1d486f7ed" "site/built/03-feature-branch.md" "2025-03-03"
10-
"episodes/04-review.md" "db6c731c1e6ff113cea69eda75a4c00f" "site/built/04-review.md" "2025-03-12"
11-
"episodes/Break.md" "3f756cfaee9cc1c397381668102aaea0" "site/built/Break.md" "2025-01-10"
8+
"episodes/02-branching.md" "0f57a1f6011a5ada367b8d2ca1b18efb" "site/built/02-branching.md" "2025-03-12"
9+
"episodes/03-feature-branch.md" "a79c0865056d9d42e5bc2d548baf4b13" "site/built/03-feature-branch.md" "2025-03-12"
10+
"episodes/04-review.md" "224586834b4e258ed66d5dfdfcea9988" "site/built/04-review.md" "2025-03-12"
11+
"episodes/Break.md" "a7ea33ad6508dcd0a2ed14e3affefbff" "site/built/Break.md" "2025-03-12"
1212
"episodes/07-history.md" "ef281c80f9126ca785bfa170e8c27a62" "site/built/07-history.md" "2025-02-27"
13-
"episodes/05-forks.md" "b8ec1e10b8ce0513086cc32693865559" "site/built/05-forks.md" "2025-03-12"
14-
"episodes/06-conflict.md" "a4365117d4de8ba82e8696d4a2bfeb3c" "site/built/06-conflict.md" "2025-02-27"
15-
"episodes/End.md" "42f2019c55b38db5ec0eab909b6bca4d" "site/built/End.md" "2025-01-09"
16-
"episodes/08-rebase.md" "c968e3b7973b5cafa1b0b5b3a9721242" "site/built/08-rebase.md" "2025-02-27"
17-
"episodes/09-pre-commit.md" "99096b6d10f4f7c1f6f5bfa72f728e45" "site/built/09-pre-commit.md" "2024-12-02"
18-
"instructors/instructor-notes.md" "ea8646b0d153b93f42e0a7dff1b1747b" "site/built/instructor-notes.md" "2025-02-26"
19-
"learners/discuss.md" "aaef6991af918125ae722d3ce4e36443" "site/built/discuss.md" "2024-11-19"
13+
"episodes/05-forks.md" "54170ba7d4b0673c40347980c0a1acff" "site/built/05-forks.md" "2025-03-12"
14+
"episodes/06-conflict.md" "141a62b9e9e9dacd628ccde00532c65b" "site/built/06-conflict.md" "2025-03-12"
15+
"episodes/End.md" "f7758fde70d72c9d855a64dc620d581e" "site/built/End.md" "2025-03-12"
16+
"episodes/08-rebase.md" "ac037185668e46d869191082dcf62c6c" "site/built/08-rebase.md" "2025-03-12"
17+
"episodes/09-pre-commit.md" "d24fc6425428b269e51f5c8e2da61b6d" "site/built/09-pre-commit.md" "2025-03-12"
18+
"instructors/instructor-notes.md" "5ebcf8a0981f49ead6b41cb95281092b" "site/built/instructor-notes.md" "2025-03-12"
19+
"learners/discuss.md" "7589b1934f2f3968de1764673e5f23cf" "site/built/discuss.md" "2025-03-12"
2020
"learners/fcm-git_cheat_sheet.md" "a90c25c1218a18430dd67a243e63533e" "site/built/fcm-git_cheat_sheet.md" "2024-11-19"
21-
"learners/reference.md" "d976a57639fa49361d9c8431850cde6a" "site/built/reference.md" "2024-11-19"
21+
"learners/reference.md" "1ef5a79f1182d422ea6a7f0766c33db0" "site/built/reference.md" "2025-03-12"
2222
"learners/setup.md" "462ca0801200cc01c164d857821ade82" "site/built/setup.md" "2025-02-28"
2323
"profiles/learner-profiles.md" "637cf5fe68afa1af6ce393717126f011" "site/built/learner-profiles.md" "2025-01-09"

0 commit comments

Comments
 (0)