diff --git a/LICENSE.txt b/LICENSE.txt index 23e5a53..e5cad63 100644 --- a/LICENSE.txt +++ b/LICENSE.txt @@ -1,4 +1,3 @@ -Copyright 2016, Darci Burdge and Stoney Jackson +Copyright 2018 Darci Burdge and Stoney Jackson SOME RIGHTS RESERVED -This work is licensed under the Creative Commons Attribution-ShareAlike 4.0 International License. -To view a copy of this license, visit http://creativecommons.org/licenses/by-sa/4.0/. +This work is licensed under the Creative Commons Attribution-ShareAlike 4.0 International License. To view a copy of this license, visit http://creativecommons.org/licenses/by-sa/4.0/ . diff --git a/README.md b/README.md index fa07ff3..e999cd5 100644 --- a/README.md +++ b/README.md @@ -37,36 +37,33 @@ Participants will be able to: - Prepare a fork and local repository to contribute changes to upstream project on GitHub - Fork a project on GitHub - Clone a local repository from a remote repository - - Create a remote in local repository to a remote repository + - Connect local repository to remote repository - Prepare a branch to work on a feature or bug - Create a local branch - Push a local branch to a remote - Issue a pull-request on GitHub - Update repository with changes from upstream - - Fetch upstream changes into local repository - - Rebase feature branch onto upstream development branch + - Pull upstream changes into local repository + - Merge master into feature branch - Resolve conflicts - Push changes to remote - - Force push changes to remote - - Squash commits ## Contents -- activity.md - Activity participants work through. -- presentation.pptx - Overview presentation of workflow. -- reference.md - Detailed description of the workflow. +- [activity.md](activity.md) - Activity participants work through. +- [contributor.md](contributor.md) - Contributors' Guide. +- [maitainer.md](maintainer.md) - Maintainers' Guide. +- [presentation.pptx](presentation.pptx) - Overview presentation of workflow. ## Facilitation -- 10 min: - - ___Quickly___ presentation.pptx - - Form teams - - Hand out activity.md and reference.md, one hardcopy per team -- 50-70 min: +- 10-20 min: + - ___Quickly___ review presentation.pptx with class +- 60-80 min: - Teams work through activity.md -## License +## Copyright and Licensing -(c) 2016 Darci Burdge and Stoney Jackson SOME RIGHTS RESERVED +Copyright 2018 Darci Burdge and Stoney Jackson SOME RIGHTS RESERVED This work is licensed under the Creative Commons Attribution-ShareAlike 4.0 International License. To view a copy of this license, visit http://creativecommons.org/licenses/by-sa/4.0/ . diff --git a/activity.md b/activity.md index 9e18c8e..b3fd56b 100644 --- a/activity.md +++ b/activity.md @@ -2,118 +2,277 @@ ## Form teams -Form a of 2 or 3 person team. It's better to work with someone who is using the same operating system as you. +Form a 2-3 person team. We suggest you work with someone who is uses the same operating system as you. -Each team member will sometimes be a maintainer and sometimes a contributor. Rotate roles as necessary to ensure everyone in your team gets a chance to experience each role. +There are two roles: __maintainer__ and __contributor__. Each team member will adopt each role at different times while playing out different scenarios. Rotate roles before each scenario, and consider replaying a scenario with team members taking on different roles. +Create and share with your team a shared editor (e.g., Google docs, https://pad.riseup.net/, etc.) for notes and answering questions. ## Overview -In this activity your team will play out several scenarios following steps -described in [_Workflow Reference_](reference.md). +Your team will play out several scenarios. -- Complete each part in order. -- Complete each step in each part in order. +- Complete each scenario in order. +- Complete each step in each scenario in order. +- There are two guides, one for each role. Use them to help you along the way. + - [__Contributors' Guide__](contributor.md) + - [__Maintainers' Guide__](maintainer.md) -## Part 1: Create an organization on GitHub -- Name it what you like. -- Set the default permissions so that all organization members can create projects and write to any project in the organization. -- Add all team members to the organization. +## Organization and Project Setup +1. Before continuing, make sure all of the following are true. -## Part 2: Create official upstream repository in organization + - [ ] Everyone in your team has a GitHub account. + - [ ] Everyone in your team is logged into their GitHub account. + - [ ] Everyone in your team has git installed on their laptop. -- Name it `ourfavorites` -- Give it a default README.md file. + If any of the above are not true, help your team members to make them true. +2. Assign the role of _maintainer_ to one of your team members. -## Part 3: Contributor-1 setup +3. Help the _maintainer_ create an organization on GitHub by following the steps to [Create an Organization](maintainer.md#create-an-organization) in the maintainers' guide. -- Select a team member to be Contributor-1 -- Help Contributor-1 to follow _Setup: (1-4)_ in the _Workflow Reference_ to prepare his/her local and remote repositories. + - What is the URL to the new organization? + ``` -## Part 4: First contribution + ``` -- Help Contributor-1 to follow _Starting your contribution: (5-13)_ to add a - new file `favorite-foods.txt` that contains a couple of Contributor-1's - favorite foods. -- Select someone to play Maintainer (not Contributor-1). -- Help the Maintainer to accept Contributor-1's pull-request on GitHub. -- Help Contributor-1 to follow _Update your master (27-28)_ and - _Delete unneeded branches (29-31)_ to clean up. +4. Have each team member accept the invitation. There are two ways to do this. + + - Have the team member navigate to the organization on GitHub and accept the invitation. + - Have the team member check for an invitation in their email associated with their GitHub account. + +5. Help the _maintainer_ create an official upstream repository in the organization as specified below by following GitHub's directions for [Creating a new repository](https://help.github.com/articles/creating-a-new-repository/) + + - Name it `ourfavorites` + - Optionally add a description + - Make it public + - Initialize it with a README + - Optionally add a .gitignore (not necessary for this activity) + - Add an open source license + - What is the URL to your official upstream repository? + ``` + + ``` + +Congratulations, you have an organization with organization members, and an initial project! :clap: + +### Reflect + +1. When performing this section, what challenges did you encounter? + + ``` + + ``` + +2. How did you overcome those challenges? + + ``` + + ``` + +3. Is there anything that your team would like clarification about? What questions does your team have about the steps or the concepts in this section? + + ``` + + ``` + +### STOP: Check in with your facilitator + +## Contributor Setup + +1. Assign the role of _contributor_ to a team member. +2. Help the _contributor_ to complete the steps to [Prepare to work on a project](contributor.md#prepare-to-work-on-a-project) to prepare to work on `ourfavorites` +3. Repeat this section for each team member, ___one at a time___, including the team member who was initially assigned the role of maintainer. + +Congratulations, everyone on your team is ready to contribute to the project and can play the role of maintainer as needed! :clap: + + +### Reflect + +1. When performing this section, what challenges did you encounter? + + ``` + + ``` + +2. How did you overcome those challenges? + + ``` + + ``` + +3. Is there anything that your team would like clarification about? What questions does your team have about the steps or the concepts in this section? + + ``` + + ``` + +### STOP: Check in with your facilitator + + +## Scenario 1: First contribution + +1. Assign the role of _maintainer_ to one team member +2. Assign the role of _contributor_ to another team member. +3. Help the _contributor_ to follow the steps to [Prepare to work on an issue](contributor.md#prepare-to-work-on-an-issue) and [Work on an issue](contributor.md#work-on-an-issue) to accomplish the following: + - Create a new file `favorite-foods.txt` in the root of the project that contains a couple of your favorite foods. +4. Help the _maintainer_ to accept _contributor's_ pull-request on GitHub by following the instructions to [Review a pull-request](maintainer.md#review-a-pull-request). +5. Help the _contributor_ to [Clean up](contributor.md#clean-up). Congratulations, your team has made its first contribution! Celebrate. :clap: :clap: -## Part 5: Contributor-2 setup and second contribution +### Reflect + +1. When performing this section, what challenges did you encounter? + + ``` + + ``` -- Help Contributor-2 to follow _Setup: (1-4)_ to prepare his/her local and remote repositories. -- Repeat the steps above to have contributor-2 contribute a new file - `favorite-movies.txt` with a couple of his/her favorite movies. -- Make sure that the maintainer has accepted contributor-2's pull-request and contributor-2 has updated their master and cleaned up. +2. How did you overcome those challenges? + + ``` + + ``` + +3. Is there anything that your team would like clarification about? What questions does your team have about the steps or the concepts in this section? + + ``` + + ``` + +### STOP: Check in with your facilitator + + +## Scenario 2: Second Contribution + +1. Assign _contributor_ to a team member who wasn't contributor in the previous scenario. +2. Assign _maintainer_ to a team member who wasn't maintainer in the previous scenario. +3. Help the _contributor_ to follow the steps to [Prepare to work on an issue](contributor.md#prepare-to-work-on-an-issue) and [Work on an issue](contributor.md#work-on-an-issue) to accomplish the following: + - Add a couple of your favorite foods to `favorite-foods.txt`. +4. Help the _maintainer_ to accept _contributor's_ pull-request on GitHub by following the instructions to [Review a pull-request](maitainer.md#review-a-pull-request). +5. Help the _contributor_ to [Clean up](contributor.md#clean-up). Celebrate again. :clap: :clap: -If you have 3 team members, repeat this scenario adding a file `favorite-animals.txt`. +If you have 3 team members, repeat this scenario again so that each team member will have experienced each role. + + +### Reflect + +1. When performing this section, what challenges did you encounter? + + ``` + + ``` + +2. How did you overcome those challenges? + + ``` + + ``` + +3. Is there anything that your team would like clarification about? What questions does your team have about the steps or the concepts in this section? + + ``` -## Part 6: First synchronization + ``` -- Contributor-1's repositories are out of synch. Help Contributor-1 follow - _Keep your repositories up-to-date (18-23)_ to update his/her repositories. +### STOP: Check in with your facilitator -Celebrate. But keep it small. :clap: Don't worry, there will be bigger celebrations later. +## Scenario 3: Multi-round contribution +1. Assign _contributor-1_ to one team member +2. Assign _contributor-2_ to another team member +3. Assign _maintainer_ to one team member (the maintainer may also be a contributor) + - In a two-person team, each contributor plays maintainer for the other contributor. +4. At the same time + - Have _contributor-1_ follow the steps to [Prepare to work on an issue](contributor.md#prepare-to-work-on-an-issue) and [Work on an issue](contributor.md#work-on-an-issue) to accomplish the following: + - Add another food to `favorite-foods.md` + - Have _contributor-2_ follow the steps to [Prepare to work on an issue](contributor.md#prepare-to-work-on-an-issue) and [Work on an issue](contributor.md#work-on-an-issue) to accomplish the following: + - Add a new file `favorite-movies.md` with a couple of movies in it. +5. Have the _maintainer_ use the pull-request to request a change (e.g., "Please pick another food. I don't like chocolate."). Do this for each pull-request. +6. Have _contributors_ follow steps to [Work on an issue](contributor.md#work-on-an-issue) to make the requested changes. +7. Have the _maintainer_ accept the updated pull-requests. +8. Have the _contributors_ [Clean up](contributor.md@clean-up). -## Part 7: Contribute conflicting changes +Notice how pull-requests provide a way for a contributor and a maintainer to communicate about a proposed change. Also notice how the pull-request updates automatically as new changes are pushed to the same branch. -- Have Contributor-1 and Contributor-2 independently follow the contribution - workflow to add another favorite food to the end of `favorite-foods.txt`. -- Maintainer, accept one of the pull-requests. Try to accept the other. You - won't be able to because changes in the pull-request conflict with the other - that you already accepted. -- Help the contributor with the unresolved pull-request to follow - _Keep your repositories up-to-date (18-23)_ to synchronize his/her - repositories and resolve the conflicts. -- Maintainer, note that the conflicted pull-request is automatically updated and - should be acceptable. Accept the pull-request. -- Have contributors clean up. +### Reflect + +1. When performing this section, what challenges did you encounter? + + ``` + + ``` + +2. How did you overcome those challenges? + + ``` + + ``` + +3. Is there anything that your team would like clarification about? What questions does your team have about the steps or the concepts in this section? + + ``` + + ``` + +### STOP: Check in with your facilitator + + +## Scenario 4: Contribute conflicting changes + +1. Assign _contributor-1_ to one team member. +2. Assign _contributor-2_ to another team member. +3. Assign _maintainer_ to one team member (the maintainer may also be a contributor). +4. At the same time + - Have _contributor-1_ follow the steps to [Prepare to work on an issue](contributor.md#prepare-to-work-on-an-issue) and [Work on an issue](contributor.md#work-on-an-issue) to accomplish the following: + - Sort the foods in `favorite-foods.md` in descending order (e.g., z-a). + - Have _contributor-2_ follow the steps to [Prepare to work on an issue](contributor.md#prepare-to-work-on-an-issue) and [Work on an issue](contributor.md#work-on-an-issue) to accomplish the following: + - Capitalize the first letter of each food in `favorite-foods.md`. (If they are already capitalized, then lower-case them.) +5. Have the _maintainer_ accept one of the pull-requests. +6. Have the _maintainer_ try to accept the other pull-request. (You + shouldn't be able to because changes in the pull-request conflict with the other that you already accepted.) +7. Help the _contributor_ who's pull-request was not accepted follow +steps to [Update and resolve conflicts on a pull-request](contributor.md#update-and-resolve-conflicts-on-a-pull-request). +8. Help the _maintainer_ accept the pull-request. +9. Have _contributors_ [Clean up](contributor.md@clean-up). Celebrate enthusiastically. :clap: :clap: :clap: That was challenging. +If time allows repeat this scenario, with a different team member playing the role of the contributor that must update and resolve conflicts on their pull-request. + +### Reflect + +1. When performing this section, what challenges did you encounter? + + ``` + + ``` + +2. How did you overcome those challenges? -## Part 8: Multi-round contribution + ``` -- Have contributor-1 add another food, and contributor-2 another movie. -- Have the maintainer ask for a modification through the pull-request - (e.g., "Please pick another flavor. I don't like chocolate."). -- Have contributors make, commit, and push the new changes. -- If the maintainer is satisfied, accept the pull-requests. -- Contributors, don't forget to clean up. + ``` -Notice how pull-requests provide a way for a contributor and a maintainer to -communicate about a proposed change. Also notice how the pull-request updates -automatically as new changes are pushed to the same branch. +3. Is there anything that your team would like clarification about? What questions does your team have about the steps or the concepts in this section? + ``` -## Part 9: Squash + ``` -- Repeat the multi-round contribution until both contributors have made multiple - commits. -- Maintainer, through the pull-request, ask contributors to squash their work - into a single commit. -- Help contributors to follow _Squash your commits (24-25)_ to squash their - commits into a single commit and push it. -- Maintainer, accept the pull-requests once it contains the same work, but only - a single commit. -- Contributors, don't forget to clean up. +### STOP: Check in with your facilitator -This is another moment for an enthusiastic celebration. :clap: :clap: :clap: :clap: :clap: Well done! ## Copyright and Licensing -Copyright 2016 Darci Burdge and Stoney Jackson SOME RIGHTS RESERVED +Copyright 2018 Darci Burdge and Stoney Jackson SOME RIGHTS RESERVED This work is licensed under the Creative Commons Attribution-ShareAlike 4.0 International License. To view a copy of this license, visit http://creativecommons.org/licenses/by-sa/4.0/ . diff --git a/contributor.md b/contributor.md new file mode 100644 index 0000000..4379ea4 --- /dev/null +++ b/contributor.md @@ -0,0 +1,328 @@ +# Contributors' Guide + +__Note:__ In the instructions below __ALL_CAPS__ is a placeholder that you must replace with a real value. + +## Overview + +### Prepare to work on a project + +1. [Fork the project](#fork-the-project) +2. [Clone your fork](#clone-your-fork) +3. [Add upstream remote](#add-upstream-remote) + + +### Prepare to work on an issue + +1. [Claim an issue](#claim-an-issue) +2. [Update master](#update-master) +3. [Create a feature branch](#create-a-feature-branch) +4. [Create a pull-request](#create-a-pull-request) + + +### Work on an issue + +1. [Create and test a change](#create-and-test-a-change) +2. [Commit the change](#commit-the-change) +3. [Push changes in feature branch to your fork](#push-changes-in-feature-branch-to-your-fork) + + +### Update and resolve conflicts on a pull-request + +1. [Update master](#update-master) +2. [Merge master into feature branch](#merge-master-into-feature-branch) +3. [Push changes to your fork](#push-changes-to-your-fork) +4. [Request a review](#request-a-review) + + +### Clean up + +1. [Update master](#update-master) +2. [Delete the feature branch](#delete-the-feature-branch) +3. [Push changes in master to your fork](#push-changes-in-master-to-your-fork) + + +## Details + +### Fork the project + +1. Log into GitHub. +2. On GitHub, navigate to the project on which you want to work. +3. Click __Fork__ in the upper-right corner. +4. If you are a member of one or more organizations, select your personal account to receive the fork. +4. You should now be looking at your fork of the project on GitHub. + + +### Clone your fork + +1. Log into GitHub. +2. On GitHub, navigate to ___your fork___ of the project. +3. Follow GitHub's instructions for [Cloning a repository](https://help.github.com/articles/cloning-a-repository/). + + +### Add upstream remote + +1. Follow GitHub's instructions for [Configuring a remote for a fork](https://help.github.com/articles/configuring-a-remote-for-a-fork/). + + +### Claim an issue + +1. Log into GitHub. +2. On GitHub, navigate to the project on which you are working. +3. Click the __issues__ tab. +4. Search for an open issue that interests you. Alternatively, if you have an idea but don't see an issue for it, create an issue. +5. Make sure the issue is not assigned to anyone, and no-one else has claimed it (check comments). +6. Claim the issue by leaving a comment that you are working on it. + + + + +### Update master + +1. From the command-line, change into your clone's root directory. + + ``` + cd CLONES_ROOT + ``` + +2. Pull changes from upstream into the master branch. + + ``` + git checkout master + git pull upstream master + ``` + +3. Push the now updated master in your local repository to your fork. + + ``` + git push origin master + ``` + + +### Create a feature branch + +1. From the command-line, change into your clone's root directory. + + ``` + cd CLONES_ROOT + ``` + + +2. Create a feature branch off of the master branch. Name your branch something related to what you are working on: e.g., `login_fix` or `preview_feature`. + + ``` + git checkout master + git branch FEATURE_BRANCH + ``` + +### Create a pull-request + +Before you can create a pull-request, you need at least one commit. In these instructions you will create an empty commit. You could just as easily make a small change and commit that instead. + +1. From the command-line, change into your clone's root directory. + + ``` + cd CLONES_ROOT + ``` + +2. Create the empty commit on your feature branch + + ``` + git checkout FEATURE_BRANCH + git commit --allow-empty -m "Start work on FEATURE" + ``` + +3. Push changes in the feature branch to your fork, create a remote branch in your fork by the same name, and tell git to track that remote branch with your local branch. (This is a powerful little command.) + + ``` + git push -u origin FEATURE_BRANCH + ``` + +4. Follow GitHub's instructions for [Creating a pull request from a fork](https://help.github.com/articles/creating-a-pull-request-from-a-fork/). + +5. In a comment on the pull-request, link to the issue number(s) that the pull-request is attempting to address. This is done by putting the issue number after a pound-sign: e.g., `#32`. For more details see GitHub's article [Autolink references and URLs](https://help.github.com/articles/autolinked-references-and-urls/). This cross-links the issue with the pull-request. + + +### Create and test a change + +1. From the command-line, change into your clone's root directory. + + ``` + cd CLONES_ROOT + ``` + +2. Checkout your feature branch + + ``` + git checkout FEATURE_BRANCH + ``` + +3. Make a small change using your standard development environment (e.g., Atom.io, Notepad++, Eclipse, etc.). + +4. Test the change to make sure it works. + +### Commit the change + +1. From the command-line, change into your clone's root directory. + + ``` + cd CLONES_ROOT + ``` + +2. Checkout your feature branch + + ``` + git checkout FEATURE_BRANCH + ``` + +3. Stage your changes. + + ``` + git add . + ``` + +4. Confirm that only files that should be committed are staged. + + ``` + git status + ``` + +5. If there are files staged that shouldn't be (e.g., anything that can be generated from source, personal/private configurations or data, etc.) see [Unstaging changes](#unstaging-changes). + +6. Commit changes and provide a good commit messages. + + ``` + git commit -v + ``` + + +### Unstaging changes + +Depending on which changes you want to unstage, do one of the following. + +* Unstage all changes + + ``` + git reset HEAD + ``` + +* Unstage all changes in a directory + + ``` + git reset HEAD -- PATH/TO/DIRECTORY + ``` + +* Unstage individual files + + ``` + git reset HEAD -- FILE1 FILE2 ... + ``` + +To avoid this problem in the future, do one of the following. + +* Stage files individually from now on + + ``` + git add FILE1 FILE2 + git add FILE3 + ``` + +* Or edit `.gitignore` to forever ignore these files and stage again. See Atlassian's article on [.gitignore](https://www.atlassian.com/git/tutorials/saving-changes/gitignore). + + ``` + vim .gitignore # use your favorite editor + git add . + ``` + + +### Push changes in feature branch to your fork + +1. From the command-line, change into your clone's root directory. + + ``` + cd CLONES_ROOT + ``` + +2. Push you changes in FEATURE_BRANCH to your fork. + + ``` + git push origin FEATURE_BRANCH + ``` + +Notes: + +- Any pull-requests associated with a branch are automatically updated when you push your changes to that branch. + + +### Merge master into feature branch + +1. From the command-line, change into your clone's root directory. + + ``` + cd CLONES_ROOT + ``` + +2. Merge changes from master into your feature branch. + + ``` + git checkout FEATURE_BRANCH + git merge master + ``` + +3. If there were conflicts, follow GitHub's instructions for [Resolving a merge conflict using the command-line](https://help.github.com/articles/resolving-a-merge-conflict-using-the-command-line/). Be sure to test your changes before committing them. + +4. If there were no conflicts, just test the merged copy. If there are any problems, continue working on your feature until they are resolved. + + +### Request a review + +When you think your pull-request is ready to be merged into the project's master, request a review from the maintainer by using an `@username` in a comment on the pull-request (see [Mention @somebody. They're Notified](https://blog.github.com/2011-03-23-mention-somebody-they-re-notified/)). + +You might also want to review some of the spirit of communication on GitHub by reading [15 rules for communicating at GitHub](https://ben.balter.com/2014/11/06/rules-of-communicating-at-github/). + + +### Delete the feature branch + +Don't do this until your pull-request has been merged, or you give up. + +1. From the command-line, change into your clone's root directory. + + ``` + cd CLONES_ROOT + ``` + +2. Delete the feature branch from your local repository. + + ``` + git checkout master + git branch -d FEATURE_BRANCH + ``` + + Note: if the last statement complains that the branch has not been merged, you may be trying to delete the wrong branch or the maintainer may have used a "merge" strategy that was not a merge at all. So first, check that you have the correct branch and that your pull-request for that branch has actually been merged. If so, and you are really, really, REALLY sure, then force the delete with a capital "D": `git branch -D FEATURE_BRANCH`. + +3. Delete the feature branch from your fork. + + ``` + git push -d origin FEATURE_BRANCH + ``` + + +### Push changes in master to your fork + +1. From the command-line, change into your clone's root directory. + + ``` + cd CLONES_ROOT + ``` + +2. Push you changes in master to your fork. + + ``` + git push origin master + ``` + + +## Copyright and Licensing + +Copyright 2018 Darci Burdge and Stoney Jackson SOME RIGHTS RESERVED + +This work is licensed under the Creative Commons Attribution-ShareAlike 4.0 International License. To view a copy of this license, visit http://creativecommons.org/licenses/by-sa/4.0/ . diff --git a/maintainer.md b/maintainer.md new file mode 100644 index 0000000..ab8b257 --- /dev/null +++ b/maintainer.md @@ -0,0 +1,41 @@ +# Maintainers' Guide + +## Create an Organization + +On GitHub + +1. Click the plus in the upper right corner and select __New organization__. +2. Name it what you like. +3. Select a free plan. +4. Invite each of your team members to be an organization member. +5. Configure member privileges so that organization members can write to repositories. See __Settings__ >> __Member privileges__ >> __Repository permissions__ . + - You are doing this so everyone in your team can play the role of maintainer. + + +## Create a repository in your organization + +Follow GitHub's directions for [Creating a new repository](https://help.github.com/articles/creating-a-new-repository/) + + +## Review a pull-request + +1. Navigate to the pull-request that needs a review. + - If you've been requested to review a pull-request, you should have a notification on GitHub (see the bell in the upper right corner). Find the notice and click through to the pull-request. + - Otherwise, navigate to the repository in the organization and find the pull-request under the __Pull-requests__ tab. +2. Inspect the changes and make sure the following are true. + - [ ] The pull-request links to the issue(s) that this pull-request addresses. + - [ ] The changes are alignment with the goals, mission, and priorities of the project. + - [ ] The changes address only the issue they link to. + - [ ] The changes are reasonable and meet the projects style conventions. + - [ ] The changes do not textually conflict with changes in master. (GitHub will tell you if they do) + - [ ] The changes pass all the automated tests (N/A for this exercise) + - [ ] The changes when merged into master run properly on your machine. (N/A for this exercise) +3. If any of the above are not true, state the problem and what needs to be done before the pull-request can be merged. +4. Or, if the PR will never be merged (e.g., the changes are not in alignment with the goals, mission, and priorities of the project), state the issue and close the PR. +5. If the entire checklist is true then merge the pull-request. For details on the different ways you can merge a pull-request, see GitHub's instructions on [Merging a pull request](https://help.github.com/articles/merging-a-pull-request/). + +## Copyright and Licensing + +Copyright 2018 Darci Burdge and Stoney Jackson SOME RIGHTS RESERVED + +This work is licensed under the Creative Commons Attribution-ShareAlike 4.0 International License. To view a copy of this license, visit http://creativecommons.org/licenses/by-sa/4.0/ . diff --git a/presentation.pptx b/presentation.pptx index d8f348e..a6c59e5 100644 Binary files a/presentation.pptx and b/presentation.pptx differ diff --git a/reference.md b/reference.md deleted file mode 100644 index 03c5a4c..0000000 --- a/reference.md +++ /dev/null @@ -1,243 +0,0 @@ -# GitHub Workflow Reference - - -## Prerequisites - -- You have a GitHub account and you know your username and password. If you - don't have one, create one now. -- You have Git 2+ installed and configured. -- You know how to open a terminal and generally work from the command-line. -- You know enough of vi or vim to edit, move around in, save, and quit files. - - -## Workflow Overview - -The workflow description below covers the typical operations in the order -they are often performed to develop and contribute work to another project. -Most of the operations are issued from the command-line. These lines start with`$`. -Do not type `$`. This is the prompt that the command-line displays to you to -indicate that it is ready for you to type a command. Lines that start with `###` -are performed using GitHub through a browser. The numbers at the end of each -line are for quick reference and should not be typed either. When you see a term in all capital letters surrounded by angle -brackets, e.g., ``, replace it with a value appropriate to the project -you are working on. A list of these placeholders and their meaning is below: - -- `` - The URL to your GitHub hosted repository. To find it, navigate to - your repository on GitHub. Click on the green "New Pull Request" - button. You get a pop-up that contains a URL in a text-box. Unless you have configured your GitHub account to authenticate with SSH, you'll want a URL that starts with https://. If the URL starts with git@github... click `Use HTTPS`. -- `` - The URL for the project's repository that you would like to - contribute to. Find it by navigating to their repository on GitHub and copy - the URL in the box right of the `SSH` or `HTTPS` button. Use `HTTPS` since - this is not your repository. -- `` - This is any directory name you like. But use the same directory for - each occurrence of ``. -- `` - This is a branch name of your choosing. Choose one that is - related to the bug your are fixing or the feature you are implementing. - Whatever you choose, use the same branch name throughout the example. - -Also note, lines marked with `*` represent modifications being made to files in -the project. The exact modifications you might make, and the tools that you use -to make them, depend on what you are trying to do and your preferences. In -short, these lines should not be typed in literally, but must be interpreted in -terms of the task you are performing. - - -## Setup: (1-4) - -When you first start working on a project, you'll need to fork their project -(1), clone your fork locally (2-3), and create a remote back to their project in -your local repository (4). Once you've done this setup for a project, you will -not need to do it again unless you delete the fork, your local clone, or the -remote. - -```bash -### Use GitHub to fork their repository. (1) -$ git clone (2) -$ cd (3) -$ git remote add upstream (4) -``` - - -## Starting your contribution: (5-13) - -When you start working on a contribution, you need to create a branch to hold -your work (5), do a little work and commit it (6-10), push your new branch to -your repository on GitHub (11), and create a pull-request from your new branch -to master in the project's repository on GitHub (12-13). - -The purpose of the pull-request isn't to get the maintainer to accept your work -(yet). It starts a conversation with the maintainer. They can review what you -are trying to do and give you feedback early. That way, if you are on the wrong -track or the maintainer is not interested in your idea, you can find out before -you waste too much time implementing your idea. - -Also, remember, lines (6-8) are marked with `*`, so must be interpreted for the -task you are performing. - -```bash -$ git checkout -b (5) -$ vim file1 (*6) -$ rm file2 (*7) -$ mv file3 file4 (*8) -$ git add . (9) -$ git commit -v (10) -$ git push -u origin (11) -### Use GitHub to open a pull request (12) -### from in yours to master on theirs. (13) -``` - - -## Work (14-17) - -Keep working on your idea, committing and publishing your work as you go -(14-17). The pull-request will automatically be updated with the new commits you -push to your repository on GitHub, allowing the maintainer to follow your -progress as you go. - -Also, remember, lines (14) is marked with `*`, so must be interpreted for the -task you are performing. - -```bash -$ vim file4 (*14) -$ git add . (15) -$ git commit -v (16) -$ git push origin (17) -``` - - -## Keep your repositories up-to-date (18-23) - -While you are working on your idea, the maintainer may have accepted work from -other contributors. As that happens, the project's master branch will contain -commits that yours do not. You'll need to fetch these commits into your local -master (18), rebase your work on top of those commits (19), and push your -branches to your repository on GitHub (23). When you rebase your work (19) you -might find that your changes are incompatible with those you fetched from -upstream. You will need to resolve any conflicts that git identifies (20-22). -GitHub has a lovely tutorial on resolving conflicts [1]. - -It's a good idea to update your repositories regularly so that your work does -not become too stale. - -Again, as you push your work to your repository on GitHub, the pull-request -is updated automatically. - -Also, remember, line (20) is marked with `*`, so must be interpreted for the -task you are performing. - - -```bash -$ git fetch upstream master:master (18) -$ git rebase master (19) -$ vim file1 (*20) -$ git add . (21) -$ git rebase --continue (22) -$ git push -f origin master (23) -``` - - -**If you are on master, (18) will fail. Now what?** - -If you are on master branch, (18) will fail. Instead replace that line with `git pull upstream master`. This will fetch and merge the changes from upstream's master branch into your current local branch (master in this case). After that, (19-22) are unnecessary. However, don't forget to update master in your origin repository but running (23). - - -**Updating other branches** - -After you have updated your master branch (18), if you have other branches, you may need to update them as well. To do that, checkout each branch one at a time (e.g., `git checkout `) and perform (19-22) for each. - - -## Squash your commits (24-25) - -If you are following best practices, you will make many small commits as you -develop your idea. Sometimes earlier commits are invalidated/corrected by later -commits as you refine your solution. Your commit log becomes a diary of how you -developed your solution. This log is sometimes useful to you as you develop your -idea, but usually maintainers will ask you to squash your commits (24) into just -a few (often one) logical commit that implements your feature, or fixes the bug. -That helps keep the log of the main project cleaner, and more clearly identifies -which commits are responsible for implementing which features or fixing which -bugs. Usually you squash when you near completion of your implementation, but a -maintainer may ask you to squash periodically as you go because it may make it -easier for them to review your changes. - -In any case, you will periodically squash your commits (24) and push the -squashed version to your repository on GitHub (25). Again, the pull-request will -be updated automatically. - -To squash commits, we perform an interactive rebase (24). This will put us into -and editor (vim most likely) with a list of the commits that we are rebasing at -the top. To squash them into one commit, change the first word in every line -after the first from `pick` to `squash`. Save and quit. Git will combine all the -commits into the first and will again put you into an editor to create the final -commit message for the newly squashed commit. If you have been providing good -commit messages as you go along, writing a good final commit message should be -relatively easy. - -GitHub has a nice article on interactive rebases [2]. - -```bash -$ git rebase -i master (24) -$ git push -f origin (25) -``` - - -## Maintainer accepts your pull-request (26) - -After all your hard work, hopefully the maintainer will eventually accept your -pull-request, which will merge your changes into their master branch. - -```bash -### Maintainer accepts your pull-request (26) -``` - - -## Update your master (27-28) - -After the maintainer has accepted your pull-request, your need to update your -master with the new changes in upstream, which are yours (27-28)! You follow the -same procedure as in "Keeping your repositories up-to-date", except that you -don't need to rebase. That's because your work is already included in master. - -```bash -$ git fetch upstream master:master (27) -$ git push origin master (28) -``` - - -## Delete unneeded branches (29-31) - -Now that your work has been accepted in upstream, you can safely delete the -branches you were working on both in your local and remote repositories (29-31). If you ever abandon your effort before -a pull-request is accepted, you can also delete your branch; but you'll need -to use -D (capital D) in (30). - -```bash -$ git checkout master (29) -$ git branch -d (30) -$ git push origin : (31) -``` - - -## Update your repositories before starting the next fix/feature (32-33) - -OK, it's been a month since you worked on the project. Now you're back from the Bahamas and are ready to start working again. However, while you were sunning yourself, others have been hard at work contributing changes to upstream. So before you start working again, you need to update your repositories with changes from upstream. Follow steps in section _Keep your repositories up-to-date (18-23)_ to get this done. - -Nice tan. Now get back to work! - - -## References - -[1] GitHub. _Resolving a Merge Conflict from the Command Line_. Accessed April -2016. -. - -[2] GitHub. _About Git Rebase_. Accessed April 2016. . - - -## Copyright and Licensing - -Copyright 2016 Darci Burdge and Stoney Jackson SOME RIGHTS RESERVED - -This work is licensed under the Creative Commons Attribution-ShareAlike 4.0 -International License. To view a copy of this license, visit -http://creativecommons.org/licenses/by-sa/4.0/ .