03_software-development/03_continuous-integration.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "[Table of contents](../toc.ipynb)\n",
    "\n",
    "# Continuous integration (CI)\n",
    "\n",
    "* Continuous integration (CI) is a concept where changes from developers are integrated and tested into main version of software within short cycles. \n",
    "\n",
    "* CI is often twinned with CD, which mean continuous delivery. In CD, the concept is to be able to create a deliverable software product for costumers in short cycles.\n",
    "\n",
    "* CI/CD (we will just consider CI in the latter) fosters automation of manual tasks and provides foundation for distributed development on short cycles.\n",
    "\n",
    "* Short cycles means daily and often many times a day."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## Why integrate in short cycles?\n",
    "\n",
    "We have seen previously that **cost of change is roughly an exponential function of time** of development process. Hence, the earlier you find errors the cheaper and easier they can be resolved.\n",
    "\n",
    "Add to this, **software development in teams requires to split larger chunks of work** (often called a feature) into smaller ones (often called story) so that developers can work simultaneously. **Without CI, tests can be just applied after integration of all stories**. If this fails, the entire feature is incomplete."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "Take a look at this figure where a feature is developed by Peter and Joe. With CI, each commit (circle) of Peter and Joe triggers a test of the entire software. \n",
    "\n",
    "Note that two commits of Joe contained a bug. However, due to direct feedback of CI, Joe noticed directly that something went wrong and he resolved the bug in the next commit. Therefore, Peters changes were not corrupted by the bugs and integration went well through.\n",
    "\n",
    "<img src=\"distributed_dev.svg\" alt=\"git\" width=\"700\">\n",
    "\n",
    "Therefore, CI ensures that the software remains *soft*. Developers do not hesitate to change the software and small changes can be integrated very fast."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## Requirements for CI\n",
    "\n",
    "If you want to apply in your development - which is a must today I would say - your project needs to address these requirements:\n",
    "\n",
    "* The software is under version control (git).\n",
    "* Tests are either together with code or before coding written (test driven development).\n",
    "* The test and build steps are automated and this automation is also under version control.\n",
    "* A CI software triggers tests and builds on events like commits or pull requests and stores and returns results.\n",
    "* Build slaves are available (hardware PCs or cloud services) to test and build the software.\n",
    "* Tests and build are fast.\n",
    "* You need a cultural environment that fosters failing fast and prioritizes bug fixes.\n",
    "\n",
    "You see, there are many requirements. However, if you address them, the quality and maintainability of software will improve drastically."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## Theory or practice?\n",
    "\n",
    "We could of course proceed with theory about CI. However, I guess the mindset behind CI is more important.\n",
    "\n",
    "* Automate the boring stuff! People believing that a checklist and manual quality tests are a way to ensure quality have not much practical experience.\n",
    "  * No one wants and will go through a checklist in daily business and run manual tests.\n",
    "* Test often, test fast!\n",
    "* Use all weapons you have (static analysis, dynamic tests, integration tests,...)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "CI techniques are developing very fast and that is why we explore some tools shortly before we get our hands dirty and set up a CI pipeline."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## CI solutions\n",
    "\n",
    "CI is state of the art in software development and there are many tools and solutions available. Here a short incomplete list of solutions.\n",
    "\n",
    "* [Jenkins](https://jenkins.io/) the probably most applied automation server. Very flexible and rich of features on the price of not so simple to learn and maintain from my experience. With Jenkins, you can do anything, but you need rather expert knowledge.\n",
    "\n",
    "* [Travis CI](https://travis-ci.org/) a more lightweight solution compared with Jenkins for CI. Easy to use and directly integrated as service in Github. I used Travis CI for instance to test all Jupyter notebooks of this course. Take a look here: [![Build Status](https://travis-ci.com/StephanRhode/py-algorithms-4-automotive-engineering.svg?branch=master)](https://travis-ci.com/StephanRhode/py-algorithms-4-automotive-engineering)\n",
    "\n",
    "* [GitHub Actions](https://github.com/features/actions) a quite recent CI feature of GitHub which of course is very easy to use. Most lightweight solution for GitHub repos currently I would say.\n",
    "\n",
    "* Tens of other solutions! Just search for CI and many tools will show up."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## Exercise:  Build a CI pipeline in GitHub-Actions (30 minutes)\n",
    "\n",
    "<img src=\"../_static/exercise.png\" alt=\"Exercise\" width=\"75\" align=\"left\">\n",
    "\n",
    "Now we want to create our first small CI pipeline with the next steps. This will be a rather long exercise in several steps.\n",
    "\n",
    "* Login into your GitHub account and create a repository with an open source license of your choice.\n",
    "* Clone this repository to your computer.\n",
    "* Create commit and push the following empty files to the repo: `my_source.py`, `test_my_source.py`, and `requirements.txt`.\n",
    "* Go to GitHub, open this repository and click on actions and select `Python application`. \n",
    "\n",
    "<img src=\"github_actions.png\" alt=\"github_actions\" width=\"700\">"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "### Check structure and `pythonapp.yml`\n",
    "\n",
    "The repository should have now this structure:\n",
    "```\n",
    "|___ .github\n",
    "    |___ workflows\n",
    "        |___ pythonapp.yml \n",
    "|___ README.md\n",
    "|___ LICENSE\n",
    "|___ my_source.py\n",
    "|___ test_my_source.py\n",
    "|___ requirements.txt\n",
    "\n",
    "```\n",
    "\n",
    "Open the `pythonapp.yml` file and try to understand what the code tells."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "### `requirements.txt`\n",
    "\n",
    "Now copy and paste\n",
    "```\n",
    "pytest\n",
    "pytest-cov\n",
    "flake8\n",
    "pylint\n",
    "pydocstyle\n",
    "```\n",
    "into `requirements.txt`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "### `my_source.py`\n",
    "\n",
    "Copy and paste\n",
    "```python\n",
    "\"\"\"Contains code under test for solution_ci.\"\"\"\n",
    "\n",
    "def add_func(a, var_two):\n",
    "    \"\"\"\n",
    "    Add two variables.\n",
    "\n",
    "    Args\n",
    "        a: first variable\n",
    "        var_two: second variable\n",
    "\n",
    "    \"\"\"\n",
    "    return a + var_two\n",
    "```\n",
    "into `my_source.py`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "### `test_my_source.py`\n",
    "\n",
    "Copy and paste\n",
    "```python\n",
    "import pytest\n",
    "from my_source import add_func\n",
    "\n",
    "\n",
    "def test_add_one():\n",
    "    assert add_func(2, 5) == 7\n",
    "\n",
    "\n",
    "@pytest.mark.xfail\n",
    "def test_add_fail():\n",
    "    assert add_func(5, 5) == 9\n",
    "```\n",
    "into `test_my_source.py`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "### Append `pythonapp.yml`\n",
    "\n",
    "And finally append these lines to `pythonapp.yml` to trigger additional build steps.\n",
    "```yml\n",
    "    - name: Lint with pylint\n",
    "      run: |\n",
    "        pylint --exit-zero my_source.py\n",
    "    - name: Test with pytest\n",
    "      run: |\n",
    "        pytest\n",
    "    - name: Code coverage\n",
    "      run: |\n",
    "        pytest --cov-report term-missing --cov\n",
    "    - name: Pydocstyle\n",
    "      run: |\n",
    "        pydocstyle\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "### Check CI on GitHub\n",
    "\n",
    "Now commit and push these changes and take a look at the actions field in GitHub.\n",
    "* Does the build run?\n",
    "* Check your emails, you should receive notifications from GitHub.\n",
    "* What kind of messages are provided?\n",
    "\n",
    "<img src=\"actions_result.png\" alt=\"actions_result\" width=\"700\">"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "### Try a bug\n",
    "\n",
    "* Now, try to change one assertion in `test_my_source.py`. Does now the build fail?\n",
    "\n",
    "### Improve pylint rating\n",
    "* Take a look at pylint field. It gives a hint to improve the code.\n",
    "* Try to resolve it."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## Solution\n",
    "\n",
    "You can compare your solution with this repository \n",
    "\n",
    "https://github.com/StephanRhode/solution_ci"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## Books on CI\n",
    "\n",
    "Please find here two books on continuous integration topic.\n",
    "\n",
    "* The Hitchhiker's Guide to Python [[Schlusser2016]](../references.bib).\n",
    "* Continuous integration improving software quality and reducing risk [[Duvall2013]](../references.bib).\n",
    "\n",
    "## Tutorial on Python CI\n",
    "\n",
    "Add to this, there are numerous web courses out there and one great and free tutorial which explains how to apply CI for Python is on realpython.com [https://realpython.com/python-continuous-integration/](https://realpython.com/python-continuous-integration/)."
   ]
  }
 ],
 "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"
  },
  "toc": {
   "base_numbering": 1,
   "nav_menu": {},
   "number_sections": true,
   "sideBar": true,
   "skip_h1_title": false,
   "title_cell": "Table of Contents",
   "title_sidebar": "Contents",
   "toc_cell": false,
   "toc_position": {},
   "toc_section_display": true,
   "toc_window_display": true
  },
  "varInspector": {
   "cols": {
    "lenName": 16,
    "lenType": 16,
    "lenVar": 40
   },
   "kernels_config": {
    "python": {
     "delete_cmd_postfix": "",
     "delete_cmd_prefix": "del ",
     "library": "var_list.py",
     "varRefreshCmd": "print(var_dic_list())"
    },
    "r": {
     "delete_cmd_postfix": ") ",
     "delete_cmd_prefix": "rm(",
     "library": "var_list.r",
     "varRefreshCmd": "cat(var_dic_list()) "
    }
   },
   "types_to_exclude": [
    "module",
    "function",
    "builtin_function_or_method",
    "instance",
    "_Feature"
   ],
   "window_display": false
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}