├── .github └── CODEOWNERS ├── .gitignore ├── README.md ├── part1-introduction └── README.md ├── part2-cloning_a_repo ├── README.md ├── code-button.png └── https-url-clone.png ├── part3-make_a_new_branch └── README.md ├── part4-changing_the_code ├── README.md ├── people │ └── seun_omonije.txt ├── printer.py └── run.py ├── part5-pushing_changes_to_github ├── README.md └── branches-link.png ├── part6-pull_requests ├── README.md ├── branch-dropdown.png ├── choose-base-and-compare-branches.png ├── pull-request-start-review-button.png ├── pullrequest-description.png └── pullrequest-send.png └── part7-keeping_up_with_repo └── README.md /.github/CODEOWNERS: -------------------------------------------------------------------------------- 1 | # These owners will be the default owners for everything in 2 | # the repo. Unless a later match takes precedence, 3 | # @global-owner1 and @global-owner2 will be requested for 4 | # review when someone opens a pull request. 5 | * @seunomonije -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # ignore enviornments and caches 2 | env/ 3 | __pycache__/ -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | ## Learn how to contribute! 2 | 3 | Throughout this tutorial, we'll go over the basics of Git and GitHub and show you how to use them, starting with cloning and ending with pull requests. This tutorial is not a comprehensive one by any means, but it should give you what you need to start making an impact in the open source community. 4 | 5 | ### Walkthrough: 6 | 1. [Introduction to Git and GitHub](part1-introduction/) 7 | 2. [Cloning a repository to make changes locally](part2-cloning_a_repo/) 8 | 3. [Creating a new branch for your local changes](part3-make_a_new_branch/) 9 | 4. [Make changes to the code locally](part4-changing_the_code/) 10 | 5. [Push your local changes to GitHub](part5-pushing_changes_to_github/) 11 | 6. [Open a pull request to merge your code with the master branch](part6-pull_requests/) 12 | 7. [Keeping up with the repository](part7-keeping_up_with_repo/) 13 | 14 | ### Good video links: 15 | - [Git Github Tutorial 10: What is Pull Request?](https://youtu.be/e3bjQX9jIBk) 16 | 17 | This tutorial was written by [@seunomonije](https://github.com/seunomonije), 2020-2021 YuQC Director of Open Source. If there are any issues, don't hesistate to open a GitHub issue or submit a PR fix! And if you're a member of YuQC and have any questions, don't hesitate to reach out! -------------------------------------------------------------------------------- /part1-introduction/README.md: -------------------------------------------------------------------------------- 1 | ## Introduction to Git and GitHub 2 | 3 | ### So what is Git and what is GitHub? 4 | 5 | So what is Git and what is GitHub? Put simply, **Git** is a version control system that lets you manage you code in a very convenient and easy way. **GitHub** is a cloud-based host that lets you store and manage projects that use Git. 6 | 7 | ### How do I get started? 8 | 9 | **Note:** All code snippets in this tutorial are assuming you are working from a UNIX based system (Mac/Linux). If you're working from a Windows computer, the concepts will still apply, but the ways that they are implemented may be different. 10 | 11 | The first step to get started is to install Git on your computer. If you're on a Mac, Git should come preloaded. To check, type `git` in your shell and usage information, along with common Git commands, should print. If you get an error or a response like `git: command not found`, you can install it [from the Git documentation site](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git). 12 | 13 | **Note:** If you are a Mac user, you might need XCode's [Command Line Package](https://developer.apple.com/library/archive/technotes/tn2339/_index.html) which allows for command line development in OSX. *Note: you do not need XCode to get these developer tools.* In order to install the package, run `xcode-select --install` in your terminal. If you get an error, you can troubleshoot and learn more about the package [here](https://developer.apple.com/opensource/). 14 | 15 | Once you have Git installed on your computer, we can start your journey to becoming a contributor! Let's go to the next section to continue. 16 | 17 | [Next: Cloning a repository to make changes locally](../part2-cloning_a_repo) -------------------------------------------------------------------------------- /part2-cloning_a_repo/README.md: -------------------------------------------------------------------------------- 1 | ## Cloning a repository locally 2 | 3 | The first step in contributing to a project is cloning the GitHub repository. Saying that we are "cloning" is just another way of saying that we are copying that repository from the internet onto our local machines. 4 | 5 | One important distinction between just copying and cloning, however, is that a remote is automatically set up between your local copy and the copy of the repository on GitHub. This remote tracks the changes that you make locally and allows you to see where your copy the and GitHub copy differ, check if your local copy needs to be updated, and push any local changes you make to GitHub. You can think of a remote as a link between your local copy of the repo and the GitHub copy. 6 | 7 | Cloning a repository is simple. Navigate to the desired directory in your computer and enter: 8 | ``` 9 | git clone 10 | ``` 11 | 12 | But where do we get this ``? 13 | 14 | At the top of every repository, there is a green button (depicted below) that expands to provide you the link to the repo! 15 | 16 | 17 | 18 | 19 | ###### Source: [GitHub Docs: Cloning a repository](https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/cloning-a-repository) 20 | 21 | For the purposes of this tutorial, we will only worry about cloning using HTTPS. All you have to do is copy the given link and paste it in! 22 | 23 | ## Challenge 1: 24 | 25 | Clone (your fork of) this repo! (But first you'll need to fork it so you can actually push your changes.) Check out [this guide](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo) for information on how to fork a repo. 26 | 27 | [Next: Creating a new branch for your local changes](../part3-make_a_new_branch) 28 | -------------------------------------------------------------------------------- /part2-cloning_a_repo/code-button.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/yaleqc/github-basics/8ae1d0d249f4a927232b3f372f9e7904a4359405/part2-cloning_a_repo/code-button.png -------------------------------------------------------------------------------- /part2-cloning_a_repo/https-url-clone.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/yaleqc/github-basics/8ae1d0d249f4a927232b3f372f9e7904a4359405/part2-cloning_a_repo/https-url-clone.png -------------------------------------------------------------------------------- /part3-make_a_new_branch/README.md: -------------------------------------------------------------------------------- 1 | ## Making a new branch to start editing code 2 | 3 | The next step you need to take before actually contributing is creating a new branch for your change. 4 | 5 | ### Why do we need branches? 6 | 7 | Branches allow you to create a local copy of the repository at its current state, which you can later merge into the `master` branch. But why would we want to do this? 8 | 9 | ##### Stability 10 | Put simply, using separate branches as workspaces allows for the `master` branch to be the point of reference for all contributors in the project. The `master` branch should be a stable and functioning version of the project at all times. Creating separate branches for separate features allows you to make changes, test them, and push them to GitHub without ruining the stable version of the product. 11 | 12 | ##### Organization 13 | Using branches also allows for implementations features to be organized well and later merged to the `master` branch piece by piece rather than in one large chunk of code. For example, if you have working code for a basic game of Pong and want to add more features, contributors might create a branch to implement different ball colors, one for different background colors, and one for different fonts. If the contributor working on the background colors gets done first, they can merge those changes into the `master` branch without having to wait for the people working on the other features to finish. This becomes especially important as the number of project contributors grows. 14 | 15 | ##### Code Reviews 16 | Branches are also needed for creating [Pull Requests](../part6-pull_requests), which we'll discuss in depth later. The importance of branches in PRs have to do with making changes. When you submit a PR (pull request) for you branch to be merged to the `master`, normally the owner(s) of the repository will check the code to make sure that the code is written well and does what it's supposed to. If you submit your branch in a PR and changes are requested, all you need to do is push the changes to your branch **and the changes will automatically show up in the PR**. Again, we'll talk more about it later, but this is an important part of branches. 17 | 18 | ### Now that we know why branches are important, how do we create and manage them? 19 | 20 | #### To checkout a new branch, enter: 21 | ``` 22 | git checkout -b 23 | ``` 24 | where `` is up do you. 25 | 26 | #### To view all local branches, enter: 27 | ``` 28 | git branch 29 | ``` 30 | 31 | in your shell. The branch you are currently on will be highlighted. 32 | 33 | #### To switch to an existing branch, enter: 34 | ``` 35 | git checkout 36 | ``` 37 | where `` is the name of the desired branch. 38 | 39 | When starting a fresh feature, first [make sure your master branch is up to date](https://github.com/yaleqc/github-basics), then create your new branch! To learn how to actually change the code and add the changes to your branch, see the next section. 40 | 41 | ## Challenge 2: 42 | 43 | Create a branch with your last name titled `lastname-first-branch` and go into it. Use `git branch` to check. 44 | 45 | [Next: Make changes to the code locally](../part4-changing_the_code) -------------------------------------------------------------------------------- /part4-changing_the_code/README.md: -------------------------------------------------------------------------------- 1 | ## Making changes to the codebase in your branch 2 | 3 | Now that you know how to create a branch to make your changes, time to actually make the changes! 4 | 5 | Doing so is pretty self-explanatory, once you're in your branch, edit files however you see fit. You can add and delete files, reorganize directories, and change code and Git will track it all. 6 | 7 | Once you're ready to actually push these changes, they need to be staged and then bundled in a commit. Think of staging as telling Git "Hey, these are the files I'd like to group together." and then making a commit is actually doing the bundling. 8 | 9 | Commits are how Git tracks different changes to the codebase. Normally, we'd like to make commits as small as possible so that we have a record of how the repository is changing. Better to have a lot of small commits rather than a few big commits. Also, if something goes wrong in the code we can always revert the repo to a prior commit. 10 | 11 | #### To stage a file for commit, enter: 12 | ``` 13 | git add 14 | ``` 15 | #### to stage all altered files, enter: 16 | ``` 17 | git add . 18 | ``` 19 | **Note:** It is much more common to just stage every altered file rather than pick and choose. However, if you only want to bundle certain files in a commit then feel free to do so. 20 | 21 | #### To bundle a commit, enter: 22 | ``` 23 | git commit -m 24 | ``` 25 | Where `` is a message describing what your commit does. To use the Pong example from before, a good description would be something like `"allows user to change the background color"`. 26 | 27 | #### To check the status of your files, enter: 28 | ``` 29 | git status 30 | ``` 31 | This is a very helpful command in showing you which files are and aren't staged. It also provides helpful commands to undo staging and commits if you ever need to do so. 32 | 33 | ## Challenge 3: 34 | 35 | 1. Create a file in the `people` subdirectory with your first and last name titled `firstname_lastname.txt`. 36 | 2. Put a random sentence inside. 37 | 3. Add a line containing your name to the comment in `printer.py` 38 | 4. Run `python run.py` to see your name added to the chain! Change your own file as much as you'd like. 39 | 5. Stage the files and bundle them in a commit. 40 | 41 | [Next: Push your local changes to GitHub](../part5-pushing_changes_to_github) -------------------------------------------------------------------------------- /part4-changing_the_code/people/seun_omonije.txt: -------------------------------------------------------------------------------- 1 | Follow me on ig @seunomonije, twitter @computabeast, tiktok @s3un -------------------------------------------------------------------------------- /part4-changing_the_code/printer.py: -------------------------------------------------------------------------------- 1 | import os 2 | import re 3 | 4 | def regex_split_and_rejoin(string): 5 | split_string = re.split(r'_|\.', string) 6 | split_string.pop() # Remove .txt 7 | return " ".join(split_string) 8 | 9 | def print_cell(name, contents): 10 | print('---\n') 11 | print(f'Name: {name}') 12 | print(f'Message: {contents}') 13 | print('\n---') 14 | 15 | def main(): 16 | for filename in os.listdir('people/'): 17 | with open(os.path.join('people/', filename), 'r') as f: 18 | name = regex_split_and_rejoin(filename) 19 | contents = f.read() 20 | print_cell(name, contents) 21 | 22 | """ 23 | These are the names of the people who should be printed. 24 | seun omonije 25 | """ -------------------------------------------------------------------------------- /part4-changing_the_code/run.py: -------------------------------------------------------------------------------- 1 | import sys 2 | 3 | if sys.version_info[0] < 3: 4 | sys.stdout.write("You need Python 3.0 or higher to run this.\nTry: python3 run.py\n") 5 | sys.exit(1) 6 | 7 | from printer import main 8 | 9 | if __name__ == '__main__': 10 | main() -------------------------------------------------------------------------------- /part5-pushing_changes_to_github/README.md: -------------------------------------------------------------------------------- 1 | ## Pushing your local changes to GitHub 2 | Now that you've created your own branch and made some changes, its time to push them to GitHub. 3 | 4 | The great thing about Git is all the work you did before makes it simple to push your changes to the internet. 5 | 6 | #### To push your change to GitHub, enter: 7 | ``` 8 | git push origin 9 | ``` 10 | Where `` is the name of the branch you've created. 11 | 12 | #### But what's going on here? In simple terms: 13 | - `git push` is the command that tells Git its time to push the commits 14 | - `origin` tells git which repo to push the commits to. If you type `git remote -v` you'll get a list of remotes and their corresponding names and you'll see that `origin` points to the online version of this repo. This parameter gets more interesting when dealing with [Forked repositories](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/working-with-forks). 15 | - `` tells git which branch of the repo to push your commits to. You won't have access to directly push to the master branch of this repo, so you'll need to specify your branch every time. 16 | 17 | If everything worked successfully, you should be able to see your branch under the branches tab or the branches link. (See image below) 18 | 19 | ![](branches-link.png) 20 | 21 | ## Challenge 4: 22 | 23 | Push the changes you staged in the last part to GitHub! 24 | 25 | [Next: Open a pull request to merge your code with the master branch](../part6-pull_requests) -------------------------------------------------------------------------------- /part5-pushing_changes_to_github/branches-link.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/yaleqc/github-basics/8ae1d0d249f4a927232b3f372f9e7904a4359405/part5-pushing_changes_to_github/branches-link.png -------------------------------------------------------------------------------- /part6-pull_requests/README.md: -------------------------------------------------------------------------------- 1 | ## Opening pull requests 2 | 3 | The final step in making sure that your changes make it into the project is opening up a **pull request**. Pull requests compare your branch to the another branch of the repository, allow for your code to be reviewed and any necessary changes to be made, and handle branch merging automatically. The normal process of submitting code to the master branch via pull requests looks like this: 4 | 1. You push your contributions to your personal branch 5 | 2. You open up a pull request between your branch and the master branch 6 | 3. You add reviewers to your code to check it before merging. 7 | 4. Reviewers either approve or request changes to your code. 8 | 5. Once the code is approved, you merge your changes into the master branch! 9 | 10 | #### To open up a pull request: 11 | 12 | 1. Open up the branch menu on the repository's home page and select your branch. 13 | 14 | 15 | 2. From the bar on top of the branch contents, click the Pull request button. 16 | 17 | 18 | 3. Looking at the dropdown menu, set the *base* branch to `master` and the *compare* branch to the branch that you made your changes in. 19 | 20 | 21 | 4. Add a title and description for your PR. 22 | 23 | 24 | 5. Select **Create Pull Request** (or draft if needed) and you're good to go! 25 | 26 | 27 | ###### Source: [GitHub Docs: Creating a pull request](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request) 28 | 29 | Now, let's say that your need to make some changes to your code you submit the PR. As mentioned in a prior part, all you'll have to make the changes locally and push to your branch, and the updates will automatically be reflected in PR. This is how you make changes brought up in **Code Reviews**. If you want to learn more about code reviews, see the [GitHub Docs: About pull request reviews](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-request-reviews). 30 | 31 | If you don't need to make any changes, the reviewer will approve the PR, and the changes will either be automatically merged in, the reviewer can do it, or you can do it yourself! 32 | 33 | **Note:** If your branch has gotten out of sync with the master branch, you may get a **merge conflict**. To avoid this, make sure your personal branch up to date with master by runing: 34 | ``` 35 | git checkout 36 | git fetch origin 37 | git pull origin master 38 | ``` 39 | This is explained further in the next part. 40 | 41 | To learn more about merge conflicts, check out the [GitHub Docs: About merge conflicts](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-merge-conflicts). 42 | ## Challenge 5: 43 | 44 | Take the changes you pushed to GitHub in the last part and open up a pull request! **Hint: if you followed the tutorial, you cloned a fork of this repository. [This link might be helpful.](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request-from-a-fork)** If everything checks out, your work in Challenge 3 will be merged into the master branch! 45 | 46 | [Next: Keeping up with the repository](../part7-keeping_up_with_repo) -------------------------------------------------------------------------------- /part6-pull_requests/branch-dropdown.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/yaleqc/github-basics/8ae1d0d249f4a927232b3f372f9e7904a4359405/part6-pull_requests/branch-dropdown.png -------------------------------------------------------------------------------- /part6-pull_requests/choose-base-and-compare-branches.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/yaleqc/github-basics/8ae1d0d249f4a927232b3f372f9e7904a4359405/part6-pull_requests/choose-base-and-compare-branches.png -------------------------------------------------------------------------------- /part6-pull_requests/pull-request-start-review-button.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/yaleqc/github-basics/8ae1d0d249f4a927232b3f372f9e7904a4359405/part6-pull_requests/pull-request-start-review-button.png -------------------------------------------------------------------------------- /part6-pull_requests/pullrequest-description.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/yaleqc/github-basics/8ae1d0d249f4a927232b3f372f9e7904a4359405/part6-pull_requests/pullrequest-description.png -------------------------------------------------------------------------------- /part6-pull_requests/pullrequest-send.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/yaleqc/github-basics/8ae1d0d249f4a927232b3f372f9e7904a4359405/part6-pull_requests/pullrequest-send.png -------------------------------------------------------------------------------- /part7-keeping_up_with_repo/README.md: -------------------------------------------------------------------------------- 1 | ## Keeping up with the repository 2 | 3 | If you've successfully gotten your PR out, congrats! You're almost there! 4 | 5 | Now things get a bit more interesting. What happens when other people update the master branch? 6 | 7 | If you've completed all the challenges one sitting, there's a pretty good chance that no updates to the master branch of this repo have been made and you don't need to worry about what we call **merge conflicts**. Merge conflicts happen when two branches differ outside of the changes that were committed. For example, let's take the main characters from the quantum world, Alice and Bob, and assume that they're both collaborating on a project. Now assume the following happens: 8 | 9 | 1. Alice and Bob both clone the repo on Monday. 10 | 2. Alice and Bob both create their dev branches and get to work on their code. 11 | 3. Alice finishes her code on Tuesday and submits a pull request to merge her dev branch to master. Master has not changed, so the branch is merged seamlessly. 12 | 4. Bob finishes his code on Wednesday and tries to merge his dev branch to master. Master from Bob's perspective is now different than master from Alice's perspective, and so a conflict occurs, since Git isn't sure which master is the correct one. 13 | 14 | So how do we resolve this conflict? The easiest way to resolve merge conflicts is by preventing them. This means keeping both your local master and dev branch up to date with the master branch on GitHub. An easy way to do this is, before you ever push any changes to your dev branch, pull the changes from the online master branch to your local master and dev branch. 15 | 16 | #### To pull changes to a branch, enter: 17 | ``` 18 | git checkout 19 | git fetch origin 20 | git pull origin master 21 | ``` 22 | 23 | Where `` is the name of the branch you want to update. You can update both master and your dev branch by checking them out and running fetch/pull on each. 24 | 25 | And with that, you've learned exactly what's needed to contribute to a large majority of open-source projects on GitHub, and now have a basic toolkit of Git commands under your belt. If there are any issues in any of the READMEs, or you feel that there's something valuable to add to this tutorial, you're now equipped to submit a pull request and fix it! (And I highly encourage you to do so!) 26 | 27 | If you want to learn more about the ins and outs of Git and GitHub, check out the following links: 28 | - [GitHub Docs](https://docs.github.com/en) 29 | - [Git Documentation](https://git-scm.com/doc) --------------------------------------------------------------------------------