diff --git a/.gitignore b/.gitignore index bd87454..14077f8 100644 --- a/.gitignore +++ b/.gitignore @@ -49,3 +49,4 @@ docs/ # translation temp files po/*~ +.DS_Store diff --git a/episodes/branches.md b/episodes/branches.md index ef31111..9e83b18 100644 --- a/episodes/branches.md +++ b/episodes/branches.md @@ -25,8 +25,7 @@ exercises: 15 Branches are independent development lines. Working independently, you can likely get away with using git without creating any branches, as in the first diagram in the figure below. However, when you begin to work with others, branches allow team members to work on the code without impacting the work of other developers or users. -![Figure showing three graph diagrams representing different repository states. Each is a graph consisting of vertices (circles) and directed edges (arrows) where each horizontal path is a branch. The first shows a single path representing a repository with a single main branch, the second has two branches, a main and a feature branch, and the third has three branches, a main and two feature branches.](../fig/branches/branches.png){alt="" width="75%"} -*These graph diagrams show repositories with different numbers of branches. The vertices, or circles, in these graphs show different commits, and each horizontal path is a branch. The first shows a repository with 1 main branch, the second a repository with 1 main and 1 feature branch, and the third repository 1 main and 2 feature branches.* +![These graph diagrams show repositories with different numbers of branches. The vertices, or circles, in these graphs show different commits, and each horizontal path is a branch. The first shows a repository with 1 main branch, the second a repository with 1 main and 1 feature branch, and the third repository 1 main and 2 feature branches.](../fig/branches/branches.png){alt='Graph diagram of nodes/circles and edges/arrows representing repository state. Each horizontal path is a branch. The first shows a single path representing a repository with a single main branch, the second has two branches, a main and a feature branch, and the third has three branches, a main and two feature branches.' width="75%"} Branches can have a few different purposes. Branches created to develop a specific feature are referred to as feature branches, and are often short-lived. Branches can also be used for longer-term purposes, such as having separate development and production branches. How you organize and use branches in your project is referred to as a branching strategy, which we will cover more when we talk about git workflows. @@ -51,11 +50,9 @@ git checkout -b my_new_branch This will create the branch `my_new_branch` and move you to the new branch. If you run `git status` at this point it will display `On branch my_new_branch`. Making and committing any changes will only update `my_new_branch`. -![Figure showing the process of creating a branch. First a graph diagram of a repository is shown with two commits on the main branch. To the left is an arrow with the text "git checkout -b my_branch" followed by the same repository with the new feature branch added. A smiley face is used on each diagram to show where you are in the repository, the first has it on the second commit in the main branch, the second on the feature branch.](../fig/branches/create_branch.png){alt="" width="75%"} -*Creating a new branch. When you run `git checkout -b my_branch` your new branch gets created and checked out, meaning you are now on your new branch (represented by the smiley face). Any commits you make will be on this branch until you checkout another one.* +![Creating a new branch. When you run `git checkout -b my_branch` your new branch gets created and checked out, meaning you are now on your new branch (represented by the star). Any commits you make will be on this branch until you checkout another one.](../fig/branches/create_branch.png){alt='Figure showing the process of creating a branch. From left to right: a repository with two commits on the main branch, followed by an arrow with the text "git checkout -b my_branch" followed by the same repository with the new feature branch added. A star is used on each repository to show which commit you are on, the first has it on the second commit in the main branch, the second on the first commit of the feature branch.' width="75%"} -![Figure creating commits on a branch. First a graph diagram of a repository is shown with two commits on the main branch and one on a feature branch. To the left is an arrow with the text "git commit (x2)", followed by the same repository with to additional commits on the feature branch. A smiley face is used on each diagram to show where you are in the repository, each on the last commit on the feature branch.](../fig/branches/commit_branch.png){alt="" width="75%"} -*Every time you run the `git commit` command the commit will be added to your current branch.* +![Every time you run the `git commit` command the commit will be added to your current branch.](../fig/branches/commit_branch.png){alt='Figure showing creating commits on a branch. From left to right: a repository with two commits on the main branch and one on a feature branch, followed by an arrow with the text "git commit (x2)", followed by the same repository with to additional commits on the feature branch. A star is used on each diagram to show where you are in the repository, each on the last commit on the feature branch.' width="75%"} The first time you push your branch to the remote repository, you will need to publish the branch by running run: @@ -75,8 +72,7 @@ git checkout main Remember, if you aren't sure which branch you are on you can run `git status`. It is good practice before you start making changes to any of your files to check that you are on the right branch with `git status`, particularly if you haven't touched the code recently. -![Figure showing the process of changing, or checking out a branch. First a graph diagram of a repository is shown with two commits on the main branch and three on the feature branch. A smiley face is on the third commit of the feature branch to show the current location. To the left is an arrow with the text "git checkout main" followed by the same repository with the smiley face now on the second commit in the main branch.](../fig/branches/checkout_branch.png){alt="" width="85%"} -*Switching branches using `git checkout`.* +![Switching branches using `git checkout`.](../fig/branches/checkout_branch.png){alt='Figure showing The process of changing, or checking out a branch. From left to right: a repository with two commits on the main branch and three on the feature branch with current location on the third commit of the feature branch, followed by an arrow with the text "git checkout main”, followed by the same repository with the current location now on the second commit in the main branch.' width="85%"} ### Merging Branches @@ -89,8 +85,8 @@ git merge main will merge any changes introduced to `main` into the `my_new_branch`. Merging in this direction is especially useful when you've been working on `my_new_branch` for a while and `main` has changed in the meantime. -![Figure showing the process of merging the main branch into the feature branch. First a graph diagram of a repository is shown with a main and feature branch. The feature branch with three commits splits off the main branch after two commits, and the main branch has an additional two commits after the split. A smiley face is on the third commit of the feature branch to show the current location. Below is an arrow with the text "git merge main" followed by the same repository with a new arrow from the last commit on the main branch to a new commit on the feature branch, showing the changes from the main branch have been merged into the changes on the feature branch.](../fig/branches/merge_into_branch.png){alt="" width="60%"} -*Merging new commits from the main branch into the feature branch with `git merge main`.* +![Merging new commits from the main branch into the feature branch with `git merge main`.](../fig/branches/merge_into_branch.png){alt='Figure showing the process of merging the main branch into the feature branch. On the top is a repository with a main and feature branch. The feature branch starts at the second commit on the main branch and has three commits, and the main branch has an additional two commits after the split. The current location is the third commit of the feature branch. Below is an arrow with the text "git merge main" followed by the same repository with a new arrow from the last commit on the main branch to a new commit on the feature branch, showing the changes from the main branch have been merged into the changes on the feature branch.' width="60%"} + When development is complete on `my_new_branch`, it would be merged into `main`: @@ -99,8 +95,7 @@ git checkout main git merge my_new_branch ``` -![Figure showing the process of merging the feature branch into the main branch. First a graph diagram of a repository is shown with a main and feature branch. The feature branch with three commits splits off the main branch after two commits. A smiley face is on the second commit of the main branch to show the current location. Below is an arrow with the text "git merge my_branch" followed by the same repository a new commit on the main branch with two arrows from the main and feature branches, showing the changes from the feature branch have been merged into main branch.](../fig/branches/merge_into_main.png){alt="" width="50%"} -*Merging new commits the feature branch into the main branch with `git merge my_branch`.* +![Merging new commits the feature branch into the main branch with `git merge my_branch`.](../fig/branches/merge_into_main.png){alt='Figure showing the process of merging the feature branch into the main branch. On the top is a repository with a main and feature branch. The feature branch starts at the second commit on the main branch and has three commits. The current location is on the second commit of the main branch. Below is an arrow with the text "git merge my_branch" followed by the same repository with a new commit on the main branch that has two incoming arrows from the main and feature branches, showing the changes from the feature branch have been merged into main branch.' width="50%"} Git will do its best to complete the merge automatically. For example, if none of the changes have happened in the same lines of code, things will usually merge cleanly. If the merge can't complete automatically, this is called a merge conflict. Any conflicts in the files must be resolved before the merge can be completed. @@ -108,8 +103,7 @@ Git will do its best to complete the merge automatically. For example, if none o There is another way to introduce changes from one branch to another: rebasing. A rebase rewrites history. For example, if there are new commits on the main branch while you are working on a feature branch, you could merge those commits into your feature branch, as we describe above. This creates a new commit with two parent commits: one in your feature branch, one in the main branch. Alternatively, you can rebase your feature branch onto the new end of the main branch with `git rebase main`. Rebasing "replays" your feature branch commits onto the new commits of the main branch, as if you started your branch there. -![Figure showing the process of rebasing the feature branch onto new commits in the main branch. First a graph diagram of a repository is shown with a main and feature branch. The feature branch with three commits splits off the main branch after two commits. A smiley face is on the third commit of the feature branch to show the current location. Below is an arrow with the text "git rebase main" followed by the same repository, but the feature branch now splits off the main branch at the last commit.](../fig/branches/rebase.png){alt="" width="50%"} -*Rebasing the feature branch onto new commits in the main branch with `git rebase main`.* +![Rebasing the feature branch onto new commits in the main branch with `git rebase main`.](../fig/branches/rebase.png){alt='Figure showing the process of rebasing the feature branch onto new commits in the main branch. On the top is a repository with a main and feature branch. The feature branch has three commits and starts from the second commit of the main branch, which has two additinal commits after the split. The current location is on the third commit of the feature branch. Below is an arrow with the text "git rebase main" followed by the same repository, but the feature branch now splits off the fourth and last commit of the main branch.' width="50%"} Rebasing creates a cleaner history, without the extra merge commit. However, rebases never be done on public branches that others might be using or even looking at. It will result in your repository and everyone else's having different history, which can be confusing and difficult to fix. If no one else is looking at your branch, especially if you haven't published it yet, rebasing is safe. diff --git a/episodes/fig/branches/checkout_branch.png b/episodes/fig/branches/checkout_branch.png index e2d37d2..a9f6369 100644 Binary files a/episodes/fig/branches/checkout_branch.png and b/episodes/fig/branches/checkout_branch.png differ diff --git a/episodes/fig/branches/commit_branch.png b/episodes/fig/branches/commit_branch.png index e872746..8399537 100644 Binary files a/episodes/fig/branches/commit_branch.png and b/episodes/fig/branches/commit_branch.png differ diff --git a/episodes/fig/branches/create_branch.png b/episodes/fig/branches/create_branch.png index 85f7f28..cda603a 100644 Binary files a/episodes/fig/branches/create_branch.png and b/episodes/fig/branches/create_branch.png differ diff --git a/episodes/fig/branches/merge_into_branch.png b/episodes/fig/branches/merge_into_branch.png index 61d1d30..2193b2e 100644 Binary files a/episodes/fig/branches/merge_into_branch.png and b/episodes/fig/branches/merge_into_branch.png differ diff --git a/episodes/fig/branches/merge_into_main.png b/episodes/fig/branches/merge_into_main.png index 6cd5ffa..9ae8989 100644 Binary files a/episodes/fig/branches/merge_into_main.png and b/episodes/fig/branches/merge_into_main.png differ diff --git a/episodes/fig/branches/rebase.png b/episodes/fig/branches/rebase.png index 12cc535..917e3f3 100644 Binary files a/episodes/fig/branches/rebase.png and b/episodes/fig/branches/rebase.png differ diff --git a/episodes/fig/pr/10_udpates.png b/episodes/fig/pr/10_udpates.png new file mode 100644 index 0000000..8cfa059 Binary files /dev/null and b/episodes/fig/pr/10_udpates.png differ diff --git a/episodes/pr.md b/episodes/pr.md index 8f8aeca..5627b63 100644 --- a/episodes/pr.md +++ b/episodes/pr.md @@ -34,41 +34,42 @@ First, make sure you don't have any commits you haven't pushed to GitHub. Go to Now navigate to your branch in GitHub. If you've pushed any commits recently you may see a callout that says your branch has recent pushes and provides a button that says "Compare and Pull Request". Pressing this will bring you to the form to create your Pull Request to the main branch. If you don't have this button, you can select "Pull Requests" at the top of the page and select "New Pull Request". From there select your branch under the "compare" dropdown. If you would like to merge your branch into a branch other than main, select that branch under the "base" dropdown. Then select "Create Pull Request". -![A screenshot of a branch on GitHub. A button with the text "Compare and Pull Request" is at the top fo the page.](../fig/pr/01_gotobranch.png){alt="" width="75%"} -*Creating a Pull Request: If you recently pushed changes to your branch you may see a button that says "Compare and Pull Request" on GitHub.* +![Creating a Pull Request: If you recently pushed changes to your branch you may see a button that says "Compare and Pull Request" on GitHub.](../fig/pr/01_gotobranch.png){alt='A screenshot of a repository on GitHub. A button with the text "Compare and Pull Request" is at the top fo the page.' width="75%"} At this point you will see a form. Fill out the form with a title and description for the Pull Request, and then click "Create Pull Request". We will go more in depth on how to make good pull requests in a later section. -![A screenshot of a Pull Request form on GitHub.](../fig/pr/02_createpr.png){alt="" width="75%"} -*Creating a Pull Request: Give your Pull Request a title and description.* +![Creating a Pull Request: Give your Pull Request a title and description.](../fig/pr/02_createpr.png){alt='A screenshot of a Pull Request form on GitHub.The title and description are filled out.' width="75%"} ### Anatomy of a Pull Request Once the Pull Request is created there are a few different tabs on the page. The first is the conversation tab, which shows a timeline of comments and commits, starting with the initial description that you gave when creating the Pull Request. At the bottom will be a box that shows the result of any Continuous Integration that has been defined, such as automated tests (the one in the image doesn't have any set up), as well as whether there are any merge conflicts for the Pull Request. -![A screenshot of the conversation tab of a Pull Request.](../fig/pr/03_conversation.png){alt="" width="75%"} -*The conversation tab of a Pull Request.* +![The conversation tab of a Pull Request.](../fig/pr/03_conversation.png){alt='A screenshot of the conversation tab of a Pull Request.' width="75%"} At the very bottom of the page is a box where you can leave a comment. GitHub supports markdown so you can include formatting with your comment. -![A screenshot of the bottom of the conversation tab of a Pull Request. At the bottom of the page is a box to leave a comment.](../fig/pr/04_comment.png){alt="" width="75%"} -*The conversation tab of a Pull Request. Scroll to the bottom of the page to leave a comment.* +![The conversation tab of a Pull Request. Scroll to the bottom of the page to leave a comment.](../fig/pr/04_comment.png){alt='A screenshot of the bottom of the conversation tab of a Pull Request. At the bottom of the page is a box to leave a comment.' width="75%"} -There is also a tab that shows all the commits in the Pull Request (the Commits tab). The last Files Changed tab shows the diff between the base branch and the Pull Request branch. This is useful in reviewing the Pull Request, and it allows you to leave in-line comments. If you see a line of code that needs to be updated or changed, you can click the + next to that line to leave a comment. +There is also a tab that shows all the commits in the Pull Request (the Commits tab). -![A screenshot of the Files Changed tab of a Pull Request. The page shows one line of code has been updated.](../fig/pr/04_comment.png){alt="" width="75%"} -*The Files Changed tab of a Pull Request, showing what the proposed changes are for the Pull Request. You can click the + next to a line number to leave an in-line comment.* +![The commits tab of a Pull Request.](../fig/pr/05_commits.png){alt='A screenshot of the Commits tab of a Pull Request. The page shows the single commit in this pull request.' width="75%"} + +The last Files Changed tab shows the diff between the base branch and the Pull Request branch. This is useful in reviewing the Pull Request, and it allows you to leave in-line comments. If you see a line of code that needs to be updated or changed, you can click the + next to that line to leave a comment. + +![The Files Changed tab of a Pull Request, showing what the proposed changes are for the Pull Request. You can click the + next to a line number to leave an in-line comment.](../fig/pr/06_fileschanged.png){alt='A screenshot of the Files Changed tab of a Pull Request. The page shows one line of code has been updated.' width="75%"} ### Updating a Pull Request Once the Pull Request is created you and anyone with access to the repository can make comments on the request. These comments might be clarifying questions or requests for additional changes. If additional changes are needed, make those changes in your branch and push them. The commits will be added to the Pull Request automatically and appear on the main Conversation page. + +![New commits can be seen on the Conversation Tab.](../fig/pr/10_updates.png){alt='A screenshot of the Conversation tab of a pull request on GitHub. This page shows additional commits added after the pull request was created along with their commit messages in a top-to-bottom timeline.' width="75%"} + ### Accepting and Merging a Pull Request Once a Pull Request has been reviewed and ready to be accepted, it can be merged. First verify that the branch has no conflicts with the base branch (the one that will be merged into). Any conflicts should be addressed with additional commits. When ready to merge, click "Merge Pull Request", then click "Confirm merge". You will be given the option to delete the branch. Whether you delete the branch depends on its purpose and how you and your group want to handle branches that have been merged. Deleting feature branches helps keep clutter down and makes it easier to find relevant branches. However, if you have any longer term branches, such as a development or production branch, you wouldn't want to delete that. -![A screenshot of the bottom of the conversation tab of a Pull Request after clicking "Merge Pull Request". There is a box with the original Pull Request title and description, with a button that says "Confirm Merge" below that.](../fig/pr/07_merge.png){alt="" width="75%"} -*After clicking the "Merge Pull Request" button on the conversation, click "Confirm Merge" to merge the pull request.* +![After clicking the "Merge Pull Request" button on the conversation, click "Confirm Merge" to merge the pull request.](../fig/pr/07_merge.png){alt='A screenshot of the bottom of the conversation tab of a Pull Request after clicking "Merge Pull Request". There is a box with the original Pull Request title and description, with a button that says "Confirm Merge" below that.' width="75%"} ## Activity diff --git a/learners/setup.md b/learners/setup.md index 4c11ee4..4aea298 100644 --- a/learners/setup.md +++ b/learners/setup.md @@ -2,5 +2,4 @@ title: Setup --- -FIXME: Setup instructions live in this document (learners\setup.md). Please specify the tools and -the data sets the Learner needs to have installed. +To complete this lesson you must have a [GitHub](https://github.com) account and have `git` installed on your laptop. Make sure you can authenticate into GitHub from your computer, either through `gh auth login` or with [ssh keys](https://docs.github.com/en/enterprise-cloud@latest/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account). To use `gh auth login` you will need to first [install the gh command](https://github.com/cli/cli#installation) and then authenticate using the instructions on the ([gh_auth_login page](https://cli.github.com/manual/gh_auth_login)). diff --git a/presentations/CollaborativeGit.pdf b/presentations/CollaborativeGit.pdf index d2613a5..e903c70 100644 Binary files a/presentations/CollaborativeGit.pdf and b/presentations/CollaborativeGit.pdf differ diff --git a/presentations/CollaborativeGit.pptx b/presentations/CollaborativeGit.pptx index 8c27c9b..63f6210 100644 Binary files a/presentations/CollaborativeGit.pptx and b/presentations/CollaborativeGit.pptx differ