Skip to content

Commit 055b9e7

Browse files
MetOffice#39 Modifies the lesson to work on one repo throughout
1 parent 72e560b commit 055b9e7

Some content is hidden

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

54 files changed

+462
-376
lines changed

config.yaml

+3-2
Original file line numberDiff line numberDiff line change
@@ -17,11 +17,11 @@ title: 'Git Working Practices'
1717
created: '2024-11-11'
1818

1919
# Comma-separated list of keywords for the lesson
20-
keywords: 'software, data, lesson, The Carpentries'
20+
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: 'pre-alpha'
24+
life_cycle: 'alpha'
2525

2626
# License of the lesson materials (recommended CC-BY 4.0)
2727
license: 'CC-BY 4.0'
@@ -59,6 +59,7 @@ contact: '[email protected]'
5959

6060
# Order of episodes in your lesson
6161
episodes:
62+
- 00-repo-access.md
6263
- 01-issues.md
6364
- 02-branching.md
6465
- 03-feature-branch.md

episodes/00-repo-access.md

+65
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
---
2+
title: Repository Access
3+
teaching: 10
4+
exercises: 0
5+
---
6+
7+
::::::::::::::::::::::::::::::::::::::: objectives
8+
9+
- Know how to give a collaborator access to your repository.
10+
11+
::::::::::::::::::::::::::::::::::::::::::::::::::
12+
13+
:::::::::::::::::::::::::::::::::::::::: questions
14+
15+
- What levels of repository permissions are there?
16+
17+
::::::::::::::::::::::::::::::::::::::::::::::::::
18+
19+
To be able to contribute to the `git-training-demo`
20+
repository your instructors will have to give you access.
21+
They are going to showcase this now.
22+
The steps are:
23+
24+
In the repository page on GitHub, click the "Settings"
25+
button on the right, select "Collaborators",
26+
click "Add people", and enter a username/s.
27+
28+
![A screenshot of the GitHub Collaborators settings page for a public personal repository, which is accessed by clicking "Settings" then "Collaborators".](fig/github-add-collaborators.png){alt='A screenshot of the GitHub Collaborators settings page, which is accessed by clicking "Settings" then "Collaborators".'}
29+
30+
To accept access to the repository, you will
31+
need to go to [https://github.com/notifications](https://github.com/notifications)
32+
or check for an email notification.
33+
Once there you can accept access to the repository.
34+
35+
## Permission Levels
36+
37+
### Personal Repositories
38+
39+
Repositories on personal accounts only have
40+
two levels of permissions, the Owner and Collaborators[^permission-personal].
41+
To use the branching model in this lesson you would need
42+
adding as a collaborator.
43+
You can still contribute to a public repository without being added
44+
as a collaborator by using the forking model.
45+
46+
[^permission-personal]: The [GitHub documentation](https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-user-account-settings/permission-levels-for-a-personal-account-repository) has more information on
47+
permissions for a repository on a personal account.
48+
49+
### Organisational Repositories
50+
51+
Repositories in organisations have more levels of permissions[^permission-org].
52+
Team members require at least **write** access to use the branching model.
53+
For all lower levels of access use the forking model.
54+
55+
[^permission-org]: The [GitHub Documentation](https://docs.github.com/en/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/repository-roles-for-an-organization) has more information on the
56+
different permission levels for repositories in organisations.
57+
58+
:::::::::::::::::::::::::::::::::::::::: keypoints
59+
60+
- On a repository you own or are an admin on navigate to
61+
[`https://github.com/<organisation>/<repository>/settings/access`](https://github.com/<organisation>/<repository>/settings/access)
62+
to control access for collaborators.
63+
- You can give individuals or teams access to a repository.
64+
65+
::::::::::::::::::::::::::::::::::::::::::::::::::

episodes/01-issues.md

+66-9
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
title: Issues
33
teaching: 10
4-
exercises: 0
4+
exercises: 5
55
---
66

77
::::::::::::::::::::::::::::::::::::::: objectives
@@ -14,6 +14,7 @@ exercises: 0
1414
:::::::::::::::::::::::::::::::::::::::: questions
1515

1616
- What information should go on an Issue?
17+
- What are Issue templates?
1718

1819
::::::::::::::::::::::::::::::::::::::::::::::::::
1920

@@ -31,23 +32,79 @@ Here's some advice for writing good Issues:
3132
- Break up large Issues into several small ones and or
3233
use checklists to track tasks in the Issue
3334

34-
![](fig/github-issue.png){alt='A screenshot of a GitHub Issue.'}
35+
Open an Issue on the `git-training-demo` repository
36+
to add a file stating your favourite cloud type.
37+
38+
Navigate to the **Issues** tab:
39+
40+
![](fig/github-fork-issue-open.png){alt='A screenshot of the git-training-demo repository showing the Issues view.'}
41+
42+
This repositories Issue tab looks different to the `weather`
43+
repository you worked on in the Introduction to Git & GitHub lesson.
44+
It uses [Issue templates](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository)
45+
to provide templates for bugs and feature requests.
46+
Click on the green **Get started** button next to the
47+
**Feature request** option:
48+
49+
![](fig/github-fork-issue-1.jpeg){alt='A screenshot of the git-training-demo repository showing an Issue being opened. The template has automatically added text to the description and labelled the Issue as an enhancement.'}
50+
51+
You can see the Issue has text in the description already.
52+
This is from the template which provides a consistent
53+
structure to the Issues on this repo.
54+
The template has also added the `enhancement` label for you.
55+
56+
Add in a clear title such as
57+
"Add mo-fitzroy's favourite cloud type",
58+
replace 'mo-fitzroy' with your GitHub username.
59+
Click **Submit new issue**.
60+
61+
::::::::::::::::::::::::::::::::::::: instructor
62+
63+
It's a good idea to remind learners that
64+
images can be dropped straight into the
65+
Issue description.
66+
An image of a cloud should do!
67+
68+
::::::::::::::::::::::::::::::::::::::::::::::::
69+
70+
### Projects, milestones, and labels
71+
72+
Your instructor has set up a Project and some custom milestones
73+
for you to add to your Issue.
74+
75+
- [Labels](https://docs.github.com/en/issues/using-labels-and-milestones-to-track-work/managing-labels)
76+
help you classify Issues and PRs.
77+
- [Milestones](https://docs.github.com/en/issues/using-labels-and-milestones-to-track-work/about-milestones)
78+
group Issues and PRs, tracking their progress towards a common milestone automatically.
79+
- [Projects](https://docs.github.com/en/issues/planning-and-tracking-with-projects/learning-about-projects/about-projects)
80+
are a tool for planning and tracking work via GitHub.
81+
Multiple repositories can be linked to a single project.
82+
Projects can have multiple views depending on your needs;
83+
some have kanban boards and gantt charts, others separate out
84+
an individual colleagues Issues to avoid clutter.
3585

3686
::::::::::::::::::::::::::::::::::::::: challenge
3787

38-
## Creating an Issue
88+
## Assign yourself, a project, and a milestone to your Issue
3989

40-
Practice opening up an Issue on your `weather` repository.
41-
Your Issue will be a feature request for the shipping forecast.
90+
On the right hand side of the Issue you can:
4291

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
92+
1. Assign yourself to the Issue so that others know
93+
you are working on it.
94+
2. Add the Issue to a Project by clicking on the cog
95+
next to the Projects section. (If you don't see a project
96+
related to the training you might not have been granted permissions,
97+
ask your instructors for help)
98+
3. Assign the Issue to a milestone.
4699

47100
::::::::::::::::::::::::::::::::::::::::::::::::::
48101

49102
:::::::::::::::::::::::::::::::::::::::: keypoints
50103

51-
- Issues are used to track and plan work
104+
- Issues are used to track and plan work.
105+
- Issue templates provide template text
106+
for the first comment for new Issues of various types.
107+
They can auto-label Issues and encourage collaborators
108+
to give plenty of detail.
52109

53110
::::::::::::::::::::::::::::::::::::::::::::::::::

episodes/02-branching.md

+3-3
Original file line numberDiff line numberDiff line change
@@ -226,9 +226,9 @@ You can find more information using the links below:
226226

227227
:::::::::::::::::::::::::::::::::::::::: keypoints
228228

229-
- A clearly communicated branching model helps developers
230-
- For small projects use the Feature Branch flow
229+
- A clearly communicated branching model helps developers.
230+
- For small projects use the Feature Branch flow.
231231
- For larger projects or those with external collaborators use
232-
forks with feature branches
232+
forks with feature branches.
233233

234234
::::::::::::::::::::::::::::::::::::::::::::::::::

0 commit comments

Comments
 (0)