diff --git a/config.yaml b/config.yaml index 297bf7d..7d3a201 100644 --- a/config.yaml +++ b/config.yaml @@ -17,11 +17,11 @@ title: 'Git Working Practices' created: '2024-11-11' # Comma-separated list of keywords for the lesson -keywords: 'software, data, lesson, The Carpentries' +keywords: 'software, data, lesson, The Carpentries, Git, GitHub' # Life cycle stage of the lesson # possible values: pre-alpha, alpha, beta, stable -life_cycle: 'pre-alpha' +life_cycle: 'alpha' # License of the lesson materials (recommended CC-BY 4.0) license: 'CC-BY 4.0' @@ -59,6 +59,7 @@ contact: 'd.theodorakis@metoffice.gov.uk' # Order of episodes in your lesson episodes: +- 00-repo-access.md - 01-issues.md - 02-branching.md - 03-feature-branch.md diff --git a/episodes/00-repo-access.md b/episodes/00-repo-access.md new file mode 100644 index 0000000..5557c4e --- /dev/null +++ b/episodes/00-repo-access.md @@ -0,0 +1,65 @@ +--- +title: Repository Access +teaching: 10 +exercises: 0 +--- + +::::::::::::::::::::::::::::::::::::::: objectives + +- Know how to give a collaborator access to your repository. + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::: questions + +- What levels of repository permissions are there? + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +To be able to contribute to the `git-training-demo` +repository your instructors will have to give you access. +They are going to showcase this now. +The steps are: + +In the repository page on GitHub, click the "Settings" +button on the right, select "Collaborators", +click "Add people", and enter a username/s. + +![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".'} + +To accept access to the repository, you will +need to go to [https://github.com/notifications](https://github.com/notifications) +or check for an email notification. +Once there you can accept access to the repository. + +## Permission Levels + +### Personal Repositories + +Repositories on personal accounts only have +two levels of permissions, the Owner and Collaborators[^permission-personal]. +To use the branching model in this lesson you would need +adding as a collaborator. +You can still contribute to a public repository without being added +as a collaborator by using the forking model. + +[^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 +permissions for a repository on a personal account. + +### Organisational Repositories + +Repositories in organisations have more levels of permissions[^permission-org]. +Team members require at least **write** access to use the branching model. +For all lower levels of access use the forking model. + +[^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 +different permission levels for repositories in organisations. + +:::::::::::::::::::::::::::::::::::::::: keypoints + +- On a repository you own or are an admin on navigate to + [`https://github.com///settings/access`](https://github.com///settings/access) + to control access for collaborators. +- You can give individuals or teams access to a repository. + +:::::::::::::::::::::::::::::::::::::::::::::::::: diff --git a/episodes/01-issues.md b/episodes/01-issues.md index e864b19..1d48a82 100644 --- a/episodes/01-issues.md +++ b/episodes/01-issues.md @@ -1,7 +1,7 @@ --- title: Issues teaching: 10 -exercises: 0 +exercises: 5 --- ::::::::::::::::::::::::::::::::::::::: objectives @@ -14,6 +14,7 @@ exercises: 0 :::::::::::::::::::::::::::::::::::::::: questions - What information should go on an Issue? +- What are Issue templates? :::::::::::::::::::::::::::::::::::::::::::::::::: @@ -31,23 +32,79 @@ Here's some advice for writing good Issues: - Break up large Issues into several small ones and or use checklists to track tasks in the Issue -![](fig/github-issue.png){alt='A screenshot of a GitHub Issue.'} +Open an Issue on the `git-training-demo` repository +to add a file stating your favourite cloud type. + +Navigate to the **Issues** tab: + +![](fig/github-fork-issue-open.png){alt='A screenshot of the git-training-demo repository showing the Issues view.'} + +This repositories Issue tab looks different to the `weather` +repository you worked on in the Introduction to Git & GitHub lesson. +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) +to provide templates for bugs and feature requests. +Click on the green **Get started** button next to the +**Feature request** option: + +![](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.'} + +You can see the Issue has text in the description already. +This is from the template which provides a consistent +structure to the Issues on this repo. +The template has also added the `enhancement` label for you. + +Add in a clear title such as +"Add mo-fitzroy's favourite cloud type", +replace 'mo-fitzroy' with your GitHub username. +Click **Submit new issue**. + +::::::::::::::::::::::::::::::::::::: instructor + +It's a good idea to remind learners that +images can be dropped straight into the +Issue description. +An image of a cloud should do! + +:::::::::::::::::::::::::::::::::::::::::::::::: + +### Projects, milestones, and labels + +Your instructor has set up a Project and some custom milestones +for you to add to your Issue. + +- [Labels](https://docs.github.com/en/issues/using-labels-and-milestones-to-track-work/managing-labels) + help you classify Issues and PRs. +- [Milestones](https://docs.github.com/en/issues/using-labels-and-milestones-to-track-work/about-milestones) + group Issues and PRs, tracking their progress towards a common milestone automatically. +- [Projects](https://docs.github.com/en/issues/planning-and-tracking-with-projects/learning-about-projects/about-projects) + are a tool for planning and tracking work via GitHub. + Multiple repositories can be linked to a single project. + Projects can have multiple views depending on your needs; + some have kanban boards and gantt charts, others separate out + an individual colleagues Issues to avoid clutter. ::::::::::::::::::::::::::::::::::::::: challenge -## Creating an Issue +## Assign yourself, a project, and a milestone to your Issue -Practice opening up an Issue on your `weather` repository. -Your Issue will be a feature request for the shipping forecast. +On the right hand side of the Issue you can: -1. Make sure you give the Issue an accurate title and description -2. Assign a label to the Issue -3. Assign yourself to the Issue +1. Assign yourself to the Issue so that others know +you are working on it. +2. Add the Issue to a Project by clicking on the cog +next to the Projects section. (If you don't see a project +related to the training you might not have been granted permissions, +ask your instructors for help) +3. Assign the Issue to a milestone. :::::::::::::::::::::::::::::::::::::::::::::::::: :::::::::::::::::::::::::::::::::::::::: keypoints -- Issues are used to track and plan work +- Issues are used to track and plan work. +- Issue templates provide template text + for the first comment for new Issues of various types. + They can auto-label Issues and encourage collaborators + to give plenty of detail. :::::::::::::::::::::::::::::::::::::::::::::::::: diff --git a/episodes/02-branching.md b/episodes/02-branching.md index 7d0195c..ceaaf63 100644 --- a/episodes/02-branching.md +++ b/episodes/02-branching.md @@ -226,9 +226,9 @@ You can find more information using the links below: :::::::::::::::::::::::::::::::::::::::: keypoints -- A clearly communicated branching model helps developers -- For small projects use the Feature Branch flow +- A clearly communicated branching model helps developers. +- For small projects use the Feature Branch flow. - For larger projects or those with external collaborators use - forks with feature branches + forks with feature branches. :::::::::::::::::::::::::::::::::::::::::::::::::: diff --git a/episodes/03-feature-branch.md b/episodes/03-feature-branch.md index acda4bf..feb52dc 100644 --- a/episodes/03-feature-branch.md +++ b/episodes/03-feature-branch.md @@ -14,116 +14,84 @@ exercises: 0 :::::::::::::::::::::::::::::::::::::::: questions - How can I use version control to collaborate with other people? +- What are Pull Request templates? :::::::::::::::::::::::::::::::::::::::::::::::::: In this episode we will use the Feature Branch model -to contribute to each others repositories. +to contribute to the `git-training-demo` repository. -You will need to get into pairs. -One person will be the "Owner" and the other -will be the "Collaborator". -The goal is for the Collaborator to add changes into -the Owner's repository. -We will switch roles at the end, so both persons will -play Owner and Collaborator. +You will need to get into pairs +so that you can review each others code changes. +Your instructor may have already paired you +with another learner. -While working together be sure to share what you -are doing with your partner. +## Cloning a Repository -::::::::::::::::::::::::::::::::::::::::: callout - -## Practicing By Yourself - -If you're working through this lesson on your own, you can carry on by opening -a second terminal window. -This window will represent your partner, working on another computer. You -won't need to give anyone access on GitHub, because both 'partners' are you. - -:::::::::::::::::::::::::::::::::::::::::::::::::: - -## Repository Access - -The Owner needs to give the Collaborator access. -In your repository page on GitHub, click the "Settings" -button on the right, select "Collaborators", -click "Add people", and -then enter your partner's username. - -![](fig/github-add-collaborators.png){alt='A screenshot of the GitHub Collaborators settings page, which is accessed by clicking "Settings" then "Collaborators"'} - -To accept access to the Owner's repo, the Collaborator -needs to go to [https://github.com/notifications](https://github.com/notifications) -or check for an email notification. -Once there they can accept access to the Owner's repo. - -## Cloning a Repo - -Next, the Collaborator needs to download a copy of the -Owner's repository to their machine. -This is called "cloning a repo". - -The Collaborator doesn't want to overwrite their own version of `climate`, so -needs to clone the Owner's repository to a different location than their own -repository with the same name. - -To clone the Owner's repository into their `Desktop` folder, the Collaborator enters: +You will both need to download a copy of the `git-training-demo` repository. +This is called "cloning a repository". ```bash -$ git clone git@github.com:mo-eormerod/weather.git ~/Desktop/mo-eormerod-weather +$ cd ~/Desktop ``` -Replace 'mo-eormerod' with the Owner's username. +```bash +$ git clone git@github.com:metoffice/git-training-demo.git +``` -If you choose to clone without the clone path -(`~/Desktop/mo-eormerod-weather`) specified at the end, -you will clone inside your own weather folder! Make sure to navigate to the `Desktop` folder first. ![](fig/github-collaboration.svg){alt='A diagram showing that "git clone" can create a copy of a remote GitHub repository, allowing a second person to create their own local repository that they can make changes to.'} ## Feature Branches -The Collaborator can now make a change in their clone of the Owner's repository. -We will use a feature branch in the same way as we've been doing before: +You can now make changes to the `git-training-demo` repository +using your clone. +We will use a feature branch to develop our change on: ```bash -$ cd ~/Desktop/mo-eormerod-weather -$ git switch -c 3_shipping-forecast +$ cd git-training-demo +$ git switch -c 1_favourite_cloud ``` ```output -Switched to branch '3_shipping-forecast' +Switched to branch '1_favourite_cloud' ``` Notice the name of the branch is prefixed by the -number `3`. This is the Issue number of the Issue the Owner -created on their repository. +number `1`. This is the Issue number of the Issue +you created in Episode 2 Issues. Your team may choose a different naming convention such as prefixing the branch name by `feature`, `bug` etc. +Add in a new file `cloud-mo-fitzroy.md`, +replace `mo-fitzroy` with your username: + ```bash -$ nano shipping-forecast.md -$ cat shipping-forecast.md +$ nano cloud-mo-fitzroy.md +$ cat cloud-mo-fitzroy.md ``` ```output -New high expected Dover 1028 by 0600 tomorrow. -Low Trafalgar 1013 losing its identity +# My Favourite Cloud + +Light and fluffy cumulus. ``` +Add and commit your changes: + ```bash -$ git add shipping-forecast.md -$ git commit -m "Add in the shipping forecast" +$ git add cloud-mo-fitzroy.md +$ git commit -m "Adds Robert Fitzroy's favourite cloud" ``` ```output -[3_shipping-forecast 17a1454] Add in the shipping forecast - 1 file changed, 2 insertions(+) - create mode 100644 shipping-forecast.md +[1_favourite_cloud b7f26e6] Adds Robert Fitzroy's favourite cloud + 1 file changed, 3 insertions(+) + create mode 100644 cloud-mo-fitzroy.md ``` -Then push the change to the *Owner's repository* on GitHub: +Then push the changes to GitHub: ```bash $ git push @@ -133,33 +101,64 @@ $ git push Enumerating objects: 4, done. Counting objects: 100% (4/4), done. Delta compression using up to 4 threads -Compressing objects: 100% (3/3), done. -Writing objects: 100% (3/3), 382 bytes | 191.00 KiB/s, done. +Compressing objects: 100% (2/2), done. +Writing objects: 100% (3/3), 357 bytes | 178.00 KiB/s, done. Total 3 (delta 1), reused 0 (delta 0), pack-reused 0 remote: Resolving deltas: 100% (1/1), completed with 1 local object. remote: -remote: Create a pull request for '3_shipping-forecast' on GitHub by visiting: -remote: https://github.com/mo-eormerod/weather/pull/new/3_shipping-forecast +remote: Create a pull request for '1_favourite_cloud' on GitHub by visiting: +remote: https://github.com/MetOffice/git-training-demo/pull/new/1_favourite_cloud remote: -To github.com:mo-eormerod/weather.git - * [new branch] 3_shipping-forecast -> 3_shipping-forecast -branch '3_shipping-forecast' set up to track 'origin/3_shipping-forecast'. +To github.com:metoffice/git-training-demo.git + * [new branch] 1_favourite_cloud -> 1_favourite_cloud +branch '1_favourite_cloud' set up to track 'origin/1_favourite_cloud'. ``` Note that we didn't have to create a remote called `origin`: Git uses this -name by default when we clone a repository. (This is why `origin` was a -sensible choice earlier when we were setting up remotes by hand.) +name by default when we clone a repository. +This is why `origin` was a sensible choice +in the git-novice lesson when we were setting up remotes by hand. + +Take a look at the repository on GitHub again, and you should be +able to see the `1_favourite_cloud` branch. +You may need to refresh your browser to see the new branch. + +::::::::::::::::::::::::::::::::::::::::: spoiler + +## fatal: no upstream branch + +If you see a message similar to the following: + +```output +fatal: The current branch 1_favourite_cloud has no upstream branch. +To push the current branch and set the remote as upstream, use + + git push --set-upstream origin 1_favourite_cloud + +To have this happen automatically for branches without a tracking +upstream, see 'push.autoSetupRemote' in 'git help config'. +``` + +You will need to set the name of the upstream GitHub branch using +the recommended `git push` command. + +You can get git to automatically set the upstream branch. +This avoids having to run git push with the --set-upstream flag +the first time you push from a new branch. + +Change your git config using: -Take a look at the Owner's repository on GitHub again, and you should be -able to see the `3_shipping-forecast` branch and this -new commit made by the Collaborator. -You may need to refresh your browser to see the new commit. +```bash +$ git config --global push.autoSetupRemote true +``` + +:::::::::::::::::::::::::::::::::::::::::::::::::: ::::::::::::::::::::::::::::::::::::::::: spoiler ## Some more about remotes -In this episode and the previous one, our local repository has had +In this episode and in the git-novice lesson, our local repository only had a single "remote", called `origin`. A remote is a copy of the repository that is hosted somewhere else, that we can push to and pull from, and there's no reason that you have to work with only one. For example, @@ -168,9 +167,10 @@ account (you'd probably call this `origin`) and also the main "upstream" project repository (let's call this `upstream` for the sake of examples). You would pull from `upstream` from time to time to get the latest updates that other people have committed. +We will practice using an `upstream` repository later in the forking model. Remember that the name you give to a remote only exists locally. It's -an alias that you choose - whether `origin`, or `upstream`, or `mo-eormerod` - +an alias that you choose - whether `origin`, or `upstream`, or `mo-fitzroy` - and not something intrinsic to the remote repository. The `git remote` family of commands is used to set up and alter the remotes @@ -186,7 +186,7 @@ associated with a repository. Here are some of the most useful ones: account, or from GitHub to a different hosting service. Or, if we made a typo when adding it! - `git remote rename [oldname] [newname]` changes the local alias by which a remote - is known - its name. For example, one could use this to change `upstream` to `mo-eormerod`. + is known - its name. For example, one could use this to change `upstream` to `mo-fitzroy`. :::::::::::::::::::::::::::::::::::::::::::::::::: @@ -197,30 +197,30 @@ In the git-novice lesson you practised opening a [pull request](https://www.astropython.com/git-novice/10-pull-requests.html). You should see a notification appear on GitHub telling you the -`3_shipping-forecast` branch had recent pushes. +`1_favourite_cloud` branch had recent pushes. The Collaborator should click on the green **Compare & pull request** button to open the PR. -If you don't see this notification click on the branches dropdown -, the button showing `main`, -and click on the `3_shipping-forecast` branch. +If you don't see this notification click on the branches dropdown, +the button showing `main`, +and click on the `1_favourite_cloud` branch. ![](fig/feature-branch-1.png){alt='A screenshot of the GitHub weather repository showing the branch selection dropdown.'} -You should now see the Code view for the `3_shipping-forecast` branch +You should now see the Code view for the `1_favourite_cloud` branch and a **Contribute** button. Click on the **Contribute** button and select the green **Open pull request** option. -![](fig/feature-branch-2.png){alt='A screenshot of the GitHub weather repository showing code view for the 3_shipping-forecast branch. The Contribute dropdown is expanded to show the Open pull request option.'} +![](fig/feature-branch-2.png){alt='A screenshot of the GitHub weather repository showing code view for the 1_favourite_cloud branch. The Contribute dropdown is expanded to show the Open pull request option.'} You may have noticed when running `git push` -on the `3_shipping-forecast` branch for the first time +on the `1_favourite_cloud` branch for the first time the output contained: ```output -remote: Create a pull request for '3_shipping-forecast' on GitHub by visiting: -remote: https://github.com/mo-eormerod/weather/pull/new/3_shipping-forecast +remote: Create a pull request for '1_favourite_cloud' on GitHub by visiting: +remote: https://github.com/MetOffice/git-training-demo/pull/new/1_favourite_cloud ``` You could have also followed this link to create a new PR. @@ -230,31 +230,107 @@ against the target branch (usually `main`). When the changes are ready for review you can mark the PR as **Ready for review**. +## Pull Request Templates + +Notice the description has filled with a template. +Just like this repository used Issue templates it +also uses a [PR template](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/creating-a-pull-request-template-for-your-repository). + +This template has a checklist that needs to be +completed before opening the PR[^pr-checklist]. +It also has checklists for science and code review. +In the description scroll down to the checklists +which look like this: + +```md +- [ ] I have read `CONTRIBUTING.md` and added my name as a Code Contributor. +``` + +Some open source projects require you to add your name +to a list of contributors. +We will do this later so for now mark the task as complete. +Replace the space in the square checkbox brackets with an `x` +to mark the task as complete: + +```md +- [x] I have read `CONTRIBUTING.md` and added my name as a Code Contributor. +``` + +Now when you open the PR it should look something like this: + +![](fig/github-fork-pr-1.jpeg){alt='A screenshot of a users pull request from their fork back to the upstream git-training-demo repository.'} + +This image shows PR number `#8`. +This PR will close/fix Issue number `#7` (the top left arrow). +You can request a review on the top right. +Some repositories will be set up to automatically assign +a reviewer based on how many reviews each team member +currently has open[^auto-assign-pr-review]. +The bottom arrow shows the checklist items we marked as complete. + +At the bottom of your PR you can see that a review is required +before merging. +All checks have passed, this repository has automatic checks +for trailing whitespace, accidentally adding large files etc. +More information can be found in the optional episode on +[pre-commit hooks](./09-pre-commit.md). + ### Automatically closing Issues via PRs -This PR adds in the shipping forecast which we have an open Issue for. A PR can automatically close an Issue when it is merged into `main`. -To use this GitHub functionality add: +To use this GitHub functionality +replace the templates `Fixes <#ISSUE_NUMBER>` line with either: + +```md +Closes #1 +``` + +or ```md -Closes #3 +Fixes #1 ``` -To the first comment of the PR, -change `3` to the Issue number of the Issue the Owner -created on their repository. +Make sure you change `1` to your Issue number. The [GitHub Documentation](https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/linking-a-pull-request-to-an-issue) has more information on linking PRs to Issues. In the next episode we will look at how these changes are reviewed and merged back into `main` in more detail. +::::::::::::::::::::::::::::::::::::::: challenge + +## Assign a Reviewer + +Assign the other learner in your pair as the reviewer +by clicking on the cog to the right of the Reviewers section. + +On the right hand side of the PR you can also: + +1. Assign yourself to the PR. +2. Add labels to the PR. +3. Add the PR to a Project by clicking on the cog +next to the Projects section. (If you don't see a project +related to the training you might not have been granted permissions, +ask your instructors for help) +4. Assign the PR to a milestone. + +:::::::::::::::::::::::::::::::::::::::::::::::::: + :::::::::::::::::::::::::::::::::::::::: keypoints -- Add collaborators to your repository by going to the repository **Settings** then the **Collaborators** tab. - Cloning a repository gives you a local copy of the repository: `git clone ` - Automatically close Issues when a PR is merged by adding a `Closes #` line to the first comment in the PR. +- Pull Request templates provide template text + for the first comment for new Issues of various types, + and Pull Requests. + They can auto-label Issues and encourage collaborators + to give plenty of detail. :::::::::::::::::::::::::::::::::::::::::::::::::: + +[^pr-checklist]: You can also open a draft PR and then edit the top +comment to mark the checklist tasks as completed. +[^auto-assign-pr-review]: The [GitHub Documentation](https://docs.github.com/en/organizations/organizing-members-into-teams/managing-code-review-settings-for-your-team) has more information on automatically assigning reviewers. diff --git a/episodes/04-review.md b/episodes/04-review.md index d9ffc73..60850b6 100644 --- a/episodes/04-review.md +++ b/episodes/04-review.md @@ -20,15 +20,13 @@ exercises: 10 In this section we will explore how to properly review code and suggest changes if necessary. -We will continue to work in pairs. -The Owner should navigate back to their own `weather` repository. -You should see an open PR from your Collaborator. +Make sure you know who is in your pair. +Find your colleagues open PR on the `git-training-demo` +repository using the Pull Requests tab +or find the request for review in your notifications. ## Reviewing Changes -As the Owner make sure you are on the PR your Collaborator has opened -on your repository. - You can add general science and code review comments in the **Conversation** tab. To review specific files go to the **Files changed** tab: @@ -36,7 +34,7 @@ To review specific files go to the **Files changed** tab: ![](fig/pr-1.png){alt='A screenshot of a PR showing the diff in the Files changed tab. The diff is shown with Split view.'} This tab shows a diff (difference) between your feature branch, -`3_shipping-forecast`, and the target branch, `main`. +`1_favourite_cloud`, and the target branch, `main`. Your diff might look different, to swap between ***Unified*** and ***Split*** view click on the cog dropdown: @@ -70,7 +68,9 @@ Click on the file icon or press Ctrl+g: ![](fig/pr-suggestion.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 with a suggestion.'} -Now click on the green **Finish your review** button, +Click on the green **Start a review** button. +Now click on the green button in the top right which says +**Finish your review** or **Review Changes**, add a comment, and select **Request changes**. When you're finished click the green **Submit review** button. @@ -82,7 +82,7 @@ The PRs **Conversation** tab now looks like this: ## Responding to Review -Now it is the Collaborators turn to respond to the review. +Now you will respond to the review on the PR that you opened. You can see merging is blocked because our reviewer has requested changes. You also have the option to commit the @@ -92,23 +92,28 @@ In the popup add a description then click on **Commit changes**: ![](fig/pr-review-2.png){alt='A screenshot of a PR showing the Conversation tab with a review that has requested changes.'} -You could have also committed the change to your feature branch -using your local copy and then marked the conversation with -the suggested change as resolved. +You could have also committed the suggested changes +to your feature branch using your local copy, +pushed the changes to GitHub +and then marked the conversation with the suggested change as resolved. + +Re-request a review by clicking on the two arrows forming a circle +next to the reviewers name at the top of the PR. ## Approving Changes -Now the Owner can respond to the Collaborators final changes. +Head back to your partners PR, if they re-requested a review +you will have received another notification. The Conversation tab should update to show the suggestion as -**Outdated** because it has been resolved by the Collaborator. +**Outdated** because it has been resolved. It also gives you the option to view the new changes since your last review. ![](fig/pr-review-3.png){alt='A screenshot of a PR showing the Conversation tab with a requested change that has been resolved.'} Click on the **View changes** button. If you are happy that -the Collaborator has addressed your requested changes then +your requested changes have been addressed then you can approve the PR: ![](fig/pr-review-4.png){alt='A screenshot of a PR showing the Files changed tab showing how to Approve a review.'} @@ -131,17 +136,17 @@ You can now delete the branch from GitHub by pressing the Some repositories will be automatically set up to delete the feature branch after a PR is successfully merged. -If you head back to the main page of your repository, -the code view shows our new file `shipping-forecast.md`. +If you head back to the main page of the `git-training-demo` +repository you will see your new file in the code view for the `main` branch. The commit message for the PR merge is shown next to it. -If you hover over the PR number (in this case `#4`) +If you hover over the PR number (in this case `#2`) a popup will appear with details of the merged PR. Click on the number to take you to the closed PR. ![](fig/pr-review-7.png){alt='A screenshot of the weather repositories main Code tab showing the files in the main branch. The new shipping-forecast.md file can be seen with the commit message from the PR squash and merge commit that created it. The PR number, #4, link is being hovered over to display a popup with brief details of PR #4.'} Head over to the repositories **Issues** tab. -Check that your Issue for adding the shipping forecast +Check that your Issue for adding your favourite cloud file was closed when you merged the PR. ::::::::::::::::::::::::::::::::::::::: challenge @@ -152,20 +157,16 @@ In the [git-novice](https://www.astropython.com/git-novice/10-pull-requests.html lesson you learnt how to pull changes and clean up your branches after merging a PR. -The Collaborator can now: +You can now: -1. Update their local copy of the `weather` repository +1. Update your local copy of the `git-training-demo` repository 2. Delete any branches that are no longer necessary -The Owner can now: - -1. Update their local copy of the `weather` repository - ::::::::::::::: solution ## Solution -1. Update your local copy of the `weather` repository +1. Update your local copy of the `git-training-demo` repository ```bash $ git switch main @@ -177,14 +178,14 @@ remote: Enumerating objects: 4, done. remote: Counting objects: 100% (4/4), done. remote: Compressing objects: 100% (3/3), done. remote: Total 3 (delta 1), reused 0 (delta 0), pack-reused 0 (from 0) -Unpacking objects: 100% (3/3), 1.11 KiB | 87.00 KiB/s, done. -From github.com:mo-eormerod/weather - e4bdab8..ed14d18 main -> origin/main -Updating e4bdab8..ed14d18 +Unpacking objects: 100% (3/3), 1.07 KiB | 20.00 KiB/s, done. +From github.com:metoffice/git-training-demo + 39720d8..9bdd3b8 main -> origin/main +Updating 39720d8..9bdd3b8 Fast-forward - shipping-forecast.md | 2 ++ - 1 file changed, 2 insertions(+) - create mode 100644 shipping-forecast.md + cloud-mo-fitzroy.md | 3 +++ + 1 file changed, 3 insertions(+) + create mode 100644 cloud-mo-fitzroy.md ``` 2. Delete any branches that are no longer necessary @@ -195,32 +196,22 @@ $ git remote prune origin ```output Pruning origin -URL: git@github.com:mo-eormerod/weather.git - * [pruned] origin/3_shipping-forecast +URL: git@github.com:metoffice/git-training-demo.git + * [pruned] origin/1_favourite_cloud ``` ```bash -$ git branch -D 3_shipping-forecast +$ git branch -D 1_favourite_cloud ``` ```output -Deleted branch 3_shipping-forecast (was 17a1454). +Deleted branch 1_favourite_cloud (was b7f26e6). ``` ::::::::::::::::::::::::: :::::::::::::::::::::::::::::::::::::::::::::::::: -::::::::::::::::::::::::::::::::::::::: challenge - -## Switch Roles and Repeat - -Switch roles. Repeat the process of making changes -on a feature branch and reviewing the changes -(episodes [03](./03-feature-branch.md) and [04](./04-review.md)). - -:::::::::::::::::::::::::::::::::::::::::::::::::: - :::::::::::::::::::::::::::::::::::::::: keypoints - A Pull Request (PR) is where your code and science review takes place. diff --git a/episodes/05-forks.md b/episodes/05-forks.md index 18f6183..ae7e92f 100644 --- a/episodes/05-forks.md +++ b/episodes/05-forks.md @@ -14,77 +14,33 @@ exercises: 0 :::::::::::::::::::::::::::::::::::::::: questions - What is a fork? -- What are Issue and Pull Request templates? :::::::::::::::::::::::::::::::::::::::::::::::::: Most open source projects require new collaborators to -contribute via their personal **fork** of the repository. +contribute via a **fork** of the repository. A fork is simply a copy of the repository that you make -on the server, in our GitHub, side. +on the server, in our case GitHub, side. This avoids having to give repository permissions to -every single collaborator. +every single collaborator[^access-private]. + +[^access-private]: If the repository is private collaborators will +need to be given access to see the repository and create a fork. +The same is true for private repositories in organisations. In this episode we will create a fork and contribute a change to the main GitHub repository using the feature branch model we have been practising. -Your instructor will give you a link to the `git-training-demo` -repository you will be forking. -This is the **upstream** repository for you fork. +We will continue working on the `git-training-demo` repository. +Your permissions have been reduced so that you can no longer push +to the main Met Office repository, you will have to use a fork! +The main Met Office repository is now the **upstream** repository for you fork. ## Open an Issue -Remember we track our work with Issues. -Open an Issue on the `git-training-demo` repository -to add a file stating your favourite cloud type. - -Navigate to the **Issues** tab: - -![](fig/github-fork-issue-open.png){alt='A screenshot of the git-training-demo repository showing the Issues view.'} - -This repositories Issue tab looks different. -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) -to provide templates for bugs and feature requests. -Click on the green **Get started** button next to the -**Feature request** option: - -![](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.'} - -You can see the Issue has text in the description already. -This is from the template which provides a consistent -structure to the Issues on this repo. -The template has also added the `enhancement` label for you. - -Add in a clear title such as -"Add mo-fitzroy's favourite cloud type", -replace 'mo-fitzroy' with your GitHub username. -Click **Submit new issue**. - -::::::::::::::::::::::::::::::::::::: instructor - -It's a good idea to remind learners that -images can be dropped straight into the -Issue description. -An image of a cloud should do! - -:::::::::::::::::::::::::::::::::::::::::::::::: - -### Projects, milestones, and labels - -Your instructor has set up a Project and some custom milestones -for you to add to your Issue. - -- [Labels](https://docs.github.com/en/issues/using-labels-and-milestones-to-track-work/managing-labels) - help you classify Issues and PRs. -- [Milestones](https://docs.github.com/en/issues/using-labels-and-milestones-to-track-work/about-milestones) - group Issues and PRs, tracking their progress towards a common milestone automatically. -- [Projects](https://docs.github.com/en/issues/planning-and-tracking-with-projects/learning-about-projects/about-projects) - are a tool for planning and tracking work via GitHub. - Multiple repositories can be linked to a single project. - Projects can have multiple views depending on your needs; - some have kanban boards and gantt charts, others separate out - an individual colleagues Issues to avoid clutter. +Open a new issue like you did earlier to add more detail to +your favourite cloud file. ## Create a Fork @@ -118,47 +74,44 @@ upstream repository. ## Make Changes -You will be using this fork to make changes using -the feature branch model from the previous episodes. -Clone your fork, replace `mo-fitzroy` with your username: +To avoid overwriting your local version of the original Met Office +`git-training-demo` repository you need to clone +your fork to a different location. + +To clone the repository into your `Desktop` folder: ```bash -$ git clone git@github.com:mo-fitzroy/git-training-demo.git +$ git clone git@github.com:mo-fitzroy/git-training-demo.git ~/Desktop/mo-fitzroy-git-training-demo ``` +Replace 'mo-fitzroy' with the Owner's username. + +If you choose to clone without the clone path +(`~/Desktop/mo-fitzroy-weather`) specified at the end, +you will clone inside the `git-training-demo` folder! + ```output -Cloning into 'git-training-demo'... -remote: Enumerating objects: 47, done. -remote: Counting objects: 100% (47/47), done. -remote: Compressing objects: 100% (44/44), done. -remote: Total 47 (delta 3), reused 0 (delta 0), pack-reused 0 (from 0) -Receiving objects: 100% (47/47), 17.07 KiB | 1.07 MiB/s, done. -Resolving deltas: 100% (3/3), done. +Cloning into '~/Desktop/mo-fitzroy-git-training-demo'... +remote: Enumerating objects: 16, done. +remote: Counting objects: 100% (16/16), done. +remote: Compressing objects: 100% (16/16), done. +remote: Total 16 (delta 1), reused 11 (delta 0), pack-reused 0 (from 0) +Receiving objects: 100% (16/16), 5.01 KiB | 1.00 MiB/s, done. +Resolving deltas: 100% (1/1), done. ``` Create your feature branch: ```bash -$ cd git-training-demo -$ git switch -c 1_add-favourite-cloud +$ cd ~/Desktop/mo-fitzroy-git-training-demo +$ git switch -c 2_update_favourite_cloud ``` ```output -Switched to a new branch '1_add-favourite-cloud' +Switched to a new branch '2_update_favourite_cloud' ``` -::: callout - -## Branch Names - -Some colleagues prefix the branch name -with the Issue number as shown above. -This helps remind you what the branch is for! - -::: - -Add in a new file `cloud-mo-fitzroy.md`, -replace `mo-fitzroy` with your username: +Add more detail to your favourite cloud file: ```bash $ nano cloud-mo-fitzroy.md @@ -169,21 +122,21 @@ $ cat cloud-mo-fitzroy.md # My Favourite Cloud Light and fluffy cumulus. +Nice to sail under. ``` Add and commit your changes: ```bash $ git add cloud-mo-fitzroy.md -$ git commit -m "Adds Robert Fitzroy's favourite cloud" +$ git commit -m "Adds more details to Robert FitzRoy's favourite cloud file" ``` ```output -[1_add-favourite-cloud a3c5e13] "Adds Robert Fitzroy's favourite cloud" - 1 file changed, 3 insertions(+) - create mode 100644 cloud-mo-fitzroy.md +[2_update_favourite_cloud 1b05798] Adds more details to Robert FitzRoy's favourite cloud file + 1 file changed, 1 insertion(+) ``` -Push your changes to your GitHub fork: +Push the changes to your GitHub fork: ```bash $ git push @@ -194,12 +147,16 @@ Enumerating objects: 5, done. Counting objects: 100% (5/5), done. Delta compression using up to 4 threads Compressing objects: 100% (3/3), done. -Writing objects: 100% (3/3), 354 bytes | 354.00 KiB/s, done. -Total 3 (delta 2), reused 0 (delta 0), pack-reused 0 -remote: Resolving deltas: 100% (2/2), completed with 2 local objects. +Writing objects: 100% (3/3), 369 bytes | 123.00 KiB/s, done. +Total 3 (delta 1), reused 0 (delta 0), pack-reused 0 +remote: Resolving deltas: 100% (1/1), completed with 1 local object. +remote: +remote: Create a pull request for '2_update_favourite_cloud' on GitHub by visiting: +remote: https://github.com/mo-fitzroy/git-training-demo/pull/new/2_update_favourite_cloud +remote: To github.com:mo-fitzroy/git-training-demo.git - f87bb5c..a3c5e13 1_add-favourite-cloud -> 1_add-favourite-cloud -branch '1_add-favourite-cloud' set up to track 'origin/1_add-favourite-cloud'. + * [new branch] 2_update_favourite_cloud -> 2_update_favourite_cloud +branch '2_update_favourite_cloud' set up to track 'origin/2_update_favourite_cloud'. ``` ## Open a Pull Request @@ -207,58 +164,14 @@ branch '1_add-favourite-cloud' set up to track 'origin/1_add-favourite-cloud'. Head back to your fork on GitHub and open a PR to contribute your changes upstream to the main `git-training-demo` repository. +You must use the **Fixes** keyword this time to automatically close +your Issue when the PR is merged since you are contributing the change +from a Fork[^link-pr-issue]. -![](fig/github-fork-pr-open.jpeg){alt='A screenshot of a user opening a pull request from their fork back to the upstream git-training-demo repository. The description has been autofilled with the pull request template contents.'} - -Notice the description has filled with a template. -Just like this repository used Issue templates it -also uses a [PR template](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/creating-a-pull-request-template-for-your-repository). - -Check the Issue you opened earlier for the Issue number. -`mo-fitzroy` checks theirs and it was Issue `#1`. -So he changes the line `Fixes <#ISSUE_NUMBER>` to `Fixes #1`. -This will automatically close Issue 1 when the PR is merged. -We use the keyword `Fixes` here instead of the `Closes` -keyword we used before because this PR comes from a fork[^link-issue-pr]. - -This template has a checklist that needs to be -completed before opening the PR[^pr-checklist]. -It also has checklists for science and code review. -In the description scroll down to the checklists -which look like this: - -```md -- [ ] I have read `CONTRIBUTING.md` and added my name as a Code Contributor. -``` - -Some open source projects require you to add your name -to a list of contributors. -We will do this later so for now mark the task as complete. -Replace the space in the square checkbox brackets with an `x` -to mark the task as complete: - -```md -- [x] I have read `CONTRIBUTING.md` and added my name as a Code Contributor. -``` - -Now when you open the PR it should look something like this: - -![](fig/github-fork-pr-1.jpeg){alt='A screenshot of a users pull request from their fork back to the upstream git-training-demo repository.'} - -This image shows PR number `#8`. -This PR will close/fix Issue number `#7` (the top left arrow). -You can request a review on the top right. -Some repositories will be set up to automatically assign -a reviewer based on how many reviews each team member -currently has open[^auto-assign-pr-review]. -The bottom arrow shows the checklist items we marked as complete. +[^link-pr-issue]: The [GitHub Documentation](https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/linking-a-pull-request-to-an-issue) has more information +on linking PRs to Issues. -At the bottom of your PR you can see that a review is required -before merging. -All checks have passed, this repository has automatic checks -for trailing whitespace, accidentally adding large files etc. -More information can be found in the optional episode on -[pre-commit hooks](./09-pre-commit.md). +![](fig/github-fork-pr-open.jpeg){alt='A screenshot of a user opening a pull request from their fork back to the upstream git-training-demo repository. The description has been autofilled with the pull request template contents.'} The PR will now need to be approved and merged by your instructors. @@ -346,7 +259,7 @@ To github.com:mo-fitzroy/git-training-demo.git ``` Your forks `main` branch is now up to date with the -main `git-training-demo` repositories `main` branch. +original `git-training-demo` repositories `main` branch. ::: callout @@ -360,27 +273,17 @@ shown earlier: If your fork is **behind** the upstream repository GitHub will alert you on the banner. You can use the **Sync fork** button to update your fork like we did above. -After syncing your fork this way you only need to run `git pull` +After syncing your fork this way run `git pull` on your local `main` branch. ::: :::::::::::::::::::::::::::::::::::::::: keypoints -- A fork is a server side (in our case GitHub) copy +- A fork is a server side, in our case GitHub, copy of the repository. - Forks allow collaborators to contribute to the main - repository without being given write permissions. -- Issue and Pull Request templates provide template text - for the first comment for new Issues of various types, - and Pull Requests. - They can auto-label Issues and encourage collaborators - to give plenty of detail. + repository without being given + collaborator access or write permissions. :::::::::::::::::::::::::::::::::::::::::::::::::: - -[^link-issue-pr]: The [GitHub Documentation](https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/linking-a-pull-request-to-an-issue) has more information -on linking PRs to Issues. -[^pr-checklist]: You can also open a draft PR and then edit the top -comment to mark the checklist tasks as completed. -[^auto-assign-pr-review]: The [GitHub Documentation](https://docs.github.com/en/organizations/organizing-members-into-teams/managing-code-review-settings-for-your-team) has more information on automatically assigning reviewers. diff --git a/episodes/07-history.md b/episodes/07-history.md index 47cd10b..60975e6 100644 --- a/episodes/07-history.md +++ b/episodes/07-history.md @@ -23,6 +23,13 @@ A more linear history is easier to understand and can be helpful when using certain git commands to explore your history. +Your Git history will look different depending on the merge +strategy you use when merging PRs +and whether you allow merging `main` into a feature branch +like we did in the last episode to resolve the conflict. +It's up to you and your team to decide which strategy is +best for your repository. + ## Viewing History You have already learnt that we can use the @@ -265,6 +272,11 @@ push to the GitHub remote to override your remotes history. The history in this case is linear and retains all the commits which makes it easier to search for a commit that introduced a bug. +Rebasing a feature branch can be difficult / impossible if you have +merged `main` into your feature branch to update it +with the latest changes or resolve conflicts. +You should choose to move your feature branch to the `HEAD` of +`main` using rebasing instead. Your team will decide what approach is right for your project. @@ -274,7 +286,7 @@ for your project. - `git log --decorate --oneline --graph` lets you visualise your repository history in graph form. - There are three options for merging your feature branch into `main`. -- merge: creates a merge commit and results in a non-linear history unless you first rebase your feature branch +- merge: creates a merge commit and results in a non-linear history unless you first rebase your feature branch. - squash and merge: squashes all your feature branch commits into one merge commit on `main`. Your history is linear. - rebase: re-writes your git history so that all the feature branch commits are now on `main`. Your history is linear. diff --git a/episodes/08-rebase.md b/episodes/08-rebase.md index b6e1f4d..ca0e9dc 100644 --- a/episodes/08-rebase.md +++ b/episodes/08-rebase.md @@ -650,7 +650,8 @@ into the previous commit. branch from the remote **before** rebasing. - **Always** check before pushing to the remote after rebasing that no new commits were added - to the remote as these will be lost. + to the remote as these will be lost, + use the `--force-with-lease` flag with `git push` to help prevent this. - Use `git push --force-with-lease` to update the remote branch. diff --git a/episodes/Break.md b/episodes/Break.md index 28672ea..1bd794c 100644 --- a/episodes/Break.md +++ b/episodes/Break.md @@ -3,17 +3,17 @@ title: Break teaching: 0 exercises: 0 --- + You've now used the Feature Branch model to: 1. Open an Issue describing the feature or bug -2. Give collaborators access to your repo -3. Clone another repository -4. Create a branch to develop your changes on -5. Make changes to your working copy -6. Open a Pull Request -7. Review changes -8. Respond to review -9. Merge the Pull Request and close the Issue -10. Tidy up your branches +2. Clone a repository +3. Create a branch to develop your changes on +4. Make changes to your working copy +5. Open a Pull Request +6. Review changes +7. Respond to review +8. Merge the Pull Request and close the Issue +9. Tidy up your branches Take a break - get up and move about. diff --git a/episodes/End.md b/episodes/End.md index 3f9d9bb..5ddf55d 100644 --- a/episodes/End.md +++ b/episodes/End.md @@ -26,5 +26,5 @@ when it comes to GitHub! - In this lesson you saw automated testing of PRs using [GitHub Actions](https://learn.microsoft.com/en-us/training/modules/introduction-to-github-actions/) which you might like to explore more. - The optional [rebasing episode](./08-rebase.md) guides you through rebasing a branch. -- These PR tests ran [pre-commit](https://pre-commit.com/) checks which you can set up locally to run before you commit. +- Your Pull Requests ran automated tests using [pre-commit](https://pre-commit.com/) checks which you can set up locally to run before you commit. The optional [pre-commit episode](./09-pre-commit.md) outlines how to set up some basic checks. diff --git a/episodes/fig/feature-branch-1-dark.png b/episodes/fig/feature-branch-1-dark.png index 7161147..e68ce20 100644 Binary files a/episodes/fig/feature-branch-1-dark.png and b/episodes/fig/feature-branch-1-dark.png differ diff --git a/episodes/fig/feature-branch-1.png b/episodes/fig/feature-branch-1.png index e65d79f..0dedd07 100644 Binary files a/episodes/fig/feature-branch-1.png and b/episodes/fig/feature-branch-1.png differ diff --git a/episodes/fig/feature-branch-2-dark.png b/episodes/fig/feature-branch-2-dark.png index 2a07cbe..4ab7730 100644 Binary files a/episodes/fig/feature-branch-2-dark.png and b/episodes/fig/feature-branch-2-dark.png differ diff --git a/episodes/fig/feature-branch-2.png b/episodes/fig/feature-branch-2.png index 283fa4f..7a3f538 100644 Binary files a/episodes/fig/feature-branch-2.png and b/episodes/fig/feature-branch-2.png differ diff --git a/episodes/fig/github-collaboration.svg b/episodes/fig/github-collaboration.svg index eba7fe7..8ebb969 100644 --- a/episodes/fig/github-collaboration.svg +++ b/episodes/fig/github-collaboration.svg @@ -151,7 +151,7 @@ y="21.6" font-size="10.8" id="tspan4664" - style="font-size:10.80000019px;font-family:Consolas">origin https://github.com/mo-eormerod/weather.git + style="font-size:10.80000019px;font-family:Consolas">origin https://github.com/MetOffice/git-training-demo.git ~/mo-eormerod/weather + style="font-size:13.5px;font-family:Helvetica">~/Desktop/mo-fitzroy/weather https://github.com/mo-eormerod/weather.git + y="278.707">https://github.com/MetOffice/git-training-demo.git origin https://github.com/mo-eormerod/weather.git + x="0">origin https://github.com/MetOffice/git-training-demo.git ~/mo-fitzroy/weather + transform="translate(16,28.707)">~/Desktop/mo-fitzroy/git-training-demo