collaborating_on_github.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# My First Pull Request Tutorial\n",
    "\n",
    "Let's say you've caught a bug in open source code that you would like to correct. We'll walk through the steps to making a _pull request_ in this tutorial.\n",
    "\n",
    "### What's a pull request? \n",
    "\n",
    "Some open source projects like [astropy](https://github.com/astropy/astropy) have >100 contributors located all around the world. How do you successfully manage the efforts of so many people? \n",
    "\n",
    "Contributors to the astropy repository _fork_, or make their own copy of, the astropy repository. They make changes on their fork, where no special permissions are needed to make changes. Then, they can offer those changes back to the _upstream_ repository, or the repository that they forked, in a _pull request_. The pull request is a means of offering your changes to the \"official\" version of the repository, where collaborators can review your changes and choose to _merge_ them, i.e. accept them into the upstream repository, or not.\n",
    "\n",
    "### Exercise Intro\n",
    "\n",
    "We will work on this [demo repository](https://github.com/bmorris3/bootcamp_demo/blob/master/functions.py), which has a bunch of non-functioning functions written in it. Your task in this lesson will be to:\n",
    "1. Fork the demo repo, and clone your fork\n",
    "2. Create an _issue_ where you describe what work needs to be done\n",
    "3. Create a _feature branch_\n",
    "4. Implement one of the non-implemented functions in your feature branch\n",
    "5. Add, commit and push your update to github\n",
    "6. Create a pull request to the upstream repository\n",
    "7. Pull changes from upstream\n",
    "\n",
    "## 1) Fork, clone the demo repository\n",
    "\n",
    "Follow this link to the [demo repository](https://github.com/bmorris3/bootcamp_demo/), and click the **Fork** button in the upper-right corner of the webpage. This will create a copy of this repository that you have permission to edit as you please. When the repo has been successfully forked, you will be taken to a webpage that's labeled `<your git username>/bootcamp_demo` in the upper-left corner. \n",
    "\n",
    "Now from your forked repo, click the green \"Clone or download\" button. You'll now see a link that you can use to _clone_ the repository. Copy that link, which looks like: `git@github.com:<your username>/bootcamp_demo.git`.\n",
    "\n",
    "In your Terminal, go to a directory where you want to put the demo repository, and run:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "Cloning into 'bootcamp_demo'...\n"
     ]
    }
   ],
   "source": [
    "%%bash\n",
    "git clone git@github.com:bmorris3/bootcamp_demo.git"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "(where the `bmorris3` above is replaced with your username). Now change directories into the `bootcamp_demo` repo.\n",
    "\n",
    "In there, you will see a script called `functions.py`: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "# Here are some functions that you can fill in to make them work.\n",
      "# Replace the \"raise NotImplementedError\" line with the correct code!\n",
      "\n",
      "def print_the_instructors_name():\n",
      "    raise NotImplementedError\n",
      "\n",
      "def print_the_number_of_this_room():\n",
      "    raise NotImplementedError\n",
      "\n",
      "def split_this_string_at_each_space(input_string):\n",
      "    raise NotImplementedError\n",
      "\n",
      "def take_the_average_of_these_numbers(a, b):\n",
      "    raise NotImplementedError\n",
      "\n",
      "def print_the_time_now_using_astropy():\n",
      "    raise NotImplementedError\n",
      "\n",
      "def return_the_minimum_of_two_numbers(a, b):\n",
      "    raise NotImplementedError\n",
      "\n",
      "def return_the_std_of_two_numbers(a, b):\n",
      "    raise NotImplementedError\n"
     ]
    }
   ],
   "source": [
    "%%bash\n",
    "cd bootcamp_demo\n",
    "\n",
    "cat functions.py"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "There are a bunch of functions in this file that are not yet implemented. Their names tell you what they intend to do, but the source of each function simply says: \"when this function is executed, raise an error\".\n",
    "\n",
    "Chose one of these functions to work on, or chose to add a new function of your own.\n",
    "\n",
    "### 2) Create an issue\n",
    "\n",
    "When you find a bug or chose to add a new feature to a repository, you should create an [_issue_ on the GitHub page of the upstream repository](https://github.com/bmorris3/bootcamp_demo/issues). Issues are useful because they allow you to solicit for help from the other contributors, and to start discussions about new features, bugfixes, improvements, etc. They also form a public record of previous discussions, which can be very useful for future contributors. \n",
    "\n",
    "Click [here](https://github.com/bmorris3/bootcamp_demo/issues/1) to see a demo issue that I created. Issues usually point to a particular piece of code and ask why or how it's supposed to work, or demonstrate an unexpected output from a function.\n",
    "\n",
    "Post an issue in the demo repo, volunteering to implement one function. You can tag people in the issue (like me, @bmorris3) if you want them to be notified to look at the issue.\n",
    "\n",
    "### 3) Create a branch\n",
    "\n",
    "Now you are going to implement your new feature. Before you do so, you should create a _branch_. A branch is an independent copy of a repository that has its own history, independent of other branches. This is useful if you're developing multiple features at once – each feature should be developed on its own branch.\n",
    "\n",
    "To see what branches exist in this repository, type:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "* master\n"
     ]
    }
   ],
   "source": [
    "%%bash\n",
    "cd bootcamp_demo\n",
    "\n",
    "git branch"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The branch that you're currently working on has a `*` next to its name. To create a new branch called `new-feature`, you can type: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "%%bash\n",
    "cd bootcamp_demo\n",
    "\n",
    "git branch new-feature"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "but you should create a branch with a more descriptive name. \n",
    "\n",
    "Now if you check the branches: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "* master\n",
      "  new-feature\n"
     ]
    }
   ],
   "source": [
    "%%bash\n",
    "cd bootcamp_demo\n",
    "\n",
    "git branch"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You'll see the new branch exists. To work on the new branch, try:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "Switched to branch 'new-feature'\n"
     ]
    }
   ],
   "source": [
    "%%bash\n",
    "cd bootcamp_demo\n",
    "\n",
    "git checkout new-feature"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You're now working on your new feature branch. You can check that by running `git status`, which will tell you that you're working `On branch new-feature`.\n",
    "\n",
    "To switch back to the master branch, you could `git checkout master`.\n",
    "\n",
    "### 4) Implement a new feature\n",
    "\n",
    "Now make your change to the `functions.py` file. You can chose to edit one of the existing functions, create a new one, or add a comment somewhere. Be creative!\n",
    "\n",
    "### 5) Pushing your change to your repo on GitHub \n",
    "\n",
    "Before you can offer this change to the upstream repository, you have to push your changes to GitHub. This is how we'll do that:\n",
    "1. `add` the file that has changes that you want to track\n",
    "2. `commit` the changes with a descriptive message\n",
    "3. `push` the changes to GitHub"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[new-feature 15dbf2d] Added a newline\n",
      " 1 file changed, 1 insertion(+)\n"
     ]
    },
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "Everything up-to-date\n"
     ]
    }
   ],
   "source": [
    "%%bash\n",
    "cd bootcamp_demo\n",
    "\n",
    "git add functions.py\n",
    "git commit -m \"Added a newline\"\n",
    "git push origin master"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 6) Creating a pull request\n",
    "\n",
    "Now when you visit your repository on GitHub, you'll see that the `functions.py` file has the update that you made on your local machine. In order to offer that change to the upstream repo, click the `New Pull Request` button in the middle-left of the page. You should now see a `diff` of the file that you changed, showing the code that you removed (or changed) in red on the left, and the code that you added on the right in green. \n",
    "\n",
    "Click the green `Create Pull Request` button to go to the pull request page. At the top of the page, you should now see \"Open a pull request\". Give your PR a title that nicely summarizes what you did in a few words. Explain in more detail what you did in the \"comments\" section, and tag me (`@bmorris3`) asking for my comments. \n",
    "\n",
    "Click the last green button to submit the pull request. Brett will now be notified about the PR, and will review the code, and even merge it.\n",
    "\n",
    "### 7) Pull changes from upstream\n",
    "\n",
    "Once you've made your pull requests, I will _merge_ some of them. After the merge, your commits will be applied to the _upstream_ repo. But now your master branch no longer reflects what the upstream repo looks like. \n",
    "\n",
    "To update your master branch, let's change branches to _master_:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Your branch is up-to-date with 'origin/master'.\n"
     ]
    },
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "Switched to branch 'master'\n"
     ]
    }
   ],
   "source": [
    "%%bash\n",
    "cd bootcamp_demo\n",
    "\n",
    "git checkout master"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now we need to setup a _remote_ for upstream. A remote is a GitHub address other than the one for your fork of the upstream repository. To see what remotes you currently have in this repo, do: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "origin\tgit@github.com:bmorris3/bootcamp_demo.git (fetch)\n",
      "origin\tgit@github.com:bmorris3/bootcamp_demo.git (push)\n"
     ]
    }
   ],
   "source": [
    "%%bash\n",
    "cd bootcamp_demo\n",
    "\n",
    "git remote -v"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "(your origin will point towards the _fork_ that you made). Now we'll add a remote for upstream, which is my version of the repository:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "origin\tgit@github.com:bmorris3/bootcamp_demo.git (fetch)\n",
      "origin\tgit@github.com:bmorris3/bootcamp_demo.git (push)\n",
      "upstream\tgit@github.com:bmorris3/bootcamp_demo.git (fetch)\n",
      "upstream\tgit@github.com:bmorris3/bootcamp_demo.git (push)\n"
     ]
    }
   ],
   "source": [
    "%%bash\n",
    "cd bootcamp_demo\n",
    "\n",
    "git remote add upstream git@github.com:bmorris3/bootcamp_demo.git\n",
    "git remote -v"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now you can _pull_ the changes that have been made on the upstream branch down to your fork:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Already up-to-date.\n"
     ]
    },
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "From github.com:bmorris3/bootcamp_demo\n",
      " * branch            master     -> FETCH_HEAD\n",
      " * [new branch]      master     -> upstream/master\n"
     ]
    }
   ],
   "source": [
    "%%bash\n",
    "cd bootcamp_demo\n",
    "\n",
    "git pull upstream master"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The message that you see above should reflect the changes that have been made since you first forked the upstream repo."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Independent exercise\n",
    "\n",
    "In the future, you may consider making a contribution to [astropy](https://github.com/astropy/astropy), the poster-child of community software development in astronomy. When considering how to contribute, you can make use of issue labels. For example, the [`package-novice` label](https://github.com/astropy/astropy/issues?q=is%3Aopen+is%3Aissue+label%3APackage-novice) indicates that you don't have to know much about astropy to fix this issue, or the [`effort-low` label](https://github.com/astropy/astropy/issues?utf8=✓&q=is%3Aopen%20is%3Aissue%20label%3AEffort-low%20) for issues that can be fixed with only a small investment of time. For your first contribution to astropy, you might search for issues with both of these labels.\n",
    "\n",
    "Now on your own or with a partner: \n",
    "\n",
    "1. Fork [astropy](https://github.com/astropy/astropy), and make a local clone of your fork\n",
    "2. Create a new branch where you can implement a fix for an issue\n",
    "3. Dig into the code where you'd make the change requested in the issue. If you know what to do, attempt to solve the issue. If you don't know how to fix the issue, make a superficial change to the code and we will pretend that it solved the issue.\n",
    "4. Add, commit and push your change to your GitHub repo. \n",
    "5. Create a pull request to astropy. **Do not actually submit** the PR to astropy unless you've implemented a viable fix."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.5.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 0
}