Practical-01-Getting_Started.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div style=\"float:left\">\n",
    "            <h1 style=\"width:450px\">Practical 1: Getting Started</h1>\n",
    "            <h2 style=\"width:450px\">Getting to grips with Jupyter, Git and Markdown</h2>\n",
    "</div>\n",
    "<div style=\"float:right\"><img width=\"100\" src=\"https://jreades.github.io/fsds/img/casa_logo.jpg\" /></div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This week’s practical is focussed on getting you set up with the tools and accounts that you’ll need to across many of the CASA modules in Terms 1 and 2, and familiarising you with ‘how people do data science’. Outside of academia, it’s rare to find a data scientist who works entirely on their own: most code is collaborative, as is most analysis! But collaborating effectively requires tools that: get out of the way of doing ‘stuff’; support teams in negotating conflicts in code; make it easy to share results; and make it easy to ensure that everyone is ‘on the same page’."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Task 0: Installing the Base Utilities\n",
    "\n",
    "If you haven't done this already, we need to install some basic tools that will allow us to interact with Git and other applications from the Terminal/Command Line. You need to do install _either_ the Xcode Command Line Tools (Mac) or WSL (Windows). \n",
    "\n",
    "Instructions for these can found on the [CASA Computing Environment](https://jreades.github.io/sds_env/req/base.html) web page. This process will take time, so please come prepared with questions or other things to do while you wait!\n",
    "\n",
    "<div class=\"alert alert-block alert-info\">\n",
    "<b>&#9888; Tip:</b> if you need help understanding how to use the Command Line or want to be able to do <i>much more</i> there are a wide range of tutorials out there (see below).\n",
    "</div>\n",
    "\n",
    "Here are some starting points for learning more:\n",
    "    \n",
    "- **I need help understanding**: [Software Carpentries](https://software-carpentry.org/lessons/index.html) is your friend! They have an entire tutorial titled [The Unix Shell](https://swcarpentry.github.io/shell-novice/).\n",
    "- **I *still* need help understanding**: the [Programming Historian](https://programminghistorian.org/) is another good place to look! And they _also_ have an entire tutorial titled [An Introduction to Bash](https://programminghistorian.org/en/lessons/intro-to-bash).\n",
    "- **I want to do *more* on the Command Line**: O'Reilly has produced an online book called [Data Science at the Command Line](https://datascienceatthecommandline.com/2e/chapter-2-getting-started.html) that will take you much, much further."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Task 1: Organising Your Workspace\n",
    "\n",
    "Before we start trying to code, I'd suggest organising a 'workspace' on your computer so that it's easy to find/load data and 'Jupyter notebooks' (the tool we'll be using to write and rung code). The easiest way to do this is to start from your `Documents` folder and set directories there to hold your code and data. Why? Because leaving everything in the Downloads folder or in random locations all over you computer is likely to be a disaster, especially when you're under time pressure.\n",
    "\n",
    "Here's _one_ way of organising things, and I'm also taking the opportunity to show you how to do this using the Command Line:\n",
    "\n",
    "- On a Mac you want the `Terminal` (under Applications > Utilities) or;\n",
    "- On a Window machine you want `bash` (which was installed with WSL2; see [Task 0](#Task-0:-Installing-the-Base-Utilities)). Windows10 users might find [this explanation](https://www.laptopmag.com/articles/use-bash-shell-windows-10) useful.\n",
    "\n",
    "This code will create a directory called `CASA` in your Documents folder (or `My\\ Documents` on some Windows machines):\n",
    "```bash\n",
    "cd $HOME     # This will normally take you to your 'home' directory (on a Mac this is /Users/<your username>)\n",
    "ls           # This will *list* the files in the current directory ($HOME)\n",
    "cd Documents # You're now *c*hanging *d*irectory to the Documents folder (e.g. /Users/<your username>/Documents)\n",
    "mkdir CASA   # *make* a *dir*ectory called `CASA`\n",
    "```\n",
    "\n",
    "<div class=\"alert alert-block alert-warning\">\n",
    "<b>&#9888; Tip:</b> On some Windows machines you might not have a <tt>Documents</tt> folder and will need to decide whether to create one or use the Windows-equivalent (probably <tt>My\\ Documents</tt> -- notice the <tt>\\</tt>!).\n",
    "</div>\n",
    "\n",
    "<div class=\"alert alert-block alert-info\">\n",
    "<b>&#9888; Tip:</b> There are any number of ways to organise your CASA work, what's important is that you are <i>logical</i> about things like names and hierarchy. This will make it much easier to access files and notebooks using Docker, Quarto, <i>and</i> Python.\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Task 2: Getting Set Up with Docker\n",
    "\n",
    "You may be tempted to leave this for later, but we'd _strongly_ encourage you to try installing the programming environment as soon as possible so that we have as long as possible to help you over any hurdles before we get to week 3 where it will be essential that you are running the environment successfully. In our experience, the students who put off trying to get the environment running end up falling quickly behind as they are unable to complete basic tasks successfully. \n",
    "\n",
    "The _majority_ of you will be able to use [Docker](https://www.docker.com), but there will be _some_ Windows 10 users whose computers will refuse to run this platform, in which case will you need to run [Anaconda Python](https://anaconda.org/) directly (see Task 8)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 2.1 Installing Docker \n",
    "\n",
    "You will need to [download](https://docs.docker.com/get-docker/) a version of Docker appropriate for your Operating System and then follow the installation instructions.\n",
    "\n",
    "### 2.2 Configuring Docker\n",
    "\n",
    "You should then be able to follow along with [the instructions](https://jreades.github.io/sds_env/setup/env.html) that we provided on the [CASA Computing Environment](https://jreades.github.io/sds_env/) web site.\n",
    "\n",
    "### 2.3 Running Docker\n",
    "\n",
    "There are three ways of running Docker:\n",
    "\n",
    "1. Directly on the Command Line as shown in the [relevant examples](https://jreades.github.io/sds_env/setup/env.html#docker). This is the _best_ way to learn how to start/stop Docker.\n",
    "2. Using a bash script and configuration file as [detailed here](https://jreades.github.io/sds_env/docker/#running-everything-script). This is the _easiest_ way to start/stop Docker.\n",
    "3. Using VSCode as [detailed here](https://jreades.github.io/sds_env/docker/#enabling-vscode-integration) or by [downloading the devcontainer folder and its contents](https://github.com/jreades/sds_env/tree/master/test-vscode-project) to create a new VSCode project that is bound to the Docker image. This will give you a very different experience of using Docker and Jupyter, but is appropriate for _those who want to use an IDE to write code_.\n",
    "\n",
    "<div class=\"alert alert-block alert-warning\">\n",
    "<b>&#9888; Warning:</b> once you have started a Docker container using any of the above, the machine <b>will continue running</b> until you either restart the computer or tell Docker to stop the container. This <i>can</i> consume memory and battery power indefinitely.\n",
    "</div>\n",
    "\n",
    "### 2.4 How do I Know it Worked?\n",
    "\n",
    "With Docker running, you will _mainly_ interact with Python through a web page (unless you choose the VSCode IDEA). To check if it's running, we just have to visit the web page and see what happens.\n",
    "\n",
    "It is likely that the page you want is: [http://localhost:8888/lab/tree/work/](http://localhost:8888/lab/tree/work/). We'll talk more about exactly what is going on next week as well, but this should show you a page that looks something like this (probably with fewer files listed on the left-hand side):\n",
    "\n",
    "![Screenshot of Jupyter Lab](https://github.com/jreades/fsds/raw/master/practicals/img/1.8-Jupyter_Lab.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Task 3: Setting Up GitHub\n",
    "\n",
    "Understanding how to use Git and GitHub effectively is a core element of learning to code. So one of the _first_ things that we are going to do is set you up with an account and a new project.\n",
    "\n",
    "So in order to complete this task you need to:\n",
    "1. Create a login with [GitHub](https://github.com). \n",
    "2. Create a new **private** project on GitHub. \n",
    "3. Edit the `README.md` and `.gitignore` files for your new project.\n",
    "4. Save the changes (this is called a 'commit') and say in a general way what edits you did.\n",
    "5. Work out how to compare the original and edited versions of any file in your browser.\n",
    "\n",
    "### 3.1 Your New GitHub Account\n",
    "\n",
    "You may wish to set up your new GitHub account with your UCL email. GitHub 'knows' about educational users and will give you access to more features for free if you use a `.ac.uk` email address. Once you've done this, you can then link a personal email address as well.\n",
    "\n",
    "From a security standpoint you should _also_ enable 2-factor authentication so that you receive a text message when you log in on a new machine and are asked to confirm a code.\n",
    "\n",
    "### 3.2 Creating a Private Repository\n",
    "\n",
    "To create a repository, click on the `+` at the upper-right corner of the GitHub web page and select `New Repository`. You might as well call your 'repo' `fsds` or `foundations` since that's a lot shorter than `foundations_of_spatial_data_science`. \n",
    "\n",
    "<div class=\"alert alert-block alert-warning\">\n",
    "    <b>&#9888; Note:</b> for the purposes of this tutorial (and all subsequent tutorials) I will assume that your repository is called <tt>fsds</tt>. You can call it whatever you like, in which case you will <em>always</em> need to substitute the name that <em>you</em> chose wherever you see me write <tt>fsds</tt>.\n",
    "</div>\n",
    "\n",
    "It's always helpful to provide some basic information about what's in the project (_e.g._ your notes and practicals for the _Foundations_ module). And finally, make sure you:\n",
    "\n",
    "1. Change the visibility from `Public` to `Private`,\n",
    "2. Tick `Add a README file`, \n",
    "3. Change `Add .gitignore` from `None` to `template: Python`.\n",
    "\n",
    "Click `Create Repository` and you should end up on a page that looks like this:\n",
    "\n",
    "![Repository created](https://github.com/jreades/fsds/raw/master/practicals/img/1.1-Repo_Created.png)\n",
    "\n",
    "Your new repository has been created (on GitHub)!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "tags": []
   },
   "source": [
    "## Task 4: Getting Comfortable with Markdown\n",
    "\n",
    "To get some practice with Markdown let's write up some notes direclty into our GitHub repository (aka 'repo'). You'll notice that we've not yet hit the *BIG GREEN BUTTON* marked `Add a README`... Let's do that now!\n",
    "\n",
    "This will take you to an editing page for the new `README.md` file. You can type directly into this web page and it will update the repository, but _only_ once you `commit` your edits.\n",
    "\n",
    "### 4.1 Working on Your Markdown\n",
    "\n",
    "Write your README file using _at least_ the following Markdown features:\n",
    "\n",
    "- A level-1 header (`#`)\n",
    "- A level-3 header (`###`)\n",
    "- Italic text (`_this is italicised_`)\n",
    "- Bold text (`**this is bold**`)\n",
    "- A link (`[link text](url)`)\n",
    "- An image (`![Alt text](image_location)`)\n",
    "\n",
    "If you're unsure how these work, just double-click on _this text_ and you'll see Markdown in a Jupyter notebook. Here's some sample text to get you started:\n",
    "\n",
    "```markdown\n",
    "## Foundations of Spatial Data Science\n",
    "\n",
    "This repository contains practicals and notes from the _Foundations_ module. \n",
    "\n",
    "You can find the original [here](https://jreades.github.io/fsds/).\n",
    "```\n",
    "\n",
    "**Don't forget to check out the \"Preview\" tab!**\n",
    "\n",
    "### 4.2 Commiting a Change\n",
    "\n",
    "Once you're happy with how your text looks and works, it's time to commit! Scroll down to where you see something like this (you will see your _own_ GitHub username, not mine):\n",
    "\n",
    "![GitHub Commit](https://github.com/jreades/fsds/raw/master/practicals/img/1.2-Commit.png)\n",
    "  \n",
    "You can just accept the description (_e.g._ `Create README.md`) or you can write your own. You can also provide an extended description if you choose. Then click `Commit new file` and you will see your new README appear."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Task 5: Updating the .gitignore File\n",
    "\n",
    "The `.gitignore` file tells Git what files to ignore by default. Unless you _force_ Git to add an ignored file it will happily live in your _local_ repository alongside files that are version-controlled and 'shared' with GitHub.\n",
    "\n",
    "The Python template for `.gitignore` includes a lot of useful files and folders that we wouldn't want Git to track for us. But it _doesn't_ include data. In your web browser, click on the `.gitignore` file and then the 'pencil' icon on the right to edit it on GitHub. You should see something like this:\n",
    "\n",
    "![Editing the .gitignore file](https://github.com/jreades/fsds/raw/master/practicals/img/1.4-Editing_Gitignore.png)\n",
    "\n",
    "### 5.1 Exclude Zip, Gzip, and CSV Files\n",
    "\n",
    "We want to make it hard to accidentally add a large data file to our repository because we're assuming that the data is backed up or available elsewhere, but our _code_ is not! So as a first step we want to (big hint) exclude compressed files **with the .zip and .gz extensions**.\n",
    "\n",
    "Here's another hint: `C extensions` are _already_ excluded by the `.gitignore` file, so maybe look to see how that's done to help you figure out how to exlcude `.zip`, `.gz`, and `.csv` files...\n",
    "\n",
    "### 5.2 Exclude a Data Directory\n",
    "\n",
    "To make it even _less_ like that we accidentally include data, let's also exclude a `data` directory from our repository. As a clue, nearly everything in the `Distribution / packaging` section of the `.gitignore` file is a directory to be excluded from Git.\n",
    "\n",
    "So how would you indicate that `data` is a directory? Once you're sure, add the `data` directory! \n",
    "\n",
    "When you are done, don't forget to add a 'commit message' (e.g. 'Added data files to .gitignore') at the bottom and then click `Commit changes`.\n",
    "\n",
    "<div class=\"alert alert-block alert-info\">\n",
    "    <b>&#9888; Answers</b>: I don't want you to get hung up on this <i>one</i> thing in Practical 1, so if you just can't make sense of what you're being asked to do here, have a look at the <a href=\"#Answers\">Answers</a> at the bottom of this page.\n",
    "</div>\n",
    "\n",
    "### 5.3 Check Your Changes\n",
    "\n",
    "Once you have committed your changes, you should be back to the default view of the `.gitignore` file but there should be a message to the effect of `Latest commit <some hexadecimal number> 10 seconds ago` and, next to that, a `History` button.\n",
    "\n",
    "Click on 'History' and let's go back in time! \n",
    "\n",
    "![The Gitignore history](https://github.com/jreades/fsds/raw/master/practicals/img/1.5-Gitignore_History.png)\n",
    "\n",
    "On the history page you can browse every edit to your file. Whenever you `commit` a file, this like taking a snapshot at a point in time. Using the 'History' you can compare two different snapshots in order to see what has changed. This would help you to work out how you broke something, check that requested changes have been made, or see how an error might have been introduced.\n",
    "\n",
    "You can mouseover the buttons to see what they do. Why don't you try to find `See commmit details` and check what edits you made to the `.gitignore` file? Yo ushould see at least _three_ plusses in the history view representing three new lines in the `.gitignore` file.\n",
    "\n",
    "<div class=\"alert alert-block alert-info\">\n",
    "<b>&#9888; Tip:</b> You can mouseover the buttons to see what they do. Why don't you try to find `See commmit details` and check what edits you made to the <tt>.gitignore</tt> file? You should see at least <em>three</em> plusses in the history view representing three new lines in the <tt>.gitignore</tt> file.\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Task 6: Setting Up Git Locally\n",
    "\n",
    "I have [created a video](https://web.microsoftstream.com/video/29a31977-ff9e-4b53-92d3-ee3bb2a769f6) on Microsoft Streams that runs you through Tasks 6.1 and 6.2 (below). You can refer ot it if you find the written instructions hard to follow for any reason or would like a visual check that you're doing the right thing!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 6.1 Configuring Defaults\n",
    "\n",
    "The first thing to do is set up the default username and email for GitHub. These can be changed on a project-by-project basis, but to begin with it's best to set up the _global defaults_. Using either the Terminal or Bash enter the following (replacing `<...>` with _your_ details):\n",
    "```bash\n",
    "cd \n",
    "git config --global user.email '<your GitHub email address>'\n",
    "git config --global user.name '<your GibHub username>'\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 6.2 Creating a Personal Access Token\n",
    "\n",
    "You do not want to have to enter your GitHub password every time you copy changes up to/down from GitHub, and you _don't_ want to paste your password in plain text into your code! The Personal Access Token is a way to manage this by issuing special passwords that allow only limited access to your account.\n",
    "\n",
    "To create a Personal Access Token:\n",
    "\n",
    "- Visit your GitHub User Page ([e.g. github.com/jreades](https://github.com/jreades))\n",
    "- Click on your user icon (at the top-right corner of the page) and pick `Settings`\n",
    "- Scroll down the [settings page](https://github.com/settings/profile) until you get to `Developer settings`\n",
    "- Click the `Developer settings` link to reach [the 'apps' page](https://github.com/settings/apps) and then click on the `Personal access tokens` link.\n",
    "- Click the `Generate new token` button and set up the token so that it has **read/write `repo` privileges (full control of private repositories)**. You can change other settings (read/write packages, gists, and notifications) but this is not necessary.\n",
    "- Save the resulting token somewhere safe as you will need it again!\n",
    "\n",
    "<div class=\"alert alert-block alert-danger\">\n",
    "<b>&#9888; Keep your Personal Token safe:</b> you will need it at least twice in this tutorial and may want to use it again on other computers. You can always create a new one, but then you'll need to update every computer where you access your GitHub repositories.\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 6.3 Cloning Your Repository\n",
    "\n",
    "Now we are going to `clone` (i.e. copy) the repository that you just created on to your own computer. This is surprisingly straightforward provided that you have installed the command line tools.\n",
    "\n",
    "On your private repository page, click on the green button labeled `Code` visible in the screenshot below:\n",
    "\n",
    "![Screenshot of cloning interface](https://github.com/jreades/i2p/raw/master/lectures/img/Cloning.png)\n",
    "\n",
    "You should then copy the URL (visible in my screenshot as `https://github.com/jreades/i2p.git`). Switching to the command line, *c*hange *d*irectory (`cd`) to the location where you want your repository to be stored on _your_ machine. For instance, if I wanted to keep all of my _Foundations_ code in the CASA directory then I would do this:\n",
    "\n",
    "```bash\n",
    "cd $HOME/Documents/CASA/\n",
    "git clone <the_url_that_you_copied_from_the_browser>\n",
    "```\n",
    "The first time that you do this, you will likely need to provide login information. Use your GitHub username and the Personal Access Token that you just created."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "tags": []
   },
   "source": [
    "### 6.4 Storing Credentials & 'Pulling'\n",
    "\n",
    "You can now activate the credtial helper that will store your Personal Access Token:\n",
    "```bash\n",
    "cd fsds\n",
    "git config credential.helper store\n",
    "git pull\n",
    "```\n",
    "\n",
    "When you type `git pull` you _should_ be asked _again_ for your username and password. You should (again) use the Personal Access Token as your password. You should not be asked again for pushing or pulling data into this GitHub repository. If you are _not_ asked for your Personal Access Token then this likely means that your token is already saved and ready to use on all future 'actions'."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 6.5 Adding a Local File to Your Repository\n",
    "\n",
    "In order to tie together the different concepts covered above, we are now going add Practical 1 (_this_ practical) to _your_ GitHub repo. The easiest way to do this is to open the practicals as `Raw text` in your browser: so navigate to the [Practical 1](https://github.com/jreades/fsds/blob/master/practicals/Practical-01-Getting_Started.ipynb) page on GitHub and then click `Raw` to see something like this:\n",
    "\n",
    "![Raw view of a Jupyter Notebook](https://github.com/jreades/fsds/raw/master/practicals/img/1.6-Raw_Ipynb.png)\n",
    "\n",
    "So, starting with the 'raw' notebook:\n",
    "\n",
    "1. Save this file to your computer as a notebook with the extension `.ipynb`. \n",
    "2. Move the file to your repostiory folder (_e.g._ `$HOME/Documents/CASA/fsds/`).\n",
    "3. You will _probably_ need to remove a `.txt` extension that was added automatically by your browser (_i.e._ it will have been saved in your Downloads directory as `<notebook_name>.ipynb.txt`. After moving the notebook file into the repository directory this can be easily done on the Command Line: `cd $HOME/Documents/CASA/fsds; mv <notebook_name>.ipynb.txt <notebook_name.ipynb` (`mv` is short for *m*o*v*e).\n",
    "\n",
    "In the Terminal/Bash we now need `add` this file to Git so that it knows to keep track of it. Unlike Dropbox or OneDrive, just putting a file in a repo directory does _not_ mean that Git will pay attention to it:\n",
    "\n",
    "```bash\n",
    "cd fsds\n",
    "git add Practical-01-Getting_Started.ipynb\n",
    "git commit -m \"Adding notebook 1 to repo.\"\n",
    "```\n",
    "\n",
    "<div class=\"alert alert-block alert-danger\">\n",
    "    <b>&#9888; Remember:</b> Unless you have <em>added</em> and <em>committed</em> a file to Git then it is <em>not</em> version controlled.\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Task 6.6 Status Check\n",
    "\n",
    "We now want to check that the file has been successfully added to Git. We do this with a `status` check in the repository directory (_i.e._ `cd $HOME/Documents/CASA/fsds/`):\n",
    "\n",
    "```bash\n",
    "git status\n",
    "```\n",
    "\n",
    "You should see something like:\n",
    "```bash\n",
    "On branch master\n",
    "Your branch is ahead of 'origin/master' by 1 commit.\n",
    "  (use \"git push\" to publish your local commits)\n",
    "```\n",
    "\n",
    "This is telling you that your local computer is 1 commit (the one that you _just_ completed) ahead of the 'origin', which is on GitHub. GitHub doesn't _have_ to be the origin (nor does the repository have to be one that we created in order to be an origin) but _conceptually_ and _practically_ it's easier to create new repositories on GitHub and clone them to our computer."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Task 6.7 Keep Pushing\n",
    "\n",
    "To synchronise the changes we just made, let's follow Git's advice:\n",
    "\n",
    "```bash\n",
    "git push\n",
    "```\n",
    "\n",
    "You should see _something_ like (the numbers and details will _all_ differ, but the messages will be the same):\n",
    "\n",
    "```bash\n",
    "Enumerating objects: 5, done.\n",
    "Counting objects: 100% (5/5), done.\n",
    "Delta compression using up to 8 threads\n",
    "Compressing objects: 100% (3/3), done.\n",
    "Writing objects: 100% (3/3), 306 bytes | 306.00 KiB/s, done.\n",
    "Total 3 (delta 2), reused 0 (delta 0), pack-reused 0\n",
    "remote: Resolving deltas: 100% (2/2), completed with 2 local objects.\n",
    "remote: This repository moved. Please use the new location:\n",
    "remote:   https://github.com/jreades/fsds.git\n",
    "To https://github.com/jreades/i2p.git\n",
    "   7410d0e..45aa80a  master -> master\n",
    "```\n",
    "\n",
    "If you now go over to your browser and visit your GitHub repo page (_e.g._ `https://github.com/jreades/fsds`) --- pressing the `Reload` button if you had the page open already --- then you should see that the file you added _on your computer_ is also showing up on the GitHub site as well! This means it's now fully version-controlled and backed-up.\n",
    "\n",
    "<div class=\"alert alert-block alert-danger\">\n",
    "    <b>&#9888; Remember:</b> Unless have <em>pushed</em> your commits to GitHub they are <em>only</em> stored on <em>your</em> computer. So your files can be properly version-controlled, but without a <em>push</em> if you lose your computer you <em>still</em> lose everything!\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## More About Git\n",
    "\n",
    "From here on out you can keep changes made either directly on GitHub or locally on your computer (or any _other_ computer to which you `clone` your repository) in synch by using `git push` (to _push_ changes from a local computer _up_ to the origin on GitHub) and `git pull` (to _pull_ changes available on the origin _down_ to the local computer).\n",
    "\n",
    "That said, you can do a _lot_ more than just push/pull to your own repository and [this Twitter thread](https://twitter.com/ChrisStaud/status/1574277175527735296) leads to a lot of useful additional resources to do with Git:\n",
    "\n",
    "- [Introduction to Version Control with Git](https://programminghistorian.org/en/lessons/retired/getting-started-with-github-desktop) on the Programming Historian web site is written for digital humanities researchers so it's intended to be accessible.\n",
    "- [Oh My Git](https://ohmygit.org/) is an 'open source game' to help you learn Git.\n",
    "- [Git Meets Minesweeper?](https://profy.dev/project/github-minesweeper) is apparently a 'thing'.\n",
    "- [Visual Git Reference](http://marklodato.github.io/visual-git-guide/index-en.html) if you think visually or just want to check your understanding.\n",
    "- [Version Control with Git](https://swcarpentry.github.io/git-novice/) is a Software Carpentries lesson that takes you quickly through the important elements of getting set up and started. It would be a good refresher.\n",
    "- [Altassian's Documentation](https://www.atlassian.com/git/tutorials) provides more detailed explanations of the commands and options.\n",
    "- [Learn Git Branching](https://learngitbranching.js.org) focusses on a key concept for software _collaboration_.\n",
    "- [Git Immersion](https://gitimmersion.com) provides a 'guided tour' of the fundamentals.\n",
    "\n",
    "<div class=\"alert alert-block alert-success\">\n",
    "    <b>&#9888; Tip</b>: For the <a href=\"https://jreades.github.io/fsds/assessments/group.html\">Data+Policy Briefing</a> every member of your group will need to make contributions to a GitHub repository. This will require learning how to invite others to be contributors, how to merge changes, and how to deal with conflicts of the coding kind.\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Task 7: Installing Quarto\n",
    "\n",
    "Although we have also installed Quarto in the Docker image (see [Task 7](#Task-7:-Getting-Set-Up-with-Docker)), it is easier to use Quarto with fonts if you are running it directly on your computer, so that's what we're going to do now:\n",
    "\n",
    "1. [Download Quarto](https://quarto.org/docs/get-started/) and install it.\n",
    "2. [Download the Article Summary Template](https://github.com/jreades/sds_env/blob/master/skills/Article_Summary.qmd) and then click on the `Raw` button to access the Markdown. Save it somewhere accessible and rename it if you like (e.g. `$HOME/Documents/CASA/fsds/articles/Template.qmd`)\n",
    "\n",
    "At this point you _should_ be able to turn the template file into a PDF as follows:\n",
    "\n",
    "```bash\n",
    "cd $HOME/Documents/CASA/fsds/\n",
    "quarto render articles/Template.qmd \n",
    "```\n",
    "\n",
    "You should then see a number of messages appear and, eventually, \n",
    "```bash\n",
    "Output created: Template.pdf\n",
    "```\n",
    "\n",
    "Open this PDF file and you _should_ see the Markdown content from `Template.qmd` converted into a well-formatted, if not particularly attractive, [PDF like this](https://jreades.github.io/sds_env/skills/Article_Summary.pdf). We'll see in later sesesions how to specify fonts and do a good deal more. But this is enough to show that you have quarto installed and running successfully! \n",
    "\n",
    "<div class=\"alert alert-block alert-info\">\n",
    "    <b>&#9888; Notice:</b> we are steadily adding files and directories to the <tt>fsds</tt> folder that we originally created. We have an <tt>articles</tt> folder now (though we have <i>not</i> yet added it to Git. And we have the practical... as time goes on more and more files and folders will live your Git directory!\n",
    "</div>\n",
    "\n",
    "To add the articles and template QMD file to Git it's the same process as it was for the practical:\n",
    "\n",
    "```bash\n",
    "git add articles # Will automatically add files under articles/\n",
    "git commit -m \"Adding article template\"\n",
    "git push\n",
    "```\n",
    "\n",
    "If you visit the GitHub web page for your FSDS repository you should now see this folder and file there as well!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Task 8: If Docker Doesn't Work\n",
    "\n",
    "<div class=\"alert alert-block alert-danger\">\n",
    "    <b>&#9888; Stop:</b> you <em>only</em> need to follow this last task if you are unable to run Docker on your computer. This is most likely to happen if you are using Windows 10 and are unable to <i>enable BIOS support</i> for virtualisation.\n",
    "</div>\n",
    "\n",
    "You can **follow along** in a [text version of the installation guide on GitHub](https://github.com/jreades/sds_env/tree/master/conda). This will help you to get a _close equivalent_ of the Docker container's content installed directly on your own machine; however, please bear in mind that you may encounter issues from time to time due to library version differences (basically: some code will need editing to run successfully).\n",
    "\n",
    "To run Anaconda Python you will want to launch the new `Anaconda Prompt` (which should now appear as a new 'app' in your Windows menu) and type the following:\n",
    "\n",
    "```bash\n",
    "cd $HOME/Downloads/CASA\n",
    "conda activate sds2022\n",
    "jupyter lab\n",
    "```\n",
    "\n",
    "That's 'it'! You're done. We've had to put a lot of pieces of software in place for the term, but you'll find these useful across multiple modules that are part of your MSc/MRes and you're now set up for the future!\n",
    "\n",
    "<div class=\"alert alert-block alert-info\">\n",
    "<b>&#9888; Tip:</b> if you use Anaconda Prompt/Terminal then you need to restart Jupyter Lab (which Docker does automatically) every time you close the Command line window.\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Other Useful Resources\n",
    "\n",
    "- [GitHub Markdown Guide](https://guides.github.com/features/mastering-markdown/)\n",
    "- [Common Mark](https://commonmark.org/help/)\n",
    "- [Markdown Guide](https://www.markdownguide.org/basic-syntax/), which helpfully includes do's and don'ts.\n",
    "\n",
    "Finally, these are a bit overkill but the bits about setting up and installing `git`, `bash`/`zsh`, and so on may come in handy later:\n",
    "- [Setting Up a New Mac](https://www.taniarascia.com/setting-up-a-brand-new-mac-for-development/)\n",
    "- [Beginner's Guide to Setting Up Windows 10](https://medium.com/@mfosullivan/a-beginners-guide-to-setting-up-a-modern-web-development-environment-on-windows-10-4d75cd94cde8)\n",
    "- [Setting up Windows without Linux](https://dev.to/jozsefsallai/how-i-ve-set-up-my-windows-machine-as-a-development-environment-without-wsl-2kcl)\n",
    "- [Microsoft Python Setup Guide](https://docs.microsoft.com/en-us/windows/python/beginners)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Answers\n",
    "\n",
    "Normally, I will provide 'answers' later in the week, but for _this_ week it makes sense to provide them right away if you need them...\n",
    "\n",
    "## .Gitignore\n",
    "\n",
    "The main thing you should notice is the pattern: `*` means 'anything', while `/` at the end of a line implies a directory. So the following four lines should be added to your `.gitignore` file:\n",
    "\n",
    "```yaml\n",
    "*.zip\n",
    "*.gz\n",
    "*.csv\n",
    "data/\n",
    "```\n",
    "\n",
    "That's it. \n",
    "\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.10.5"
  },
  "vscode": {
   "interpreter": {
    "hash": "33a5d9b5ec968901da68ed670e49e0e20dd00b9a06b2f25f99954d276a7eae3b"
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}