02_workspace.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# Foundations of Computational Economics\n",
    "\n",
    "by Fedor Iskhakov, ANU\n",
    "\n",
    "<img src=\"_static/img/dag3logo.png\" style=\"width:256px;\">"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "## Local workspace. Jupyter notebooks. Git and GitHub\n",
    "\n",
    "<img src=\"_static/img/lab.png\" style=\"width:64px;\">"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "<img src=\"_static/img/youtube.png\" style=\"width:65px;\">\n",
    "\n",
    "[https://youtu.be/UrZnRv3_IUc](https://youtu.be/UrZnRv3_IUc)\n",
    "\n",
    "Description: Introduction of Git version control system. Local installation of Python, Anaconda, Jupyter Notebooks, Git and Git GUI. GitHub and GitHub Classroom."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Prerequisites\n",
    "\n",
    "- You have a fairly modern computer: desktop or laptop, Windows or Mac or Linux  \n",
    "- You have administrative access to this computer (can install programs)  \n",
    "\n",
    "\n",
    "1. Find the **Terminal** program in your system  \n",
    "\n",
    "\n",
    "> - Mac: Applications >> Utilities >> Terminal  \n",
    "- Win: Run command.. >> cmd or powershell  \n",
    "- Unix: should be obvious  "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Main steps to set up your local workspace\n",
    "\n",
    "1. Install Python environment manager Anaconda  \n",
    "1. Install Git and Git GUI  \n",
    "1. Register at GitHub  \n",
    "1. Install good text editor  \n",
    "\n",
    "\n",
    "[QuantEcon page on setting up local environment](https://python-programming.quantecon.org/getting_started.html)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "#### 1. Anaconda\n",
    "\n",
    "- Python  \n",
    "- Jupyter Notebook  \n",
    "- Scientific programming libraries  \n",
    "\n",
    "\n",
    "Install: [Anaconda Individual Edition](https://www.anaconda.com/products/individual) (free)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "#### 2. Git and Git GUI\n",
    "\n",
    "- Git is the *command line* version control software  \n",
    "- GUI makes Git a lot more practical  \n",
    "\n",
    "\n",
    "Install: [Git](https://git-scm.com/)\n",
    "\n",
    "Choose and install: [Git GUI application](https://git-scm.com/downloads/guis)\n",
    "\n",
    "Recommended options:\n",
    "- [SourceTree](https://www.sourcetreeapp.com/)\n",
    "- [GitHub Desktop](https://desktop.github.com/)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "#### 3. GitHub\n",
    "\n",
    "- Social coding network website\n",
    "  - Hosting code\n",
    "  - Version control + integrations\n",
    "  - Community of coders\n",
    "  - Open source community projects  \n",
    "- Register on [GitHub](https://github.com/join) (if not yet)\n",
    "  - *Be mindful about using your personal data when registering!*\n",
    "  - [Apply for Student Pack](https://help.github.com/articles/applying-for-a-student-developer-pack)  \n",
    "- Course materials will be distributed through GitHub Classroom  \n",
    "- Unless you opt out, you will submit assignments through GitHub  \n",
    "\n",
    "\n",
    "https://github.com/fediskhakov"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "#### 4. Text editor [optional]\n",
    "\n",
    "- Good text editor is very useful for editing source files  \n",
    "- Could be done in Jupyter or other default editors, but less convenient  \n",
    "- Essential for bigger coding projects  \n",
    "- Good options are:\n",
    "  - [Atom](https://atom.io/)\n",
    "  - [VS Code](https://code.visualstudio.com/)\n",
    "  - [Sublime Text](https://www.sublimetext.com/) (for pay)\n",
    "  - [PyCharm](https://www.jetbrains.com/pycharm/) (complete IDE)  "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "#### Typical single user Git workflow\n",
    "\n",
    "1. Create/Clone repository  \n",
    "1. Write/edit (text) files (**CODING HERE**)  \n",
    "1. Observe diffs  \n",
    "1. Stage and commit  \n",
    "1. Upload to server/GitHub by pushing  \n",
    "1. Back to step 2  \n",
    "\n",
    "\n",
    "- Occasionally dig back in history of diffs to figure smth out  \n",
    "- Checkout previous version of files  \n",
    "- Branching for experimental features  "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "#### Typical multiple coauthor Git workflow (without GitHub)\n",
    "\n",
    "1. Create/Clone repository *for each co-author*  \n",
    "1. Link repos by specifying remotes  \n",
    "1. Fetch latest changes by others, observe diffs  \n",
    "1. Merge their work into master  \n",
    "1. Checkout a particular branch to work in  \n",
    "1. Write/edit (text) files (**CODING HERE**)  \n",
    "1. Stage and commit  \n",
    "1. Merge work completed in other branches into *master*  \n",
    "1. Back to step 3  "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "#### Typical multiple coauthor Git workflow (with GitHub)\n",
    "\n",
    "1. Create repository on GitHub  \n",
    "1. Each author clones from GitHub to create local repository  \n",
    "1. Fetch and merge (pull) latest changes from GitHub **before doing any work**  \n",
    "1. Merge their work into master  \n",
    "1. Checkout a new branch to work in  \n",
    "1. Write/edit (text) files (**CODING HERE**)  \n",
    "1. Stage and commit  \n",
    "1. Push new branch to GitHub, create pull request  \n",
    "1. Back to step 2  "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "#### Exercise 1\n",
    "\n",
    "1. Create a test repository on GitHub  \n",
    "1. Edit README.md file online  \n",
    "1. Clone repository to the local machine  \n",
    "1. Observe the history of changes in the local GUI  \n",
    "1. Make several changes in the working directory  \n",
    "1. Commit changes  \n",
    "1. Push updated code to GitHub  \n",
    "1. Observe the changes on the server  "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "#### GitHub Social Coding\n",
    "\n",
    "- A number of instruments for social coding, beyond Git version control\n",
    "  - communications with users (*issue tracker*, *wiki pages*)\n",
    "  - sharing (*code releases*)\n",
    "  - interactions with other developers (*forking*,*pull requests*,*code reviews*)\n",
    "  - project web pages (*github pages*)  \n",
    "- [Interactive minicourse about GitHub](https://lab.github.com/githubtraining/introduction-to-github) [optional]  \n",
    "- Largely ignored this course  "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "#### GitHub Classroom\n",
    "\n",
    "- The course will use a GitHub add-on software GitHub Classroom  \n",
    "- Interface for automatic creation of repositories for assignments\n",
    "  - used for distributing assignment tasks (including midterm and final exam)\n",
    "  - each student (or group) works in own repository  \n",
    "- Turn your work in by committing and pushing to this repo\n",
    "  - Contact me if you want to opt out from using GitHub to submit assignments\n",
    "  - Alternative way to turn in your work will be made available  \n",
    "- To accept assignment, follow the distributed *assignment link*  "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "#### Jupyter notebooks are great\n",
    "\n",
    "- Excellent way to present and discuss code\n",
    "  - this entire course is tough using notebooks  \n",
    "- Good instrument to develop new ideas\n",
    "  - especially together with coauthors  \n",
    "- Saved to disk as JSON files with multiple sections\n",
    "  - text\n",
    "  - math and formulas in latex\n",
    "  - code (different languages are possible)\n",
    "  - output from the code  "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "#### Jupyter notebooks have limitations\n",
    "\n",
    "- NOT GOOD way to store developed code, use libraries (modules)  \n",
    "- NOT GOOD for version control\n",
    "  - changes in metadata are tracked\n",
    "  - changes in output are tracked\n",
    "  - merging changed files may break JSON format  \n",
    "- Require additional tools to work well with Git (see [https://pascalbugnion.net/blog/ipython-notebooks-and-git.html](https://pascalbugnion.net/blog/ipython-notebooks-and-git.html))  \n",
    "- We don’t worry about it for the most of the course  "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "#### Exercise 2\n",
    "\n",
    "1. Clone course repository  \n",
    "1. Run lecture notebook locally  \n",
    "1. Observe and commit changes  \n",
    "1. Pull to check if new lecture materials have become available  "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Further learning resources\n",
    "\n",
    "- Simple guide to Git [http://rogerdudler.github.io/git-guide/](http://rogerdudler.github.io/git-guide/)  \n",
    "- Further on version control and Git [https://git-scm.com/doc](https://git-scm.com/doc)  \n",
    "- More on GitHub [https://guides.github.com/](https://guides.github.com/)  \n",
    "- Tutorial in Jupyter Notebook\n",
    "  [https://medium.com/codingthesmartway-com-blog/getting-started-with-jupyter-notebook-for-python-4e7082bd5d46](https://medium.com/codingthesmartway-com-blog/getting-started-with-jupyter-notebook-for-python-4e7082bd5d46)  \n",
    "- Markdown syntax cheatsheet\n",
    "  [https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet)  "
   ]
  }
 ],
 "metadata": {
  "celltoolbar": "Slideshow",
  "date": 1612589584.299636,
  "download_nb": false,
  "filename": "02_workspace.rst",
  "filename_with_path": "02_workspace",
  "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"
  },
  "title": "Foundations of Computational Economics"
 },
 "nbformat": 4,
 "nbformat_minor": 4
}