diff --git a/.gitignore b/.gitignore index a1f7bb6..e43b0f9 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1 @@ .DS_Store -*.png -/tutorial2/*.docx diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..2fd2f87 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,46 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation. + +## Our Standards + +Examples of behavior that contributes to creating a positive environment include: + +* Using welcoming and inclusive language +* Being respectful of differing viewpoints and experiences +* Gracefully accepting constructive criticism +* Focusing on what is best for the community +* Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +* The use of sexualized language or imagery and unwelcome sexual attention or advances +* Trolling, insulting/derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or electronic address, without explicit permission +* Other conduct which could reasonably be considered inappropriate in a professional setting + +## Our Responsibilities + +Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior. + +Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful. + +## Scope + +This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at dr.stoney@gmail.com. The project team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately. + +Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at [http://contributor-covenant.org/version/1/4][version] + +[homepage]: http://contributor-covenant.org +[version]: http://contributor-covenant.org/version/1/4/ diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..c79c3b5 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,97 @@ +# Contributing Guide + +First, thanks for contributing! + + +## Report a problem or make a suggestion + +We love both! Please report the problem or make a suggestion as follows: + +1. Look for an existing issue in the issue tracker that describes a similar + problem or makes a similar suggestion. If you find one and you feel it is + the same problem or suggestion you have, please add a comment in support of + the issue. +2. If you feel your problem or suggestion is not the same, open a new issue and describe the problem or suggestion. + + +## Fixing a problem or implementing a suggestion + +If you think you know how to fix a reported issue or a reported suggestion, +please contribute using the same workflow as is taught in this activity: +fork-branch-pull-request. + + +## Versioning + +1. This project use [SemVer](https://semver.org/) version number: + MAJOR.MINOR.PATCH. +2. The public API is defined from the perspective of the facilitator. + Specifically the interface includes the activity's prerequisites, learning + outcomes, time requirements, material requirements, team composition + requirements, and facilitation requirements. +3. An increment in the MAJOR version number indicates that a change to the API +has been made that would require the facilitator to make an adjustment in their +course or the delivery of this activity before successfully adopting the new +version over the previous in their course. Here are some examples of changes +that would likely cause the MAJOR version number to be incremented. + * Adding or removing a learning outcome (e.g., students will no longer + learn the `git add` command). + * Adding or removing a prerequisite (e.g., students now need to know + calculus before participating in this activity) + * Changing from markdown to another delivery format (e.g., now requires + Googld Doc) + * A change in the required materials or course prep (e.g., now need + sticky-notes) +4. An increment in the MINOR version number indicates that improvements have +been made that should not violate the API thus allowing a facilitator to adopt +without requiring an adjustment in their course or the delivery of this +activity. However, facilitators should still make themselves aware of the +changes before adopting, just in case. Here are some examples of changes that +likely would require the MINOR version number to be incremented. + * Adding an optional question + * Reordering questions + * Adding a note about common pit-falls + * Adding or adjusting facilitator notes +5. An increment in the PATCH version number indicates that one or more +non-breaking bug-fix or cosmetic changes have been made. Again these should not +violate the API allowing facilitators to adopt the new version without +adjustment to their course. Again, facilitators should make themselves aware of +the changes before adopting, just in case. Here are some examples of changes +would likely only require the PATCH number to be incremented. + * Fixing a typo + * Fixing grammar + * Fixing a broken link + * Making a cosmetic change + + +## Merging a PR + +1. In the PR, update README.md with the new version number determined as + follows (the PR author must do this or give the maintainer permission to + modify their PR). Start with the current version in README.md from master. + If the PR contains a commit with a trivial bugfix, increment PATCH. If the + PR contains one or more commits that represent an improvement that are + backwards compatible, increment MINOR and reset PATCH to 0. If the PR + contains a breaking change, increment MAJOR and reset MINOR and PATCH to 0. + This is the new version number. + +2. Edit the PR title to ensure it is a good title for the squashed commit you are about to create. + +3. Draft a commit message (in a PR comment or a separate editor) that + - [ ] Summarizes the changes in the PR + - [ ] Lists each issue the PR closes with a line "Closes #k" where k is the + issue's number (not the PR's number) + - [ ] Lists related issues that the PR doesn't close with a line "Related + #k" where k is the issue's number (not the PR's number) + - [ ] Contains a Co-authored-by: for every author beyond the + first that had a commit in the PR + +4. Merge the PR using the "squash and merge" feature. Provide the commit + message when prompted. + + +## Small changes by a maintainer + +A small change (e.g., fixing a typo) may be made by a maintainer directly to +master. If this is done, be sure to increment PATCH in README.md at the same +time. 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..f9dc7a3 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,7 @@ # GitHub Workflow Activity +v3.0.0 + Participants, in teams of 2-3, work through a series of scenarios to learn how to contribute to open-source projects using a common workflow. ## Required Resources @@ -37,36 +39,30 @@ 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 +## Facilitation -- activity.md - Activity participants work through. -- presentation.pptx - Overview presentation of workflow. -- reference.md - Detailed description of the workflow. +- 10-20 min: + - Quickly review [activity/presentation.pptx](activity/presentation.pptx) with the class. +- 60-80 min: + - Teams work through [activity/README.md](activity/README.md). -## Facilitation +## Contributing to this project -- 10 min: - - ___Quickly___ presentation.pptx - - Form teams - - Hand out activity.md and reference.md, one hardcopy per team -- 50-70 min: - - Teams work through activity.md +Please read our [Code of Conduct](CODE_OF_CONDUCT.md) and [Contributing Guide](CONTRIBUTING.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 deleted file mode 100644 index 9e18c8e..0000000 --- a/activity.md +++ /dev/null @@ -1,119 +0,0 @@ -# GitHub Workflow Activity - -## 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. - -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. - - -## Overview - -In this activity your team will play out several scenarios following steps -described in [_Workflow Reference_](reference.md). - -- Complete each part in order. -- Complete each step in each part in order. - -## 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. - - -## Part 2: Create official upstream repository in organization - -- Name it `ourfavorites` -- Give it a default README.md file. - - -## Part 3: Contributor-1 setup - -- 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. - - -## 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. - -Congratulations, your team has made its first contribution! Celebrate. :clap: :clap: - - -## Part 5: Contributor-2 setup and second contribution - -- 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. - -Celebrate again. :clap: :clap: - -If you have 3 team members, repeat this scenario adding a file `favorite-animals.txt`. - -## 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. - -Celebrate. But keep it small. :clap: Don't worry, there will be bigger celebrations later. - - -## Part 7: Contribute conflicting changes - -- 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. - -Celebrate enthusiastically. :clap: :clap: :clap: That was challenging. - - -## 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. - - -## 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. - -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 - -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/README.md b/activity/README.md new file mode 100644 index 0000000..cf3d852 --- /dev/null +++ b/activity/README.md @@ -0,0 +1,57 @@ +# GitHub Workflow Activity + +## Form teams of 2-3 persons + +We suggest you work with someone who is uses the same operating system as you. + +## Instructions + + +1. (2 minutes) Ensure that each of your team members ... + + - [ ] Has git installed on their laptop. + - [ ] Is logged into their GitHub account on their computer. + +2. (1 minute) Create and share with your team a shared editor (e.g., Google docs, https://pad.riseup.net/, etc.) for notes. + +3. (10 minutes) Assign the role of _maintainer_ to one of your team members and help them [Create an organization and a repository](create-an-organization-and-a-repository.md) for the team. Return here when you are done. + +4. (2 minutes) Take a moment and reflect on your experience in the previous step. Record in your shared editor any insights you have learned or any questions that you still have. __Check in with your facilitator before continuing.__ + +5. (10 minutes) Assign the role of _contributor_ to one of your team members and help them [Prepare to contribute to a project](prepare-to-contribute-to-a-project.md). Return here when you are done. + +6. (2 minutes) Take a moment and reflect on your experience in the previous step. Record in your shared editor any insights you have learned or any questions that you still have. __Check in with your facilitator before continuing.__ + +7. (5 minutes) If you were the _contributor_ in the previous step, help your other team members play the role of _contributor_ and complete the previous step __in parallel__. + +8. (15 minutes) Assign the role of _maintainer_ to one of your team members, and the role of _contributor_ to another. Your team's goal is to have the _contributor_ create a new file `favorite-foods.txt` in the root of the project containing a couple of their favorite foods. Follow the __Contribution Workflow__ to accomplish this goal. _Maintainer_, when asked to review the PR, accept and merge the PR. + * [Contribution Workflow](contribution-workflow.md) + +9. (5 minutes) Take a moment and reflect on your experience in the previous step. Record in your shared editor any insights you have learned or any questions that you still have. __Check in with your facilitator before continuing.__ + +10. (10 minutes) Reassign the roles of _maintainer_ and _contributor_ to different team members. Your team's goal is to have the _contributor_ add a couple of their favorite foods to `favorite-foods.txt`. Follow the __Contribution Workflow__ to accomplish this goal. ___BUT THIS TIME___, _maintainer_, when asked to review the PR, request an alteration (e.g., "no lettuce please"). Once the change is made, then accept and merge the PR. + * [Contribution Workflow](contribution-workflow.md) + +11. (2 minutes) Take a moment and reflect on your experience in the previous step. Record in your shared editor any insights you have learned or any questions that you still have. __Check in with your facilitator before continuing.__ + +12. (10 minutes) This time, everyone is a _contributor_ and a _maintainer_. However, you cannot serve as a _maintainer_ for you own PR. Follow the __Contribution Workflow__ in parallel to accomplish the following: + * Add `favorite-movies.txt` + * Add `favorite-books.txt` + * (if you have three members) Add `favorite-sports.txt` + +13. (2 minutes) Take a moment and reflect on your experience in the previous step. Record in your shared editor any insights you have learned or any questions that you still have. __Check in with your facilitator before continuing.__ + +14. (20 minutes) Again, everyone plays the roles of a _contributor_ and a _maintainer_, but never serves as a _maintainer_ for their own PR. This time you will try to force a conflict so that you can experience resolving a conflict in the context of the __Contribution Workflow__. Complete the three tasks below in parallel. Note that only the first PR should merge successfully. The others should require resolving conflicts. Tasks: + * Sort the foods in `favorite-foods.txt` in ascending order. + * After each food in `favorite-foods.txt` add one or more labels to categorize the food (e.g., `[vegetable]`, `[fruit]`, `[meat]`, etc.) + * (if you have three members) Reformat the list of foods in `favorite-foods.txt` so that every item has a bullet in front (e.g., `*`). If they already have a bullet, change the bullet to a different style of bullet (e.g., `+` or `-`). + +15. (5 minutes) Take a moment and reflect on your experience in the previous step. Record in your shared editor any insights you have learned or any questions that you still have. __Check in with your facilitator before continuing.__ + + + +## 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/activity/contribution-workflow.md b/activity/contribution-workflow.md new file mode 100644 index 0000000..30ddb4f --- /dev/null +++ b/activity/contribution-workflow.md @@ -0,0 +1,229 @@ +# Contribution Workflow + +## Prepare to work on an issue + +In this section you will complete three tasks: find or create and claim an issue, create a feature branch, and open a pull-request back to upstream. All of this you will do before actually working on the feature. Let's quickly discuss why you are doing these tasks before you do them. + +Finding or creating and issue and then claiming it helps prevent developers from working on the same thing at the same time. Also issue provide a place for the community to propose and ideas, prioritize issues, size issues, clarify requirements, and verify bugs. So although this step may feel artificial during the activity, it's important to get in the habit of interacting with the community through the issue tracker before doing a significant amount of work. + +A branch as a personal copy of the project within a repository. You will create a branch for every issue you work on. This will allow you to work on more than one feature at same time, allowing you to quickly switch between them, while keep their changes separate until you are ready to merge them. This applies to the master branch as well. The master branch contains the official, current copy of the project. Using feature branches allows master to evolve while you work on your features without interfering with your development; and then, when you are ready, you can update your efforts with changes from master. Again, in this activity you might feel branches are artificial and useless. However, when you are working on more significant issues and with more developers branches become invaluable. So we want to practice the full workflow with these more simplistic tasks so that we know what we are doing when things get more complicated. + +Last, you will open an empty pull-request back to the organization's repository (upstream). Pull-requests provide a place for developers to discuss their solution design and implementation. By opening a pull-request immediately, you make your efforts visible from the very beginning, allowing others to track progress and provide useful feedback. Getting feedback early may help you avoid pitfalls and will more likely lead to an acceptable solution sooner and with less effort than if you wait until you are "done" to get feedback. + +### Find or create, and claim an issue + +__Assumptions__ + +* You are the contributor. +* You are signed into GitHub. + +__Instructions__ + +1. Navigate to your team's repository on GitHub (_not_ your fork). +2. Click the __Issues__ tab. +3. Search to see if there is an existing issue for what you want to do. +4. If no reasonable issue exists for what you want to do, create one. +5. If someone is assigned to the ticket or has claimed it by leaving a comment that they are working on it, move on, or maybe leave a comment asking about the progress and express interest in working on the issue. +6. If no-one is working on the issue assign yourself to the ticket (or leave a comment that you are working on it). +7. In your shared editor, note the issue number of the issue you will be working on. + +Congratulations, you now have a claimed issue for the work you plan to do. + +### Create a feature branch and a pull request (PR) for your work + +__Assumptions__ + +* You are the contributor. +* You have claimed an issue for the work you plan to do. +* You have a terminal opened and positioned to the root of your local clone. +* You are signed into GitHub. + +__Instructions__ + +1. You are going to create a new branch to hold your work. New branches should always be branched from master. So first ensure that the master branch is checked out. + ``` + git checkout master + ``` +2. Also you should always make sure that you start your branch based on the most recent copy of master. So let's pull changes from upstream (your team's repository on GitHub). In this activity, there shouldn't be any new changes in upstream, but this is a good habit to get into. So let's practice. At the same time, let's make sure your fork has those changes too. + ``` + git pull upstream master + git push origin master + ``` +2. Create the feature branch for the issue. Name it something short but meaningful and relevant to the issue. Replace BRANCH_NAME in the command below with your chosen name. + ``` + git branch BRANCH_NAME + ``` +3. Checkout the branch you just created. Checking out a branch makes it the active branch so that any new commits you make will be added to this branch. + ``` + git checkout BRANCH_NAME + ``` +4. Create an empty commit so that you can immediately issue a pull-request in the steps below. (Alternatively you could make a small change, stage it, and commit it. For now, just create an empty commit.) + ``` + git commit --allow-empty -m "Start BRANCH_NAME" + ``` +5. Push your new branch containing the empty commit to your fork. Recall that your clone has a remote named `origin` that points to your fork. At the same time, use `-u` to tell git to track this remote branch with the local branch with the same name. Basically you are telling git that the new remote and local branches mean the same thing. You only use `-u` when you first create and push a branch. + ``` + git push -u origin BRANCH_NAME + ``` +6. On GitHub, navigate to _your fork_. +7. Open a PR by either clicking + * __New pull request__ (subtle grey button in the middle) and then the __compare across forks__ link. + or + * __Compare & pull request__ (big green button on the right) +8. Make sure that + * __base fork__ is set to your team's repository under the organization + * __base__ is set to master + * __head fork__ is set to your fork of the team's repository + * __compare branch__ is set to your feature branch (e.g., BRANCH_NAME) +9. Click the __Create pull request__ button. +10. Briefly describe what you plan to do, and mention the issue that this PR is addressing. Mention the issue by putting its issue number in the body using this format: `Closes #i` where `i` is the issue number. When GitHub sees this, it cross-references the issue and the PR allowing folks to easily to get from one to the other. Also, when the PR is merged into master, it will close all issues mentioned this way! +11. Click __Create pull request__. + +Congratulations! You have created a feature branch to hold the changes you will make while working on the issue. You have also opened a PR for this feature branch back to the upstream repository. This will allow others to follow your progress as you work. Also, the PR is a place where developers can discuss designs and implementations for solutions to issues. + + +## Work on the issue + +__Assumptions__ + +* You are a contributor. +* You have a terminal opened and positioned to the root of your local clone. +* You have the feature branch for the issue checked out. +* You have an open PR associated with the feature branch. + +__Instructions__ + +1. Make a small change to the files in your local clone that gets you closer to accomplishing one of your goals (see the activity instructions to remind yourself of what your goals are in this scenario). Use any tools you would normally use to work on a project: e.g., editors such as Atom.io or Notepad++, development environments such as Eclipse, etc. +2. Test the change to make sure it works. In the activity this probably means reopening the file or files and making sure they have the correct changes. In a real project this means writing and running unit tests, running all the automated tests, manually running the code to see if it still works, running style checkers, etc. +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.) complete [Unstage changes](unstage-changes.md). When you are done, return here and continue. +6. Commit changes and provide a good commit message. + ``` + git commit + ``` +7. Push your changes that are in FEATURE_BRANCH to your fork. + ``` + git push origin FEATURE_BRANCH + ``` + +Congratulations, you have made a change, committed it to your feature branch, and pushed it up to your fork, which automatically updates the PR associated with your feature branch! + +* If you are not done working on the issue, return to [Work on the issue](#work-on-the-issue). +* If you give up, close the PR on GitHub and then go to [Clean up](#clean-up). +* If you think your work is ready to be upstreamed, continue to the next section. + + +## Collaborate to upstream your work + +### Update your PR with changes in upstream + +__Assumptions__ + +* You are the contributor. +* You have a terminal opened and positioned to the root of your local clone. +* You have a feature branch and a corresponding PR opened back to the upstream repository. + +__Instructions__ + +1. Synchronize master + ``` + git checkout master + git pull upstream master + git push origin master + ``` +2. Merge changes from master into your feature branch. + ``` + git checkout FEATURE_BRANCH + git merge master + ``` +3. If there are 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. Return here when you are done. +4. Test the merged copy. If there are any problems, return to [Work on the issue](#work-on-the-issue) and continue from there. +5. Update your fork and the PR + ``` + git push origin FEATURE_BRANCH + ``` + +Congratulations, your PR is now up-to-date with the latest changes from upstream. Time to request a review. + + +### Request a review + +__Assumptions__ + +* You are the contributor. +* You have an open PR. +* You are signed into GitHub. + +__Instructions__ + +1. Navigate to your PR on the team's repository on GitHub. +2. Make a comment. In that comment at-mention one of your team-members who will play the role of _maintainer_ (e.g., `@person`), and ask them to please review your work. +3. Click __comment__ (___do not click___ "close and comment"). + + Closing a PR means that it no longer needs to be merged into upstream. As a _contributor_, you would only do this if you are giving up on your effort. More often a PR is closed by the _maintainer_ either when they merge the PR into master or if they decide the PR should never be merged into master (i.e., the PR is no longer relevant, the PR is outside the scope of the project, the PR has been abandoned, etc.). + + +### Maintainer reviews the PR + +__Assumptions__ + +* You are the maintainer. +* You are signed into GitHub. + +__Instructions__ + +1. Navigate to the PR that needs reviewing on GitHub. +2. Review the changes and make sure they are up to the project's standards. Many projects have style guidelines and acceptance criteria such as "must pass all tests" and "contributions must include unit tests". The maintainer often must merge the contributor's feature branch into master in a local clone and confirm that it works as expected. As this activity is about training contributors, we will not go into the details about how to be a maintainer here. +3. After reviewing the PR, do one of the following (refer to the instructions in the [activity](README.md) for which you should pick) + * Reject the PR by closing it and leaving a message of why you are closing it. + * Accept the PR by merging it into master: choose "squash and merge" strategy for now and click __Merge pull request__ and then __Confirm__. + * Request modifications to the PR if it needs work by leaving a message in the PR indicating what needs to be done. + + +### Contributor decides what to do next + +__Assumptions__ + +* You are the contributor. +* You have received an automated email notifying you of the _maintainer's_ decision. + +__Instructions__ + +* If the _maintainer_ merged your PR into the master branch in the team repository, go to [Clean up](#clean-up). +* If the _maintainer_ closed the PR without merging (maybe because it's obsolete, or not a feature the maintainer wants, etc.), go to [Clean up](#clean-up). +* If the _maintainer_ asked for adjustments to your work, return to [Work on the issue](#work-on-the-issue) and make the requested changes. + + +### Clean up + +__Assumptions__ + +* You are the contributor. +* You have a terminal opened in the root of your local clone. + +__Instructions__ + +1. Checkout the master branch, update master with changes from upstream, and push those changes to your fork. This synchronizes master across your team's repository, your fork, and your clone. + ``` + git checkout master + git pull upstream master + git push origin master + ``` +2. Delete the feature branch from your local repository. + ``` + 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 + ``` + +Congratulations, having cleaned up your repositories you have completed this workflow! diff --git a/activity/create-an-organization-and-a-repository.md b/activity/create-an-organization-and-a-repository.md new file mode 100644 index 0000000..456c6d2 --- /dev/null +++ b/activity/create-an-organization-and-a-repository.md @@ -0,0 +1,46 @@ +# Create an organization and a repository + +## Create an organization + +__Assumptions__ + +* You are signed into GitHub. + +__Instructions__ + +On GitHub (you must be signed-in) + +1. Click the plus `+` in the upper right corner and select __New organization__. +2. Name it what you like. +3. Use the email associated with your GitHub account as the billing address. (Since you chose the free plan you won't get billed.) +4. Select a free plan. +5. Finish the creation of the organization. +6. Invite each of your team members to be an organization member. +7. In your shared editor, make a note of the URL of the organization's homepage. +8. Configure member privileges so that organization members can write to repositories. See __Settings__ >> __Member privileges__ >> __Repository permissions__ . + +Congratulations! You have created an organization that can hold multiple repositories for your team. More importantly for this activity, this setup allows any of your team members to play the role of _maintainer_ or _contributor_ using a fork-pull-request based workflow (also known as [GitHub-flow](https://guides.github.com/introduction/flow/) workflow). + +## Create a repository + +__Assumptions__ + +* You are signed into GitHub. +* You have just created an organization. +* You are viewing your organization on GitHub. +* Your organization is empty; i.e., it does not have any repositories. + +__On GitHub__ + +1. Click the __Repository__ tab to view the repositories of the organization. +1. Click the big green __Create a new repository__ button. (If you already have a repository in this organization, click the green __New__ button.) +2. Name the repository `our-favorites`. +3. Optionally add a description. +4. Make it public. +5. Initialize it with a README. +6. Optionally add a .gitignore (not necessary for this activity). +7. Add an open source license (unless you have a strong opinion, for now choose __GNU Public License v3.0__). +8. Click the big green __Create repository__ button +9. In your shared editor, make a note of the URL of the repository's homepage. + +Congratulations! You have created your team's first repository. diff --git a/activity/prepare-to-contribute-to-a-project.md b/activity/prepare-to-contribute-to-a-project.md new file mode 100644 index 0000000..db37236 --- /dev/null +++ b/activity/prepare-to-contribute-to-a-project.md @@ -0,0 +1,97 @@ +# Prepare to contribute to a project + +## Accept the invitation to join the organization + +If you played the role of maintainer in the last activity, skip this step. + +__Assumptions__ + +* You are signed into GitHub. + +__Instructions__ + +Either + +* Find the invitation in your email, view the invitation, and accept the invitation. + +Or + +* Navigate to the team's organization, view the invitation, and accept the invitation. + + +## Fork the upstream repository + +__Assumptions__ + +* You are signed into GitHub. +* You are viewing the team's repository within the team's organization on GitHub. + +__Instructions__ + +1. Click __Fork__ in the upper-right corner. +2. If you are a member of one or more organizations, select your personal account to receive the fork. +3. You should be viewing your personal fork of the team's repository on GitHub. + +Congratulations, you have forked a personal copy of the team's repository! + +## Clone your fork + +__Assumptions__ + +* You have git installed and configured on your machine. +* You are viewing your personal fork of the team's repository on GitHub. +* Your team's repository is named our-favorites. + +__Instructions__ + +1. In the browser, click the green __Clone or Download__ button. +2. If "HTTPS" is not selected, click __Use HTTPS__. +3. Click the clipboard to copy the URL in the box to your clipboard. +4. Open a terminal and change directories to the Desktop. + - If you are using Windows, right-click on your desktop and select __git-bash__ + - If you are on a Mac or linux, open a terminal and then execute + ``` + cd ~/Desktop + ``` +5. In the terminal, clone the repository. Do not type PASTE_URL, instead paste the URL that's in your clipboard from step 3. + ``` + git clone PASTE_URL + ``` +6. Change into the root of your clone. + ``` + cd our-favorites + ``` + +Congratulations, you have cloned your fork to your local machine! + +## Add an upstream remote + +__Assumptions__ + +* You are viewing your fork of the team's repository on GitHub. +* You have cloned your fork locally. +* You have a terminal opened and positioned in the root of your local clone. + +__Instructions__ + +1. In the browser, navigate to your team's repository by clicking its link under the title of your repository (look for "forked from ..."). +2. Click the green __Clone or Download__ button. +3. If "HTTPS" is not selected, click __Use HTTPS__. +4. Click the clipboard to copy the URL in the box to your clipboard. +5. In the terminal add a named URL (called a remote) to your clone that points to the team's repository, which we'll call `upstream`. + ``` + git remote add upstream PASTE_URL + ``` +6. Run the following and confirm that your local has two remotes (but four lines): origin that points to your fork of the team's repository, and upstream that points to your team's repository. + ``` + git remote -v + ``` + You should see something like this (with YOUR_ACCOUNT and TEAM_ORGANIZATION replaced with actual values). + ``` + $ git remote -v + origin https://github.com/YOUR_ACCOUNT/our-favorites.git (fetch) + origin https://github.com/YOUR_ACCOUNT/our-favorites.git (push) + upstream https://github.com/TEAM_ORGANIZATION/our-favorites.git (fetch) + upstream https://github.com/TEAM_ORGANIZATION/our-favorites.git (push) + ``` +Congratulations, your local clone now knows where to find the upstream repository (i.e., your team's repository). diff --git a/activity/presentation.pptx b/activity/presentation.pptx new file mode 100644 index 0000000..92843cb Binary files /dev/null and b/activity/presentation.pptx differ diff --git a/activity/unstage-changes.md b/activity/unstage-changes.md new file mode 100644 index 0000000..1780286 --- /dev/null +++ b/activity/unstage-changes.md @@ -0,0 +1,36 @@ +# Unstage changes + +__Assumptions__ + +* You are the contributor. +* You have files staged that you do not want committed. + +__Instructions__ + +Depending on which changes you want to unstage, do one of the following. + +* Unstage all changes. (Literally type `HEAD` here. `HEAD` means the currently checked out commit.) + ``` + git reset HEAD + ``` +* Unstage all changes in a directory. (Replace PATH/TO/DIRECTORY with a relative or absolute path to the directory containing the changes you want to unstage; One Windows use backslashes '\\' instead of '/') + ``` + git reset HEAD -- PATH/TO/DIRECTORY + ``` +* Unstage individual files (... means "and so on"; do not type them literally). + ``` + 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 . + ``` diff --git a/presentation.pptx b/presentation.pptx deleted file mode 100644 index d8f348e..0000000 Binary files a/presentation.pptx and /dev/null 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/ .