diff --git a/README.md b/README.md index 7f8ae9c..95c2ad1 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ -# FIXME Lesson title +# Working Collaboratively -This repository generates the corresponding lesson website from [INTERESECT](https://intersect-training.org/) repertoire of lessons. +This repository generates the corresponding lesson website from [INTERSECT](https://intersect-training.org/) repertoire of lessons. The lesson format and structure is based off the [The Carpentries](https://carpentries.org/). ## Contributing @@ -21,8 +21,9 @@ If you contribute to this lesson and would like to acknowledge specific funding The contributing author(s) to this lesson are: -* FIXME -* FIXME +* Lauren Milechin +* Dave Rumph +* David Bernholdt ## Maintainer(s) diff --git a/_episodes/01-introduction.md b/_episodes/01-introduction.md index 58bdaed..f8fb02e 100644 --- a/_episodes/01-introduction.md +++ b/_episodes/01-introduction.md @@ -26,18 +26,18 @@ While technology helps, it is not the solution on its own. We will also discuss Before diving in, we should review some basic terminology and commands. Note that while other options are available, we are focusing on GitHub for this lesson. -- **repository**: The project, contains all data and history (commits, branches, tags). -- **remote (repository)**: The copy of the repository on a remote server, such as GitHub. Accessible to anyone who has access to the repository on the server. Also referred to as the "central" repository. -- **local (repository)**: A copy of the repository in another place, such as a laptop or your home directory on a cluster. Generally accessible to one person. -- **commit**: Snapshot of the project, gets a unique identifier (e.g. c7f0e8bfc718be04525847fc7ac237f470add76e). -- **branch**: Independent development line. The main development line is often called main or master. -- **tag**: A pointer to one commit, to be able to refer to it later. Like a commemorative plaque that you attach to a particular commit (e.g. phd-printed or paper-submitted). -- **cloning**: Copying the whole repository to your laptop - the first time. It is not necessary to download each file one by one. This creates a local copy of the repository. -- **forking**: Taking a copy of a repository (which is typically not yours) - your copy (fork) stays on GitHub/GitLab and you can make changes to your copy. -- **pull**: Bring changes from a remote repository to your local repository. -- **push**: Bring changes from your local repository to the remote repository. - -{% comment %} Cite definitions from code refinery {% endcomment %} +- *repository (repo)*: The project, contains all data and history (commits, branches, tags). +- *remote (repository)*: The copy of the repository on a remote server, such as GitHub. Accessible to anyone who has access to the repository on the server. Also referred to as the "central" repository. +- *local (repository)*: A copy of the repository in another place, such as a laptop or your home directory on a cluster. Generally accessible to one person. +- *commit*: Snapshot of the project, gets a unique identifier (e.g. c7f0e8bfc718be04525847fc7ac237f470add76e). +- *branch*: Independent development line. The main development line is often called main or master. +- *tag*: A pointer to one commit, to be able to refer to it later. Like a commemorative plaque that you attach to a particular commit (e.g. phd-printed or paper-submitted). +- *clone*: Copying the whole repository to your laptop - the first time. This creates a local copy of the repository. "Clone" as a noun refers to the local copy of the repository. +- *fork*: Taking a copy of a repository (which is typically not yours) - your copy (fork) stays on GitHub/GitLab and you can make changes to your copy. "Fork" as a noun refers to the your forked copy of the repository. +- *pull*: Bring changes from a remote repository to your local repository. +- *push*: Bring changes from your local repository to the remote repository. + +These definitions are adapted from [Code Refinery: Concepts around Collaboration](https://coderefinery.github.io/git-collaborative/concepts/). A note about git integrations: You may find that your IDE has git built in allowing you to use the GUI instead of running the commands we talk about here. In this lesson we are focusing on the command line git commands, since they should be universal across any system you use. After this lesson we encourage you to use what you are most comfortable with, and the commands we cover will also help you better understand the functionality of your IDE git integration. @@ -45,18 +45,10 @@ A note about git integrations: You may find that your IDE has git built in allow Verify that you can access your GitHub account, have git installed on your computer, and can authenticate with GitHub from your computer, either using gh auth, ssh keys, or using your preferred GUI application. -In groups: have one person in your group create a repository from the provided template. Give access to the others in your group. Everyone should create a local clone with `git clone`. We will use this repository for the remainder of the exercises in this section. +Work in small groups of 3-4. Have one person in your group create a repository from the [provided template](https://github.com/INTERSECT-training/intersect-training-day2). To create a repository from the template click "Use this Template" in the top right, then "Create a New Repository". Give access to the others in your group. Everyone should accept the invitation to collaborate and then create a local clone with `git clone`. We will use this repository for the remainder of the exercises in this section. -## Outline - -- Recall challenges: - - Sharing code in a cohesive way, everyone has access to the latest version, everyone is able to contribute equally - - Keeping organized when working on a team, staying on the same page, communicating -- Contributing document -- Brief review of terminology - -## TODO - -- Create/find repository template to use +## Additional Resources +- [Code Refinery: Concepts around Collaboration](https://coderefinery.github.io/git-collaborative/concepts/) +- [Code Refinery: Introduction to Version Control](https://coderefinery.github.io/git-intro/) {% include links.md %} diff --git a/_episodes/02-branches.md b/_episodes/02-branches.md index dc26d99..3dd8860 100644 --- a/_episodes/02-branches.md +++ b/_episodes/02-branches.md @@ -33,14 +33,14 @@ Changes made in one branch can be brought into another branch with a merge. For You can create a branch on your local clone of the repository. If didn't just clone the repository it is always good to make sure you have any recent changes to the main branch by checking out the main branch and running "git pull": -```bash +```shell git checkout main git pull ``` Then, to create a branch we can run: -```bash +```shell git checkout -b my_new_branch ``` @@ -54,7 +54,7 @@ This will create the branch `my_new_branch` and move you to the new branch. If y The first time you push your branch to the remote repository, you will need to publish the branch by running run: -```bash +```shell git push --set-upstream origin my_new_branch ``` @@ -64,7 +64,7 @@ After this any commits can be pushed with a simple `git push`. If you need to switch to another existing branch you can use the `git checkout` command. For example, to switch back to the main branch you can run: -```bash +```shell git checkout main ``` @@ -77,7 +77,7 @@ Remember, if you aren't sure which branch you are on you can run `git status`. I Bring the changes from one branch into another branch by merging them. When you merge branches, changes from the specified branch are merged into the branch that you currently have checked out. For example, -```bash +```shell git checkout my_new_branch git merge main ``` @@ -89,7 +89,7 @@ will merge any changes introduced to `main` into the `my_new_branch`. Merging in When development is complete on `my_new_branch`, it would be merged into `main`: -```bash +```shell git checkout main git merge my_new_branch ``` @@ -119,7 +119,7 @@ Everyone: Now, **all but one** should run the following: -```bash +```shell git pull git checkout main git merge branch_name diff --git a/_episodes/04-git-workflows.md b/_episodes/04-git-workflows.md index 8b9ca76..1353d4c 100644 --- a/_episodes/04-git-workflows.md +++ b/_episodes/04-git-workflows.md @@ -68,14 +68,14 @@ In each of these example workflows we have assumed that anyone contributing to a With a forking workflow it can be easy to end up with an old version of the code, especially if it changes frequently. It can get confusing whether we are attempting to pull from or push to the fork or the original repository. Setting up remotes with easy to remember aliases makes this much easier. A "remote" is a named connection to a remote repository. You can add and remove remotes with the `git remote add` and `git remote rm` commands, respectively. For example: -```bash +```shell git remote add upstream https://github.com/project_team/project.git git remote add my-fork https://github.com/me/project.git ``` Here we are adding a remote called "upstream" for our central team repository and another called "my-fork" for our own fork. We can view our remotes with `git remote -v`. Now when you want to retrieve any changes from the upstream repository you can run `git fetch upstream`. To update your main branch with these changes, you would merge them into your local forked repository: -```bash +```shell git checkout main # this is the main branch for your fork that you have cloned locally git merge upstream/main ``` @@ -94,7 +94,9 @@ We will end with a quick note if your team works on shared systems, including cl ## Activity -We provide a base repository to each group that each group member creates a local copy of the repository (either by forking or cloning). Students should decide which workflow to use and set up their repository accordingly. Start a contributor guide that explains the layout and rules. +For your group's "project" that you have been working on through this lesson discuss which workflow would work best for your team. Set up the repository as needed to support this workflow. Start a contributor guide that explains the workflow and any rules for contributing. + +If time allows, discuss any projects that your group members work on collaboratively with others. Is there a specified workflow for this project? How would someone contribute to the project? ## Additional Resources diff --git a/index.md b/index.md index a4c8931..1c2bf0f 100644 --- a/index.md +++ b/index.md @@ -3,7 +3,6 @@ layout: lesson root: . # Is the only page that doesn't follow the pattern /:path/index.html permalink: index.html # Is the only page that doesn't follow the pattern /:path/index.html --- -FIXME: home page introduction diff --git a/presentations/CollaborativeGit.pptx b/presentations/CollaborativeGit.pptx index 1a42b85..15653f1 100644 Binary files a/presentations/CollaborativeGit.pptx and b/presentations/CollaborativeGit.pptx differ diff --git a/reference.md b/reference.md index 8c82616..1c4d825 100644 --- a/reference.md +++ b/reference.md @@ -4,6 +4,15 @@ layout: reference ## Glossary -FIXME +- **repository**: The project, contains all data and history (commits, branches, tags). +- **remote (repository)**: The copy of the repository on a remote server, such as GitHub. Accessible to anyone who has access to the repository on the server. Also referred to as the "central" repository. +- **local (repository)**: A copy of the repository in another place, such as a laptop or your home directory on a cluster. Generally accessible to one person. +- **commit**: Snapshot of the project, gets a unique identifier (e.g. c7f0e8bfc718be04525847fc7ac237f470add76e). +- **branch**: Independent development line. The main development line is often called main or master. +- **tag**: A pointer to one commit, to be able to refer to it later. Like a commemorative plaque that you attach to a particular commit (e.g. phd-printed or paper-submitted). +- **cloning**: Copying the whole repository to your laptop - the first time. It is not necessary to download each file one by one. This creates a local copy of the repository. +- **forking**: Taking a copy of a repository (which is typically not yours) - your copy (fork) stays on GitHub/GitLab and you can make changes to your copy. +- **pull**: Bring changes from a remote repository to your local repository. +- **push**: Bring changes from your local repository to the remote repository. {% include links.md %}