Guide_Git_GitHub.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "# Git and GitHub and CLIMADA\n",
    "Chris Fairless"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# Contents\n",
    "- Git and Github\n",
    "- GitFlow\n",
    "- The CLIMADA release cycle\n",
    "- How to write a new module\n",
    "- Pull requests\n",
    "- Issues"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# Introduction\n",
    "![](https://source.unsplash.com/1600x900/?introduction)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Git and GitHub\n",
    "\n",
    "- Git's not that scary\n",
    "    - 95% of your work on Git will be done with the same handful of commands\n",
    "    - (the other 5% will always be done with careful Googling)\n",
    "    - Almost everything in Git can be undone by design (but use `rebase`, `--force` and `--hard` with care!)\n",
    "    - Your favourite IDE (Spyder, PyCharm, ...) will have a GUI for working with Git, or you can download a standalone one.\n",
    "- The [Git Book](https://git-scm.com/book/en/v2) is a great introduction to how Git works and to using it on the command line.\n",
    "- Feel free to ask for help"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "![](img/git_gui.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## What I assume you know\n",
    "\n",
    "I'm assuming you're all familiar with the basics of Git.\n",
    "\n",
    "- What (and why) is version control\n",
    "- How to clone a repository\n",
    "- How to make a commit and push it to GitHub\n",
    "- What a branch is, and how to make one\n",
    "- How to merge two branches\n",
    "- The basics of the GitHub website\n",
    "\n",
    "If you're not feeling great about this, I recommend\n",
    "- sending me a message so we can arrange an introduction with CLIMADA\n",
    "- exploring the [Git Book](https://git-scm.com/book/en/v2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Terms we'll be using today\n",
    "\n",
    "These are terms I'll be using a lot today, so let's make sure we know them\n",
    "\n",
    "- local versus remote\n",
    "    - Our **remote** repository is hosted on GitHub. This is the central location where all updates to CLIMADA that we want to share end up. If you're updating CLIMADA for the community, your code will end up here too.\n",
    "    - Your **local** repository is the copy you have on the machine you're working on, and where you do your work.\n",
    "    - Git calls the (first, default) remote the `origin`\n",
    "    - (It's possible to set more than one remote repository, e.g. you might set one up on a network-restricted computing cluster)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "- push, pull and pull request\n",
    "    - You **push** your work when you send it from your local machine to the remote repository\n",
    "    - You **pull** from the remote repository to update the code on your local machine\n",
    "    - A **pull request** is a standardised review process on GitHub. Usually it ends with one branch merging into another"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "- Conflict resolution\n",
    "    - Sometimes two people have made changes to the same bit of code. Usually this comes up when you're trying to merge branches. The changes have to be manually compared and the code edited to make sure the 'correct' version of the code is kept. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# Gitflow\n",
    "![](https://source.unsplash.com/1600x900/?git&flow)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# Gitflow\n",
    "\n",
    "Gitflow is a particular way of using git to organise projects that have\n",
    "- multiple developers\n",
    "- working on different features\n",
    "- with a release cycle\n",
    "\n",
    "It means that\n",
    "- there's always a stable version of the code available to the public\n",
    "- the chances of two developers' code conflicting are reduced\n",
    "- the process of adding and reviewing features and fixes is more standardised for everyone\n",
    "\n",
    "Gitflow is a _convention_, so you don't need any additional software.\n",
    "- ... but if you want you can get some: a popular extension to the git command line tool allows you to issue more intuitive commands for a Gitflow workflow.\n",
    "- Mac/Linux users can install git-flow from their package manager, and it's included with Git for Windows "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Gitflow works on the `develop` branch instead of `main`\n",
    "\n",
    "![](flow_1.png)\n",
    "\n",
    "- The critical difference between Gitflow and 'standard' git is that almost all of your work takes place on the `develop` branch, instead of the `main` (formerly `master`) branch.\n",
    "- The `main` branch is reserved for planned, stable product releases, and it's what the general public download when they install CLIMADA. The developers almost never interact with it."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Gitflow is a feature-based workflow\n",
    "\n",
    "![](img/flow_2.png)\n",
    "\n",
    "- This is common to many workflows: when you want to add something new to the model you start a new branch, work on it locally, and then merge it back into `develop` **with a pull request** (which we'll cover later)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "- By convention we name all CLIMADA feature branches `feature/*` (e.g. `feature/meteorite`).\n",
    "- Features can be anything, from entire hazard modules to a smarter way to do one line of a calculation. Most of the work you'll do on CLIMADA will be a features of one size or another.\n",
    "- We'll talk more about developing CLIMADA features later!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Gitflow enables a regular release cycle\n",
    "\n",
    "![](img/flow_3.png)\n",
    "\n",
    "- A release is usually more complex than merging `develop` into `main`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "- So for this a `release-*` branch is created from `develop`. We'll all be notified repeatedly when the deadline is to  submit (and then to review) pull requests so that you can be included in a release.\n",
    "- The core developer team (mostly Emanuel) will then make sure tests, bugfixes, documentation and compatibility requirements are met, merging any fixes back into `develop`.\n",
    "- On release day, the release branch is merged into `main`, the commit is tagged as a release and the release notes are published on the GitHub at https://github.com/CLIMADA-project/climada_python/releases"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Everything else is hotfixes\n",
    "\n",
    "![](img/flow_4.png)\n",
    "\n",
    "- The other type of branch you'll create is a hotfix."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "- Hotfixes are generally small changes to code that do one thing, fixing typos, small bugs, or updating docstrings. They're done in much the same way as features, and are usually merged with a pull request.\n",
    "- The difference between features and hotfixes is fuzzy and you don't need to worry about getting it right.\n",
    "- Hotfixes will occasionally be used to fix bugs on the `main` branch, in which case they will merge into both `main` and `develop`.\n",
    "- Some hotfixes are so simple - e.g. fixing a typo or a docstring - that they don't need a pull request. Use your judgement, but as a rule, if you change what the code does, or how, you should be merging with a pull request."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# Features\n",
    "![](https://source.unsplash.com/1600x900/?features)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# Planning a new feature\n",
    "\n",
    "Here we're talking about large features such as new modules, new data sources, or big methodological changes. Any extension to CLIMADA that might affect other developers' work, modify the CLIMADA core, or need a big code review.\n",
    "\n",
    "Smaller feature branches don't need such formalities. Use your judgment, and if in doubt, let people know.\n",
    "\n",
    "## Talk to the group\n",
    "  - This is the chance to work out the Big Picture stuff that is better when it's planned with the group - possible intersections with other projects, possible conflicts, changes to the CLIMADA core, additional dependencies (see Chahan's presentation later)\n",
    "  - Talk with the core development team ([see the GitHub wiki](https://github.com/CLIMADA-project/climada_python/wiki/Developer-Board)), especially Chahan and Emanuel (as I write this).\n",
    "  - Bring it to a developers meeting - people may be able to help/advise and are always interested in hearing about new projects. You can also find reviewers!\n",
    "  - Also, keep talking! Your plans _will_ change :)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Planning the work\n",
    "\n",
    "- Does the project go in its own repository and import CLIMADA, or does it extend the main CLIMADA repository?\n",
    "    - The way this is done is slowly changing, so definitely discuss it with the group.\n",
    "    - Chahan will discuss this later!\n",
    "- Find a few people who will help to review your code.\n",
    "    - Ask in a developers' meeting, on Slack (for WCR developers) or message people on the development team ([see the GitHub wiki](https://github.com/CLIMADA-project/climada_python/wiki/Developer-Board)).\n",
    "    - Let them know roughly how much code will be in the reviews, and when you'll be creating pull requests.\n",
    "- How can the work split into manageable chunks?\n",
    "    - A series of smaller pull requests is far more manageable than one big one (and takes off some of the pre-release pressure)\n",
    "    - Reviewing and spotting issues/improvements/generalisations early is always a good thing.\n",
    "    - It encourages modularisation of the code: smaller self-contained updates, with documentation and tests.\n",
    "- Will there be any changes to the CLIMADA core?\n",
    "    - These should be planned carefully\n",
    "- Will you need any new dependencies? Are you sure?\n",
    "    - Chahan will discuss this later!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Your feature branch\n",
    "\n",
    "When developing a big new feature, consider creating a feature branch and merging smaller branches into that feature branch with pull requests, keeping the whole process separate from `develop` until it's completed. This makes step-by-step code review nice and easy, and makes the final merge more easily tracked in the history.\n",
    "\n",
    "e.g. developing the big `feature/meteorite` module you might write `feature/meteorite-hazard` and merge it in, then `feature/meteorite-impact`, then `feature/meteorite-stochastic-events` etc... before finally merging `feature/meteorite` into `develop`. Each of these could be a reviewable pull request.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# Pull requests\n",
    "![](https://source.unsplash.com/1600x900/?pull&request)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# Pull requests\n",
    "\n",
    "We want every line of code that goes into the CLIMADA repository to be reviewed!\n",
    "\n",
    "Code review:\n",
    "- catches bugs (there are _always_ bugs)\n",
    "- lets you draw on the experience of the rest of the team\n",
    "- makes sure that more than one person knows how your code works\n",
    "- helps to unify and standardise CLIMADA's code, so new users find it easier to read and navigate\n",
    "- creates an archived description and discussion of the changes you've made"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## When to make a pull request\n",
    "\n",
    "- When you've finished writing a big new class or method (and its tests)\n",
    "- When you've fixed a bug or made an improvement you want to merge\n",
    "- When you want to merge a change of code into `develop` or `main`\n",
    "- When you want to _discuss_ a bit of code you've been working on - pull requests aren't only for merging branches\n",
    "\n",
    "Not all pull requests have to be into `develop` - you can make a pull request into any active branch that suits you."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Step by step pull request!\n",
    "\n",
    "Let's suppose you've developed a cool new module on the `feature/meteorite` branch and you're ready to merge it into `develop`.\n",
    "\n",
    "### Checklist before you start\n",
    "\n",
    "- Documentation\n",
    "- Tests\n",
    "- Tutorial (if a complete new feature)\n",
    "- Updated dependencies (if need be)\n",
    "- Added your name to the AUTHORS file\n",
    "- (Advanced, optional) interactively rebase/squash recent commits that _aren't yet on GitHub_.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Step by step pull request!\n",
    "\n",
    "1) Make sure the `develop` branch is up to date on your own machine\n",
    "```\n",
    "git checkout develop\n",
    "git pull\n",
    "```\n",
    "\n",
    "2) Merge `develop` into your feature branch and resolve any conflicts\n",
    "```\n",
    "git checkout feature/meteorite\n",
    "git merge develop\n",
    "```\n",
    "\n",
    "In the case of more complex conflicts, you may want to speak with others who worked on the same code. Your IDE should have a tool for conflict resolution.\n",
    "    \n",
    "3) Check all the tests pass locally\n",
    "```\n",
    "make unit_test\n",
    "make integ_test\n",
    "```\n",
    "\n",
    "4) Perform a static code analysis using pylint with CLIMADA's configuration `.pylintrc` (in the climada root directory). Jenkins executes it after every push. To do it locally, your IDE probably provides a tool, or you can run `make lint` and see the output in `pylint.log`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "5) Push to GitHub.\n",
    "    If you're pushing this branch for the first time, use\n",
    "```\n",
    "git push -u origin feature/meteorite\n",
    "```\n",
    "and if you're updating a branch that's already on GitHub:\n",
    "```\n",
    "git push\n",
    "```\n",
    "\n",
    "6) Check all the tests pass on the WCR Jenkins server (https://ied-wcr-jenkins.ethz.ch). See Emanuel's presentation for how to do this! You should regularly be pushing your code and checking this!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "7) Create the pull request!\n",
    "\n",
    "- On the CLIMADA GitHub page, navigate to your feature branch (there's a drop-down menu above the file structure, pointing by default to `main`).\n",
    "- Above the file structure is a branch summary and an icon to the right labelled \"Pull request\".\n",
    "- Choose which branch you want to merge with. This will usually be `develop`, but may be another feature branch for more complex feature development.\n",
    "- Give your pull request an informative title (like a commit message).\n",
    "- Write a description of the pull request. This can usually be adapted from your branch's commit messages (you wrote informative commit messages, didn't you?), and should give a high-level summary of the changes, specific points you want the reviewers' input on, and explanations for decisions you've made. The code documentation (and any references) should cover the more detailed stuff. \n",
    "- Assign reviewers in the page's right hand sidebar. Tag anyone who might be interested in reading the code. You should already have found one or two people who are happy to read the whole request and sign it off (they could also be added to 'Assignees').\n",
    "- Create the pull request.\n",
    "- Contact the reviewers to let them know the request is live. GitHub's settings mean that they may not be alerted automatically. Maybe also let people know on the WCR Slack!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "8) Talk with your reviewers\n",
    "\n",
    "- Use the comment/chat functionality within GitHub's pull requests - it's useful to have an archive of discussions and the decisions made.\n",
    "- Take comments and suggestions on board, but you don't need to agree with everything and you don't need to implement everything.\n",
    "- If you feel someone is asking for too many changes, prioritise, especially if you don't have time for complex rewrites.\n",
    "- If the suggested changes and or features don't block functionality and you don't have time to fix them, they can be moved to Issues.\n",
    "- Chase people up if they're slow. People are slow.\n",
    "\n",
    "9) If the review takes a while, remember to merge `develop` back into the feature branch every now and again (and check the tests are still passing on Jenkins). Anything pushed to the branch is added to the pull request.\n",
    "\n",
    "10) Once everyone reviewing has said they're satisfied with the code you can merge the pull request using the GitHub interface. Delete the branch once it's merged, there's no reason to keep it. (Also try not to re-use that branch name later.)\n",
    "\n",
    "11) Update the `develop` branch on your local machine.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# How to review a pull request\n",
    "\n",
    "- Be friendly\n",
    "- Decide how much time you can spare and the detail you can work in. Tell the author!\n",
    "- Use the comment/chat functionality within GitHub's pull requests - it's useful to have an archive of discussions and the decisions made.\n",
    "- Fix the big things first! If there are more important issues, not every style guide has to be stuck to, not every slight increase in speed needs to be pointed out, and test coverage doesn't have to be 100%.\n",
    "- Make it clear when a change is optional, or is a matter of opinion"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "At a minimum\n",
    "- Make sure unit and integration tests are passing on Jenkins\n",
    "- (For complete modules) Run the tutorial on your local machine and check it does what it says it does\n",
    "- Check everything is fully documented"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "At least one reviewer needs to\n",
    "- Review all the changes in the pull request. Read what it's supposed to do, check it does that, and make sure the logic is sound.\n",
    "- Check that the code follows the CLIMADA style guidelines `#TODO: link`\n",
    "- If the code is implementing an algorithm it should be referenced in the documentation. Check it's implemented correctly.\n",
    "- Try to think of edge cases and ways the code could break. See if there's appropriate error handling in cases where the function might behave unexpectedly.\n",
    "- (Optional) suggest easy ways to speed up the code, and more elegant ways to achieve the same goal.\n",
    "\n",
    "There are a few ways to suggest changes\n",
    "- As questions and comments on the pull request page\n",
    "- As code suggestions (max a few lines) in the code review tools on GitHub. The author can then approve and commit the changes from GitHub pull request page. This is great for typos and little stylistic changes.\n",
    "- If you decide to help the author with changes, you can either push them to the same branch, or create a new branch and make a pull request with the changes back into the branch you're reviewing. This lets the author review it and merge."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# General tips and tricks\n",
    "![](https://source.unsplash.com/1600x900/?tips&tricks)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Ask for help with Git\n",
    "\n",
    "- Git isn't intuitive, and rewinding or resetting is always work. If you're not certain what you're doing, or if you think you've messed up, send someone a message."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Don't push or commit to `develop` or `main`\n",
    "\n",
    "- Almost all new additions to CLIMADA should be merged into the `develop` branch with a pull request.\n",
    "- You won't merge into the `main` branch, except for emergency hotfixes (which should be communicated to the team).\n",
    "- You won't merge into the `develop` branch without a pull request, except for small documentation updates and typos.\n",
    "- The above points mean  you should never need to push the `main` or `develop` branches.\n",
    "\n",
    "So if you find yourself on the `main` or `develop` branches typing `git merge ...` or `git push` stop and think again - you should probably be making a pull request.\n",
    "\n",
    "This can be difficult to undo, so contact someone on the team if you're unsure!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Commit more often than you think, and use informative commit messages\n",
    "\n",
    "- Committing often makes mistakes less scary to undo\n",
    "```\n",
    "git reset --hard HEAD\n",
    "```\n",
    "- Detailed commit messages make writing pull requests really easy\n",
    "- Yes it's boring, but _trust me_, everyone (usually your future self) will love you when they're rooting through the git history to try and understand why something was changed"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## What not to commit\n",
    "\n",
    "There are a lot of things that don't belong in the Git repository: \n",
    "- Don't commit data, except for config files and very small files for tests.\n",
    "- Don't commit anything containing passwords or authentication credentials or tokens. (These are annoying to remove from the Git history.) Contact the team if you need to manage authorisations within the code.\n",
    "- Don't commit anything that can be created by the CLIMADA code itself\n",
    "\n",
    "If files like this are going to be present for other users as well, add them to the repository's `.gitignore`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Log ideas and bugs as GitHub Issues\n",
    "\n",
    "If there's a change you might want to see in the code - something that generalises, something that's not quite right, or a cool new feature - it can be set up as a GitHub Issue. Issues are pages for conversations about changes to the codebase and for logging bugs, and act as a 'backlog' for the CLIMADA project.\n",
    "\n",
    "For a bug, or a question about functionality, make a minimal working example, state which version of CLIMADA you are using, and post it with the Issue."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## How not to mess up the timeline\n",
    "![dr_who](img/dr_who.jpg)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "Git builds the repository through incremental edits. This means it's great at keeping track of its history. But there are a few commands that _edit_ this history, and if histories get out of sync on different copies of the repository you're going to have a bad time.\n",
    "\n",
    "- Don't rebase any commits that already exist remotely!\n",
    "- Don't `--force` anything that exists remotely unless you know what you're doing!\n",
    "- Otherwise, you're unlikely to do anything irreversible\n",
    "- You can do what you like with commits that only exist on your machine.\n",
    "\n",
    "That said, doing an interactive rebase to tidy up your commit history _before_ you push it to GitHub is a nice friendly gesture :)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Don't fast forward merges \n",
    "\n",
    "(This shouldn't be relevant - all your merges into `develop` should be through pull requests, which doesn't fast forward. But:)\n",
    "\n",
    "Don't fast forward your merges unless your branch is a single commit. Use\n",
    "`git merge --no-ff ...`\n",
    "\n",
    "The exceptions is when you're merging `develop` into your feature branch."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Merge the remote `develop` branch into your feature branch every now and again\n",
    "\n",
    "- This way you'll find conflicts early\n",
    "```\n",
    "git checkout develop\n",
    "git pull\n",
    "git checkout feature/myfeature\n",
    "git merge develop\n",
    "```\n",
    "- It's especially i"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Create frequent pull requests\n",
    "\n",
    "I said this already:\n",
    "- It structures your workflow\n",
    "- It's easier for reviewers\n",
    "- If you're going to break something for other people you all know sooner\n",
    "- It saves work for the rest of the team right before a release"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Whenever you do something with CLIMADA, make a new local branch \n",
    "\n",
    "You never know when a quick experiment will become something you want to save for later."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## But don't do everything in the CLIMADA repository\n",
    "\n",
    "- If you're running CLIMADA rather than developing it, create a new folder, initialise a new repository with `git init` and store your scripts and data there\n",
    "- If you're writing an extension to CLIMADA that doesn't change the model core, create a new folder, initialise a new repository with `git init` and import CLIMADA. You can always add it to the model later if you need to."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# Questions\n",
    "\n",
    "![Git and Github logos](img/xkcd_git.png)\n",
    "https://xkcd.com/1597/"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "celltoolbar": "Slideshow",
  "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.7.6"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}