lectures/pkgs_git_github/pkgs_git_github.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "3051a6a4",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# <center>Open source, Git, and GitHub</center>\n",
    "<br>\n",
    "<center>\n",
    "    <div style=\"width:auto; height:100px;\">\n",
    "        <img style=\"float:center; display:inline; height:80px; width:auto;\" src=\"figures/Git-Logo-2Color.png\" />\n",
    "        <img style=\"float:right; display:inline; height:80px; width:auto;\" src=\"figures/GitHub-Mark-120px-plus.png\" />\n",
    "    </div>\n",
    "</center>\n",
    "    \n",
    "### <center>Timothy E. Holy</center>\n",
    "<center>Department of Neuroscience</center>\n",
    "<center>Washington University in St. Louis</center>"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c1d2947c",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# What we'll cover today\n",
    "\n",
    "- open source: expectations, etiquette, and economies\n",
    "- open source licenses\n",
    "- how to recognize a great package\n",
    "- package structure\n",
    "- core git concepts (*not* the practicalities of git or GitHub)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d3fe9607",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "# Covered in your homework\n",
    "\n",
    "Practical use of `git` and GitHub"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9468f7d2",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "![open source rules](figures/os_take_over_world.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "76e3f008",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# Open-source expectations & etiquette"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e49f5e1e",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "- GitHub is a social media platform (people get to know you)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "bfc599a6",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "- Be nice!"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "55d55aa8",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "Specifically:\n",
    "  + you're not a *customer* (you haven't paid anything)\n",
    "  + much of the code is written by volunteers\n",
    "  + the authors are probably like you (busy with a variety of demands and reward structures)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "414ac6d4",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "- Creating great packages takes a diversity of skills (code development, writing documentation, and growing your community). People might be good at some of these and not so good at others"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "31dac47f",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# Open source economies\n",
    "\n",
    "- the currencies are *time* and *passion*"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "bbf0b68e",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "- many developers care about their packages and will fix bugs if you report them. **Most developers are very grateful to receive \"good\" bug reports.**"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9a4714a8",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "- most developers know that code-familiarity helps: if it's my package, I can fix it more efficiently than someone who doesn't know the code"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a355d88d",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "- bug reports should be fully reproducible: whoever handles your issue should be able to copy/paste your code and reproduce the bug. Gold standard: the *MWE = Minimal Working Example*."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "db3d3823",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "- it's OK for a developer to *not* fix your bug or implement your feature request: you can do it, too."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c079065f",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# GitHub repository structure\n",
    "\n",
    "![package structure](figures/repo_structure_dataframes_1.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "51a50aca",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "![readme](figures/repo_structure_dataframes_2.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c5b822f3",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# Things to check when using or contributing: open-source licenses\n",
    "\n",
    "The license declares what you can do with code:\n",
    "- can you use it in a research project?\n",
    "- can you use it to produce a commercial product?\n",
    "- can you share it?\n",
    "- can you modify it?"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3c1d7a4f",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "Categories of license:\n",
    "- restrictive (awareness required even when reading the source code)\n",
    "  + commercial\n",
    "  + \"copyleft\" (examples: GPL, LGPL): fully open, can *use & distribute* without encumberance, but *derived* works must use the same license\n",
    "- permissive (examples: MIT, BSD, Apache): largely unencumbered (but do read the license terms for more specifics)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c37826e4",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## The MIT license\n",
    "\n",
    "\n",
    "    The Revise.jl package is licensed under the MIT \"Expat\" License:\n",
    "\n",
    "    Copyright (c) 2017: Tim Holy.\n",
    "\n",
    "    Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8524e150",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "    The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.\n",
    "\n",
    "    THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "884e0ce4",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# \"Scoping out\" repositories on GitHub\n",
    "\n",
    "To identify packages that are likely to be useful to you, good signs are:\n",
    "- packages you hear about or seem to be widely used\n",
    "- packages with a lot of stars and good documentation\n",
    "- packages with multiple contributors\n",
    "- packages with responsive maintainers (check the history of issues & pull requests)\n",
    "\n",
    "A package that meets *all* of these criteria is **DataFrames.jl**.\n",
    "(Many wonderful packages do not come close to this same standard; absence of these signs does not prove that a package is not useful.)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7c36feaa",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "Stars (upper right): ![stars](figures/dataframes_stars.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "08918531",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "Contributors (lower right): ![contributors](figures/dataframes_contributors.png)\n",
    "\n",
    "\n",
    "and \"Issues\" (bug reports etc.):"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9e56fbbc",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "![issues](figures/dataframes_issues.png)\n",
    "\n",
    "Major positives: rapid replies to users, many issues have a corresponding pull request. This is \"platinum-level\" maintenance; commercial software should be so good!"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "430ae502",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# Version control\n",
    "\n",
    "*Manual* \"version control\": email documents like `myfile_v1.docx`, `myfile_v2.docx`, etc. to your collaborators"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4a551c57",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "Problems:\n",
    "- they cannot easily see each other's comments or changes as they work through the document\n",
    "- you have to manually merge the changes from multiple modifications (`myfile_v1_PersonA_edits.docx`, `myfile_v1_PersonB_edits.docx`, etc.)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f54d09d1",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "*Centralized* version control: Google Docs & similar services"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e5c34a40",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "Pros:\n",
    "- everyone sees the document in real-time\n",
    "- the changes tend to be the union of all changes, preserving a single master document"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5d79a010",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "Cons:\n",
    "- you can't work if you're not connected to the internet (or if you do, you break the model, and changes may need manual merging)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "facc992e",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "*Distributed* version control: `git`"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "086210b4",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "Features:\n",
    "- there is no single \"master document\" (\"official version\" is a *social* construct, not a technical one)\n",
    "- different copies do not automatically sync, but you can trigger syncing yourself\n",
    "- merge disparate changes based on shared history"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "bd0b7b70",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "A reasonably-good mental model: biological evolution\n",
    "- there is no \"master copy\" of a species, only individuals\n",
    "- \"syncing\" = \"mating\": the combination of mutations from two parent organisms\n",
    "- there can be no syncing without shared history (you need a foundation of sequence homology)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "eb0d39c7",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "The model is imperfect:\n",
    "- in software there is a social drive to (eventually) unify into \"a single thing\"\n",
    "- unlike reproduction, changes are merged *exhaustively*, not randomly\n",
    "- there is no analog of the sexes: any two \"individuals\" (*branches*) can merge if they have shared history"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "956aceb1",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# Distributed version control works well for code\n",
    "\n",
    "- *pro*: develop your feature without interference from unrelated changes occurring simultaneously all over the globe\n",
    "- *pro*: combine changes when they are ready\n",
    "- *con*: conflicts sometimes have to be merged manually"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "aaa69847",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# Why does history matter?\n",
    "\n",
    "Merges could be made purely based on comparisons between final products, the *diff*:\n",
    "\n",
    "| Version A | Version B | Differences |\n",
    "|:---- |:--- | ---:|\n",
    "| `x = 6` | `x = 6` | |\n",
    "| `y = 2` | `y = 3` | <--- |\n",
    "| `z = x + y` | `z = x + y` | |\n",
    "\n",
    "But which one do you want to keep? History endows modifications with *directionality* and allows most merges to be automatic."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d963d47d",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "<img style=\"float:center; display:inline; height:120px; width:auto;\" src=\"figures/Git-Logo-2Color.png\" />\n",
    "\n",
    "`git` has become the dominant version control system (VCS) for software."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d18fc43c",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "Install it on all machines you use (Windows, Macs, and Unix)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d9b6c0a6",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "Works with or without a *hosting service* (GitHub, GitLab, BitBucket, etc.)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "fe3f8162",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# Git concepts (1/3): branch and merge\n",
    "\n",
    "![branching and merging](figures/git-branches-merge.png)\n",
    "\n",
    "Inspired by *NobleDesktop*"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "584ef5bf",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# Git concepts (2/3): checkouts and staging\n",
    "\n",
    "![checkout](figures/git-staging.png)\n",
    "\n",
    "The code you see in your folder is a \"checkout\" from the overall `git` tree: you can switch branches mid-project.\n",
    "\n",
    "From *Pro Git book*"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a6cd5ed6",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# Git concepts (3/3): remotes\n",
    "\n",
    "![remotes](figures/remotes.png)\n",
    "\n",
    "- *push*: send code (needs read access to local, and write access to remote)\n",
    "- *pull*: receive code (needs read access to remote, write access to local)\n",
    "- *clone*: make initial copy of a remote repository"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "335d95bb",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# Hosting concepts: forks\n",
    "\n",
    "![forks](figures/hosting1.png)\n",
    "\n",
    "Inspired by *Thomas Beuzen*"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1c2f44fc",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "![forks](figures/hosting2.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3aa160a9",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# Advanced topics\n",
    "\n",
    "`git` is history based. It is possible to rewrite history:\n",
    "\n",
    "- `git commit --amend`\n",
    "- `git rebase`\n",
    "\n",
    "**Warning**: don't do this on `main` if anyone besides yourself is using the repository: you will generate incompatible histories.\n",
    "\n",
    "You can do it to \"clean up a branch,\" but this is a bit advanced and we won't cover it here. (You can read about it.)\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "275f2ed7",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# Summary\n",
    "\n",
    "- `git` and hosting services like GitHub enable worldwide collaboration\n",
    "- the hosting services are social media platforms: be respectful and earn the respect of others\n",
    "- `git` is based on a few core concepts:\n",
    "  + changes get *staged* and *committed*\n",
    "  + branches get `push`ed, `pull`ed, and `merge`d\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "45359778",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "On the homework:\n",
    "- complete a set of \"bot\" exercises on the basics of GitHub\n",
    "- use VS Code on your local machine to create a repository, make changes, and push up to GitHub"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "98ff30be",
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "celltoolbar": "Slideshow",
  "kernelspec": {
   "display_name": "Julia 1.8.0",
   "language": "julia",
   "name": "julia-1.8"
  },
  "language_info": {
   "file_extension": ".jl",
   "mimetype": "application/julia",
   "name": "julia",
   "version": "1.8.0"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}