0_github_exercise_hands_on.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Introduction to GitHub\n",
    "\n",
    "Contributor: Lukas Franken, Max Parzen\n",
    "\n",
    "#### We will cover\n",
    "\n",
    "1. Overview to GitHub\n",
    "2. Basic pull-push workflow\n",
    "3. Advanced workflow: 5 steps of code contribution\n",
    "4. Hands-on test of workflow"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Prerequisites"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "- Local installation of [git](https://git-scm.com/downloads)\n",
    "- Account on [github](https://github.com/)\n",
    "- Authentication set up on [github](https://docs.github.com/en/authentication/managing-commit-signature-verification)\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 1. Overview to GitHub"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img src=\"images/wiki.PNG\" alt=\"drawing\" width=\"1000\"/>\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Why?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img src=\"images/branching.PNG\" alt=\"drawing\" width=\"500\"/>\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### In practice:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img src=\"images/pypsa-branches.PNG\" alt=\"drawing\" width=\"800\"/>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 2. Basic pull-push workflow"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img src=\"images/pushpull.PNG\" alt=\"drawing\" width=\"300\"/>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Use this notebook as a guide (tutorial/talk.ipynb)\n",
    "\n",
    "- To obtain the hackathon repository, run in your git terminal\n",
    "\n",
    "    ```shell\n",
    "    $ git clone https://github.com/pypsa-meets-africa/pypsa-africa-hackathon.git\n",
    "    ```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Test it out by running the following steps\n",
    "\n",
    "1. Create a new repository in GitHub with a chosen name e.g. 'test'\n",
    "\n",
    "2. Setup a directory on your pc using the git terminal\n",
    "\n",
    "    ```shell\n",
    "    $ mkdir test\n",
    "    $ cd test \n",
    "    \n",
    "    ```\n",
    "\n",
    "\n",
    "3. Run the steps shown in your new repository on GitHub to connect online and local repository\n",
    "\n",
    "4. Make local changes by adding a file  ``` example.py```\n",
    "\n",
    "    ```shell\n",
    "    $ touch example.py\n",
    "    \n",
    "    ```\n",
    "\n",
    "5. Execute the following three commands to push the changes online\n",
    "\n",
    "    ```shell\n",
    "    $ git add example.py\n",
    "    $ git commit -m 'changes have been made'\n",
    "    $ git push\n",
    "\n",
    "    ```\n",
    "\n",
    "6. Check in the online repository that the changes have been received.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 3. Advanced workflow: 5 steps of code contribution"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "__Problem:__ Implementation of features can interfere with other contributor's progress"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "__Solution:__ \n",
    "\n",
    "1. Create your own copy of the repository (**forking**),\n",
    "2. Download the copy of the repository on your PC (**cloning**)\n",
    "3. Create development branch (**branching**),\n",
    "4. Add changes and upload them to your copy (**pushing**)\n",
    "5. Propose the changes to the maintainers of the original *upstream* repository (**pull request**)\n",
    "\n",
    "Tip: Keep the main branch of the 'origin' always updated (i.e. after some contributions were accepted) as well as your development branch to avoid merge conflicts"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img src=\"images/forkpull.PNG\" alt=\"drawing\" width=\"500\"/>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 4. Hands-on test of workflow"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The goal is to implement a function that prints your name using the 5 steps outlined above"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "1. Fork the hackathon repository: navigate to [repository on GitHub](https://github.com/pypsa-meets-africa/pypsa-africa-hackathon) and click the Fork button. Now your fork is online available."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "2. Clone the forked repository locally on your PC (click on the clone button at your fork. Below example for SSH clone): \n",
    "\n",
    "    ```shell\n",
    "    $ git clone git@github.com:<YOU ACCOUNT NAME>/pypsa-africa-hackathon.git\n",
    "    \n",
    "    ```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "3. Checkout a new branch (here called “new_feature”): \n",
    "\n",
    "    ```shell\n",
    "    $ git checkout -b new_feature\n",
    "\n",
    "    ```\n",
    "    Is this branch also available at your \"online\" fork? Not yet, because we need to push changes first to the online repository. So let's do that."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "4. Add changes locally and push them to your 'online' fork\n",
    "\n",
    "- Make changes \n",
    "    - Add your name at the bottom of the README.md\n",
    "    \n",
    "- Add changes\n",
    "    - Check the status by typing in the terminal:\n",
    "        ```\n",
    "            $ git status\n",
    "        ```\n",
    "        You should see an untracked file `README.md`\n",
    "        \n",
    "    - Add the changes to one commit (=snapshot of your repository) by:\n",
    "        ```\n",
    "            $ git add README.md\n",
    "        ```\n",
    "        What is the git status now? Green files would be added to a commit\n",
    "        \n",
    "    - Make a commit with an appropriate *commit message*:\n",
    "        ```\n",
    "            $ git commit\n",
    "        ```\n",
    "\n",
    "- Push changes\n",
    "    - Execute in the terminal:\n",
    "        ```\n",
    "            git push\n",
    "        ```\n",
    "        Are you receiving an error? For every first commit on a new branch it is required to set an upstream, so git\n",
    "        know where to push the changes. Git already recommend often after the error what to do. In my case:\n",
    "        ```\n",
    "            git push --set-upstream origin new_feature\n",
    "        ```\n",
    "    - Check your online fork and the git status in the local repository. Do you understand what happened?\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "5. Pull request\n",
    "\n",
    "    - Checking your fork online you can **compare** and start the **Pull Request (PR)** online with the interface\n",
    "    - Make sure choosing the right branch\n",
    "    \n",
    "    **Tip:** You should keep your branch as long active until the PR is merged. Usually when start developing a feature you create a **draft pull request** to show that you actively working on something. The PR updates with each new commit and shows how you progress and is the best point to ask for help. After the PR is ready for review you can convert it to a *full PR* that one maintainer will review. Once changes are reviewed and accepted (=merged) then you can delete the branch. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Congrats! You just learnt the full process how to add new features to open source projects :)"
   ]
  }
 ],
 "metadata": {
  "interpreter": {
   "hash": "f9bef397ef5e7b2d367b3209d88d895d60e5cf9367d4dd0bd56847f579153646"
  },
  "kernelspec": {
   "display_name": "Python 3.8.0 64-bit",
   "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.8.0"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}