remote-version-control.ipynb

{
 "cells": [
  {
   "cell_type": "raw",
   "id": "e1007ad1-5600-43b6-b576-db8dd7fd3948",
   "metadata": {},
   "source": [
    "---\n",
    "title: \"Remote version control with Git\"\n",
    "author: \"Kyle Niemeyer\"\n",
    "date: \"8 January 2025\"\n",
    "institute: \"Oregon State University\"\n",
    "format:\n",
    "  revealjs:\n",
    "    output-file: remote-version-control-revealjs.html\n",
    "    incremental: true\n",
    "    toc: false\n",
    "  html: default\n",
    "jupyter: python3\n",
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "33d69b62-cdb0-4acc-a066-af6e21bc7208",
   "metadata": {},
   "source": [
    "# Remote version control (i.e., using GitHub) and Software Licenses\n",
    "\n",
    "## Topics for today:\n",
    "\n",
    "- Backup up code (and any files) online\n",
    "- Cloning and forking remote repositories\n",
    "- Managing files in a collaboration\n",
    "- Merging simultaneous changes\n",
    "- Downloading open source code\n",
    "\n",
    "\n",
    "## Repositories\n",
    "\n",
    "[![](./images/GitHub_Logo.png){width=25% fig-alt=\"GitHub logo\"}](https://github.com)\n",
    "[![](./images/launchpad-logo.png){width=25% fig-alt=\"Launchpad logo\"}](https://launchpad.net)\n",
    "[![](./images/sourceforge-logo.jpeg){width=25% fig-alt=\"SourceForge logo\"}](https://sourceforge.net)\n",
    "[![](./images/gitlab-logo.svg){width=25% fig-alt=\"GitLab logo\"}](https://about.gitlab.com)\n",
    "\n",
    "::: {.fragment}\n",
    "### We'll focus on GitHub.\n",
    ":::\n",
    "\n",
    "## Why GitHub?\n",
    "\n",
    "- Nice landing page---renders README automatically\n",
    "- Grabs information about LICENSE, programming language\n",
    "- Supports issue tracking and wiki\n",
    "- Network graphs, time history of commits\n",
    "- User downloads\n",
    "- Varying permissions (read, write, etc.)\n",
    "- Nice web interface to browse, view, and edit code\n",
    "\n",
    "## Workflow (with account)\n",
    "\n",
    "1. Create space for repo on GitHub account\n",
    "2. Point to that remote repo from local copy\n",
    "3. Push repository to the remote location\n",
    "4. Continue working!\n",
    "\n",
    "## Alternatively, if starting new project, you can:\n",
    "\n",
    "1. Create a new repo on account\n",
    "2. Copy (clone) empty repo to local computer\n",
    "3. Prosper!\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4110e89e-08bd-4fe4-a3cb-d6621ffe5428",
   "metadata": {},
   "source": [
    "# Creating and working with repositories\n",
    "\n",
    "## Let's work through creating a repo\n",
    "\n",
    "![](./images/github-create-new-repo.png){width=90% fig-alt=\"GitHub screenshot\"}\n",
    "\n",
    "---\n",
    "\n",
    "![](./images/new-repo-info.png){width=60% fig-alt=\"Screenshot of creating a new repo on GitHub\"}\n",
    "\n",
    "---\n",
    "\n",
    "![](./images/new-repo-info-filled.png){width=60% fig-alt=\"Screenshot of creating a new repo on GitHub with information filled\"}\n",
    "\n",
    "---\n",
    "\n",
    "![](./images/new-repo-empty.png){width=60% fig-alt=\"Screenshot of a new, empty repo on GitHub\"}\n",
    "\n",
    "## Create and push new repo\n",
    "\n",
    "![](./images/github-push-remote.png){width=90% fig-alt=\"Pushing to a remote repo on GitHub\"}\n",
    "\n",
    "## Cloning a repo\n",
    "\n",
    "![](./images/github-clone-repo.png){width=90% fig-alt=\"Cloning a repo from GitHub\"}\n",
    "\n",
    "## Terminology\n",
    "\n",
    "::: {.fragment}\n",
    "**Clone**: make local copy of any repository (Git)\n",
    ":::\n",
    "\n",
    "::: {.fragment}\n",
    "**Fork**: Remote repository connected to/aware of the \"upstream\" repo it was cloned from (GitHub)\n",
    ":::\n",
    "\n",
    "## Forking a repo\n",
    "\n",
    "![](./images/github-fork.png){width=90% fig-alt=\"Forking a repo on GitHub\"}\n",
    "\n",
    "## Collaborative work using GitHub\n",
    "\n",
    "![](./images/github-collaborate-forks.png){width=90% fig-alt=\"Collaborating with forks on GitHub\"}\n",
    "\n",
    "---\n",
    "\n",
    "![](./images/github-clone-repo.png){width=60% fig-alt=\"Cloning a repo from GitHub\"}\n",
    "\n",
    "::: {.fragment}\n",
    "How does Fran keep local repo up to date with the original?\n",
    ":::\n",
    "\n",
    "## Do this yourself:\n",
    "\n",
    "1. Fork it: click \"Fork\" at [SoftwareDevEngResearch/analysis_code](https://github.com/SoftwareDevEngResearch/analysis_code)\n",
    "2. Clone your fork: `$ git clone https://github.com/[you]/analysis_code.git`\n",
    "3. Create alias `upstream` for the remote repo:\n",
    "\n",
    "``` {.bash .fragment}\n",
    "$ git remote add upstream \\\n",
    "https://github.com/SoftwareDevEngResearch/analysis_code.git\n",
    "$ git remote -v\n",
    "```\n",
    "\n",
    "## Fetching and merging remote content\n",
    "\n",
    "1. In your cloned local repo, fetch the upstream repo history\n",
    "2. Then merge the `upstream` main branch into your main branch\n",
    "3. Look at the changes!\n",
    "\n",
    "``` {.bash .fragment}\n",
    "$ git fetch upstream\n",
    "$ git merge upstream/main\n",
    "```\n",
    "\n",
    "## Update your fork\n",
    "\n",
    "::: {.fragment}\n",
    "After merging upstream history, push your work to `origin main`:\n",
    "\n",
    "```bash\n",
    "$ git push\n",
    "```\n",
    ":::\n",
    "\n",
    "::: {.fragment}\n",
    "What if you (or someone else) made a change in your fork?\n",
    ":::\n",
    "\n",
    "``` {.bash .fragment}\n",
    "$ git pull\n",
    "```\n",
    "\n",
    "::: {.fragment}\n",
    "`pull` = `fetch` & `merge` for `origin main`\n",
    ":::\n",
    "\n",
    "## Alternatively, use GitHub\n",
    "\n",
    "![](./images/github-fetch-upstream.png){width=90% fig-alt=\"Fetch upstream on GitHub\"}\n",
    "\n",
    "## What about conflicts?\n",
    "\n",
    "::: {.fragment}\n",
    "When fetching, merging, and/or pulling remote changes, you may encounter conflicts.\n",
    ":::\n",
    "\n",
    "::: {.fragment}\n",
    "To solve: just follow the directions!\n",
    ":::\n",
    "\n",
    "::: {.fragment}\n",
    "(In-class example)\n",
    ":::\n",
    "\n",
    "## Best practices for collaborating\n",
    "\n",
    "::: {.fragment}\n",
    "For solo projects:\n",
    ":::\n",
    "\n",
    "- push and pull (to/from origin\n",
    "- use branches, merge into main\n",
    "\n",
    "\n",
    "::: {.fragment}\n",
    "For multi-person projects:\n",
    ":::\n",
    "\n",
    "- Fork into a personal repo\n",
    "- Use git fetch/merge to keep updated with upstream\n",
    "- Push (and pull) to/from origin (your fork on GitHub)\n",
    "- Contribute changes via pull requests on GitHub\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9ca36ad3-f8af-4c5a-a879-3fcfdac35a1c",
   "metadata": {},
   "source": [
    "# (Some) issues that arise when using GitHub: Pull requests & licences\n",
    "\n",
    "## Pull Requests\n",
    "\n",
    "::: {.fragment}\n",
    "Modern, GitHub-based version of emailing someone a **patch**\n",
    "::: \n",
    "\n",
    "::: {.fragment}\n",
    "Pull Requests (or PRs) consist of sequences of patches, based on a history of Git commits\n",
    "::: \n",
    "\n",
    "## Example Pull Request on GitHub\n",
    "\n",
    "![](./images/github-pull-request-example.png){width=90% fig-alt=\"Pull request example on GitHub\"}\n",
    "\n",
    "## How to contribute a change to someone else's repository\n",
    "\n",
    "1. Fork the repo\n",
    "2. Clone your fork locally\n",
    "3. Create a new branch for your changes/fix\n",
    "4. Commit and push your changes\n",
    "5. Submit a Pull Request via GitHub\n",
    "\n",
    "``` {.bash .fragment}\n",
    "$ git clone ...\n",
    "$ git checkout -b newfix\n",
    "\n",
    "$ git commit -am \"fixes problem in upstream project\"\n",
    "$ git push origin newfix\n",
    "```\n",
    "\n",
    "## Create Pull Request\n",
    "\n",
    "![](./images/github-create-pull-request.png){width=90% fig-alt=\"Create a Pull Request on GitHub\"}\n",
    "\n",
    "## Submitting Pull Requests\n",
    "\n",
    "::: {.fragment}\n",
    "Try to submit shorter Pull Requests when possible, as they are easier to review and merge\n",
    ":::\n",
    "\n",
    "::: {.fragment}\n",
    "If the project uses testing, make sure to add a new test (or modify an existing one) to reflect your change. More on tests later!\n",
    ":::"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f84a2975-bceb-45b2-9f85-1bacd1ff7946",
   "metadata": {},
   "source": [
    "# Software Licenses & Copyright\n",
    "\n",
    "## Important notice\n",
    "\n",
    "### I AM NOT A LAWYER!\n",
    "\n",
    "### AKA: IANAL\n",
    "\n",
    "## Copyright\n",
    "\n",
    "::: {.fragment}\n",
    "Facts and ideas are **not copyrightable**.\n",
    ":::\n",
    "\n",
    "::: {.fragment}\n",
    "*Expressions* of ideas are copyrightable.\n",
    ":::\n",
    "\n",
    "## Copyright Examples\n",
    "\n",
    "::: {.fragment}\n",
    "Game rules are not copyrightable (chess, Go, football, *Dungeons & Dragons*)\n",
    "::: \n",
    "\n",
    "::: {.fragment}\n",
    "Expressions of game rules *are* copyrightable.\n",
    ":::\n",
    "\n",
    "::: {.fragment}\n",
    "![](./images/dnd-handbook.jpg){height=\"300\" fig-alt=\"Dungeons & Dragons Player's Handbook\"}\n",
    ":::\n",
    "\n",
    "## Basic Copyright\n",
    "\n",
    "::: {.fragment}\n",
    "\"Right of First Publication\": copyright automatically goes to the first creator of any creative work\n",
    ":::\n",
    "\n",
    "::: {.fragment}\n",
    "(Even if not explicitly specified)\n",
    ":::\n",
    "\n",
    "::: {.fragment}\n",
    "Consequence: if you post software to GitHub without an explicit license, then you own the copyright—even if openly and publicly visible.\n",
    ":::\n",
    "\n",
    "::: {.fragment}\n",
    "By default, no one else is legally allowed to use or modify your work.\n",
    ":::\n",
    "\n",
    "## Software Licenses\n",
    "\n",
    "**All** software codes you make publicly available should be accompanied by a software license describing the terms by which others may use and/or modify your code.\n",
    "\n",
    "## Public Domain\n",
    "\n",
    "::: {.fragment}\n",
    "Alternatively, you can put work into the <em>public domain</em>: \"This work has been placed in the public domain.\"\n",
    ":::\n",
    "\n",
    "::: {.fragment}\n",
    "Free for anyone and everyone to use and modify.\n",
    ":::\n",
    "\n",
    "::: {.fragment}\n",
    "Literature examples: *Sherlock Holmes*, *Frankenstein*\n",
    ":::\n",
    "\n",
    "::: {.fragment}\n",
    "(There are some tricky issues internationally, however.)\n",
    ":::\n",
    "\n",
    "## Software Licenses\n",
    "\n",
    "::: {.fragment}\n",
    "Kinds of software licenses: proprietary, and free/open source (FOSS, FLOSS, OSS).\n",
    ":::\n",
    "\n",
    "::: {.fragment}\n",
    "**Pick an existing license. Do not create your own.**\n",
    ":::\n",
    "\n",
    "## Software Licenses\n",
    "\n",
    "::: {.fragment}\n",
    "FOSS categories: permissive, and \"copyleft\"\n",
    ":::\n",
    "\n",
    "::: {.fragment}\n",
    "**Permissive** licenses: BSD 3-clause, MIT; allow further distribution under any license\n",
    ":::\n",
    "\n",
    "::: {.fragment}\n",
    "**Copyleft** licenses: GPL; require modifications to be shared under the same license (\"viral\")\n",
    ":::\n",
    "\n",
    "## <https://choosealicense.com>\n",
    "\n",
    "[![](./images/choosealicense.com.png){fig-alt=\"ChooseALicense.com}](https://choosealicense.com)\n",
    "\n",
    "## Open Source Initiative licenses\n",
    "\n",
    "[![](./images/open-source-initiative-licenses.png){width=75% fig-alt=\"Open Source Initiative Licenses & Standards\"}](https://opensource.org/licenses)\n",
    "\n",
    "## Which license to use?\n",
    "\n",
    "::: {.fragment}\n",
    "When in doubt, use a permissive license like the BSD 3-clause or MIT licenses.\n",
    ":::\n",
    "\n",
    "## Copyrighting other creative works: Creative Commons\n",
    "\n",
    "- BY: Attribution\n",
    "- SA: ShareAlike\n",
    "- ND: NoDerivatives\n",
    "- NC: NonCommercial\n",
    "\n",
    "::: {.fragment}\n",
    "Licenses: CC BY, CC BY-SA, CC BY-NC, CC BY-NC-NC\n",
    ":::\n",
    "\n",
    "::: {.fragment}\n",
    "[Choose a license](https://creativecommons.org/share-your-work/)\n",
    ":::\n",
    "\n",
    "## Beyond copyright & licenses\n",
    "\n",
    "::: {.fragment}\n",
    "**Patents**: cover ideas and concepts; modern issues with \"patent trolls\"\n",
    "::: \n",
    "\n",
    "::: {.fragment}\n",
    "**Trademarks**: symbols that represent a business or organization\n",
    ":::\n",
    "\n",
    "::: {.fragment}\n",
    "**Export control**: government may forbid the transfer of source code (and data, ideas) to another country or foreign national without permission\n",
    ":::\n",
    "\n",
    "::: {.fragment}\n",
    "**HIPAA compliance**: software that deals with human patients must be anonymized\n",
    ":::"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "393a4219-ca45-4710-8513-cb99d7386537",
   "metadata": {},
   "source": [
    "# Long story short:\n",
    "\n",
    "::: {.fragment}\n",
    "Pick a license when creating a project, and put as `LICENSE.txt` in your repo.\n",
    ":::"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "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.13.1"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}