manage_python_project.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "0",
   "metadata": {},
   "source": [
    "# Manage Python project"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1",
   "metadata": {},
   "source": [
    "# Table of Contents\n",
    "  - [Manage Python project](#Manage-Python-project)\n",
    "  - [References](#References)\n",
    "  - [Introduction](#Introduction)\n",
    "    - [Preparatory exercise](#Preparatory-exercise)\n",
    "  - [The `pyproject.toml` file](#The-pyproject.toml-file)\n",
    "    - [The `project` section](#The-project-section)\n",
    "    - [Dependency specification](#Dependency-specification)\n",
    "    - [Optional dependencies](#Optional-dependencies)\n",
    "    - [Exercise on the `pyproject.toml` file.](#Exercise-on-the-pyproject.toml-file.)\n",
    "  - [Pre-commit](#Pre-commit)\n",
    "    - [Installation and running](#Installation-and-running)\n",
    "    - [Configuration](#Configuration)\n",
    "    - [Supported hooks](#Supported-hooks)\n",
    "      - [Auto-formatters](#Auto-formatters)\n",
    "      - [Linters](#Linters)\n",
    "      - [Type checks](#Type-checks)\n",
    "    - [pre-commit.ci](#pre-commit.ci)\n",
    "    - [Exercise on pre-commit](#Exercise-on-pre-commit)\n",
    "  - [Testing](#Testing)\n",
    "    - [Types of tests](#Types-of-tests)\n",
    "    - [Installation](#Installation)\n",
    "    - [Write your first unit test](#Write-your-first-unit-test)\n",
    "    - [Run the tests](#Run-the-tests)\n",
    "    - [Test driven development (TDD)](#Test-driven-development-(TDD))\n",
    "    - [Code coverage](#Code-coverage)\n",
    "  - [Documentation](#Documentation)\n",
    "    - [Why document?](#Why-document?)\n",
    "    - [How document?](#How-document?)\n",
    "    - [Comments](#Comments)\n",
    "    - [Docstrings](#Docstrings)\n",
    "    - [Type hints](#Type-hints)\n",
    "    - [Markdown](#Markdown)\n",
    "    - [README.md](#README.md)\n",
    "    - [Exercise on README.md](#Exercise-on-README.md)\n",
    "    - [GitHub wiki](#GitHub-wiki)\n",
    "    - [Read the Docs](#Read-the-Docs)\n",
    "      - [Configuration](#Configuration)\n",
    "      - [Writing the documentation](#Writing-the-documentation)\n",
    "      - [Building the documentation](#Building-the-documentation)\n",
    "      - [Deploying on Read the Docs](#Deploying-on-Read-the-Docs)\n",
    "  - [Releasing package](#Releasing-package)\n",
    "    - [Why release?](#Why-release?)\n",
    "    - [Update the version](#Update-the-version)\n",
    "    - [Python Package Index (PyPI)](#Python-Package-Index-(PyPI))\n",
    "    - [Changelog](#Changelog)\n",
    "      - [CHANGELOG.md](#CHANGELOG.md)\n",
    "      - [GitHub releases](#GitHub-releases)\n",
    "  - [Automate things](#Automate-things)\n",
    "    - [Testing](#Testing)\n",
    "    - [Exercise on testing automation](#Exercise-on-testing-automation)\n",
    "    - [Version update](#Version-update)\n",
    "    - [Exercise on version update automation](#Exercise-on-version-update-automation)\n",
    "    - [Releasing](#Releasing)\n",
    "    - [Exercises on releasing automation](#Exercises-on-releasing-automation)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2",
   "metadata": {},
   "source": [
    "# References\n",
    "\n",
    "- [Python Packaging User Guide](https://packaging.python.org/)\n",
    "- [PEP 518](https://www.python.org/dev/peps/pep-0518/) – Specifying Minimum Build System Requirements for Python Projects\n",
    "- [Pre-commit](https://pre-commit.com/) and its documentation.\n",
    "- [Pytest documentation.](https://docs.pytest.org/en/latest/)\n",
    "- [Python Packages book](https://py-pkgs.org/) by Tomas Beuzen and Tiffany Timbers."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3",
   "metadata": {},
   "source": [
    "# Introduction\n",
    "\n",
    "In the basic tutorial we have discussed the package structure.\n",
    "\n",
    "We came up with the following setup:\n",
    "\n",
    "```bash\n",
    "mypackage/\n",
    "├── mypackage\n",
    "│   ├── __init__.py\n",
    "│   ├── geometry\n",
    "│   │   ├── __init__.py\n",
    "│   │   └── geometry.py\n",
    "│   └── utils.py\n",
    "└── pyproject.toml\n",
    "```\n",
    "\n",
    "Where the content of the `pyprojects.toml` file is:\n",
    "\n",
    "```toml\n",
    "[build-system]\n",
    "requires = [\"flit_core >=3.2,<4\"]\n",
    "build-backend = \"flit_core.buildapi\"\n",
    "\n",
    "[project]\n",
    "name = \"mypackage\"\n",
    "version = \"0.1.0\"\n",
    "description = \"My first package\"\n",
    "```\n",
    "\n",
    "This is a minimal setup to create a package that can be installed with `pip`.\n",
    "However, we can do better, way better.\n",
    "We can expand the `pyproject.toml` file, as well as automate code formatting, testing, and releasing.\n",
    "\n",
    "For the following exercises you can either use some package you develop or the [mypackage](https://github.com/empa-scientific-it/mypackage) we have created in the basic tutorial.\n",
    "In case you use the `mypackage` you can fork it to your own GitHub account and clone it to your local machine."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4",
   "metadata": {},
   "source": [
    "## Preparatory exercise\n",
    "\n",
    "1. Decide which package you want to use for the following exercises, yours or the [mypackage](https://github.com/empa-scientific-it/mypackage).\n",
    "2. If you use the `mypackage` fork it to your own GitHub account by clicking on the `Fork` button in the top right corner.\n",
    "3. Clone the package to your local machine: `git clone <url-to-your-repository>`.\n",
    "\n",
    "<div class=\"alert alert-block alert-info\">\n",
    "In the following, we will always assume that <code>mypackage</code> is the package you are working on (either yours or the one you have forked).\n",
    "</div>\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5",
   "metadata": {},
   "source": [
    "# The `pyproject.toml` file\n",
    "\n",
    "The `pyproject.toml` file is a configuration file that is used by the build system.\n",
    "To read more about the `pyproject.toml` file, see [PEP 518](https://www.python.org/dev/peps/pep-0518/).\n",
    "\n",
    "Let' start by adding more information to the `pyproject.toml` file."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6",
   "metadata": {},
   "source": [
    "## The `project` section\n",
    "\n",
    "The `project` section contains information about the Python package.\n",
    "The `name` and `version` are required fields, the other fields are optional.\n",
    "However, it is recommended to provide as much information as possible about your package.\n",
    "Let's take a look at the [`pyproject.toml` file](https://github.com/numpy/numpy/blob/main/pyproject.toml) of the `numpy` package:\n",
    "\n",
    "```toml\n",
    "[project]\n",
    "name = \"numpy\"\n",
    "version = \"2.0.0.dev0\"\n",
    "license = {file = \"LICENSE.txt\"}\n",
    "\n",
    "description = \"Fundamental package for array computing in Python\"\n",
    "authors = [{name = \"Travis E. Oliphant et al.\"}]\n",
    "maintainers = [\n",
    "    {name = \"NumPy Developers\", email=\"numpy-discussion@python.org\"},\n",
    "]\n",
    "requires-python = \">=3.9\"\n",
    "readme = \"README.md\"\n",
    "classifiers = [\n",
    "    'Development Status :: 5 - Production/Stable',\n",
    "    'Intended Audience :: Science/Research',\n",
    "    'Intended Audience :: Developers',\n",
    "    'License :: OSI Approved :: BSD License',\n",
    "    'Programming Language :: C',\n",
    "    'Programming Language :: Python',\n",
    "    'Programming Language :: Python :: 3',\n",
    "    'Programming Language :: Python :: 3.9',\n",
    "    'Programming Language :: Python :: 3.10',\n",
    "    'Programming Language :: Python :: 3.11',\n",
    "    'Programming Language :: Python :: 3.12',\n",
    "    'Programming Language :: Python :: 3 :: Only',\n",
    "    'Programming Language :: Python :: Implementation :: CPython',\n",
    "    'Topic :: Software Development',\n",
    "    'Topic :: Scientific/Engineering',\n",
    "    'Typing :: Typed',\n",
    "    'Operating System :: Microsoft :: Windows',\n",
    "    'Operating System :: POSIX',\n",
    "    'Operating System :: Unix',\n",
    "    'Operating System :: MacOS',\n",
    "]\n",
    "\n",
    "[project.urls]\n",
    "homepage = \"https://numpy.org\"\n",
    "documentation = \"https://numpy.org/doc/\"\n",
    "source = \"https://github.com/numpy/numpy\"\n",
    "download = \"https://pypi.org/project/numpy/#files\"\n",
    "tracker = \"https://github.com/numpy/numpy/issues\"\n",
    "\"release notes\" = \"https://numpy.org/doc/stable/release\"\n",
    "\n",
    "```\n",
    "\n",
    "Here is what each field means:\n",
    "\n",
    "\n",
    "| Key          | Type      | Description |\n",
    "|--------------|-----------|------------|\n",
    "| `name`       | string    | The name of the package. |\n",
    "| `version`    | string    | The version of the package. |\n",
    "| `description`| string    | A short description of the package. |\n",
    "| `license`    | table     | Path to the license file relative to the `pyproject.toml` file. One can also provide the content of the license in the `text` field: `license = {text = \"BSD 3-Clause License\"}`. Keep in mind that the `file` and `text` fields are mutually exclusive.|\n",
    "| `authors` [1]    | array of tables     | A list of authors. Each author is a table with `name` and `email` keys. The `name` key is a string that contains the name of the author or maintainer. The `email` key is a string that contains the email address of the author or maintainer.  One can provide either both keys of only one of them.|\n",
    "| `maintainers` [1]    | array of tables     | Same as for `authors`.|\n",
    "| `requires-python` | string | The Python version required to run the package. |\n",
    "| `readme` | string or table | The path to the readme file relative to the `pyproject.toml` file. One can also provide the content of the readme file in the `text` field. Finally, one can provide a table with `file` and `content-type` keys.|\n",
    "| `classifiers` | array of strings | A list of [trove classifiers](https://pypi.org/classifiers/). These classifiers are used to categorize the package. Make sure to provide as complete list of classifiers as possible.|\n",
    "| `urls` | table | A table of URLs. The key is the URL label and the value is the URL itself.|\n",
    "\n",
    "\n",
    "[1] Accordnig to the [official documentation](https://packaging.python.org/en/latest/specifications/declaring-project-metadata/#authors-maintainers) the meaning of these fileds is open to interpretation."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7",
   "metadata": {},
   "source": [
    "## Dependency specification\n",
    "\n",
    "The `pyproject.toml` file can also be used to specify the dependencies of the package.\n",
    "All the dependencies are listed under the `dependencies` key in the `project` section as an array of strings.\n",
    "Each string must be formatted as a valid [PEP 508](https://www.python.org/dev/peps/pep-0508/) dependency specifier.\n",
    "\n",
    "For example, the following `pyproject.toml` file specifies that the package requires `httpx` and `gidgethub` with a version greater than `4.0.0`:\n",
    "\n",
    "```toml\n",
    "[project]\n",
    "dependencies = [\n",
    "  \"httpx\",\n",
    "  \"gidgethub>4.0.0\",\n",
    "]\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8",
   "metadata": {},
   "source": [
    "## Optional dependencies\n",
    "\n",
    "Optional dependencies can be specified in the `optional-dependencies` key in the `project` section.\n",
    "The value of this key is a table where the key is the name of the optional dependency and the value is an array of strings that specify the dependencies of the optional dependency.\n",
    "Usually, one needs to define separate set of dependencies for development and documentation.\n",
    "\n",
    "```toml\n",
    "[project.optional-dependencies]\n",
    "dev = [\n",
    "  \"bumpver==2023.1129\",\n",
    "  \"pre-commit==3.5.0\",\n",
    "  \"pytest==7.4.3\",\n",
    "  \"pytest-cov==2.6.1\",\n",
    "]\n",
    "docs = [\n",
    "  \"sphinx==4.2.0\",\n",
    "  \"sphinx-rtd-theme==1.0.0\",\n",
    "]\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9",
   "metadata": {},
   "source": [
    "## Exercise on the `pyproject.toml` file.\n",
    "\n",
    "1. Add an MIT license to `mypackage` and refer to it in the `pyproject.toml` file.\n",
    "2. Specify the dependencies of `mypackage` in the `pyproject.toml` file.\n",
    "3. Specify optional development dependencies in the `pyproject.toml` file.\n",
    "4. Try to re-install `mypackage` with `pip` and see if it works and all the optional dependencies are installed."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "10",
   "metadata": {},
   "source": [
    "# Pre-commit\n",
    "\n",
    "[Pre-commit](https://pre-commit.com/) is a framework for managing and maintaining multi-language pre-commit hooks.\n",
    "\n",
    "Pre-commit hooks are small scripts that are executed before a commit is created.\n",
    "These scripts can be used to check the code for formatting errors, syntax errors, and other issues.\n",
    "If a pre-commit hook fails, the commit is aborted."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "11",
   "metadata": {},
   "source": [
    "## Installation and running\n",
    "\n",
    "To install pre-commit, run the following command:\n",
    "\n",
    "```bash\n",
    "pip install pre-commit\n",
    "```\n",
    "\n",
    "However, it is common to install pre-commit as part of the development dependencies, see [above](#Optional-dependencies).\n",
    "\n",
    "To run pre-commit, run the following command:\n",
    "\n",
    "```bash\n",
    "pre-commit run --all-files\n",
    "```\n",
    "This command will run all the pre-commit hooks on all the files in the repository.\n",
    "However, this command will fail if there is no `.pre-commit-config.yaml` file in the current directory.\n",
    "We will discuss the `.pre-commit-config.yaml` file in the next section.\n",
    "\n",
    "Usually, one would run pre-commit on the files that are about to be committed.\n",
    "It turns out that pre-commit can do that for us.\n",
    "To do so, we need to install a pre-commit hook that will run pre-commit on the files that are about to be committed.\n",
    "To install the pre-commit hook, run the following command:\n",
    "\n",
    "```bash\n",
    "pre-commit install\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "12",
   "metadata": {},
   "source": [
    "## Configuration\n",
    "\n",
    "To configure pre-commit, we need to create a `.pre-commit-config.yaml` file in the root of the repository.\n",
    "This file contains the configuration of the pre-commit hooks.\n",
    "The following example shows how to configure pre-commit to \n",
    "\n",
    "```yaml\n",
    "---\n",
    "repos:\n",
    "    - repo: https://github.com/pre-commit/pre-commit-hooks\n",
    "      rev: v4.4.0\n",
    "      hooks:\n",
    "          - id: end-of-file-fixer\n",
    "          - id: trailing-whitespace\n",
    "          - id: check-yaml\n",
    "          - id: check-added-large-files\n",
    "```\n",
    "\n",
    "As you can see, we provide a list of repositories and for each repository we specify the revision (version in other words) and the hooks that we want to use.\n",
    "This is by far not the complete configuration, but it is a good start."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "13",
   "metadata": {},
   "source": [
    "## Supported hooks\n",
    "\n",
    "Pre-commit supports a wide range of hooks.\n",
    "The full list can be found [here](https://pre-commit.com/hooks.html).\n",
    "However, in this tutorial we will only discuss the commonly used ones."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "14",
   "metadata": {},
   "source": [
    "### Auto-formatters\n",
    "\n",
    "Auto-formatters are tools that automatically format the code.\n",
    "They take away from you the burden of ensuring the consistency of the code style.\n",
    "We recommend to use the following formatters:\n",
    "\n",
    "- [isort](https://pycqa.github.io/isort/) for sorting imports.\n",
    "- [autoflake](https://github.com/PyCQA/autoflake) for removing unused imports and variables.\n",
    "- [black](https://black.readthedocs.io/en/stable/) for an uncompromising code formatting (it really is!).\n",
    "\n",
    "Here is the configuration of these formatters:\n",
    "\n",
    "```yaml\n",
    "    - repo: https://github.com/pycqa/isort\n",
    "      rev: 5.12.0\n",
    "      hooks:\n",
    "          - id: isort\n",
    "            args: [--profile, black, --filter-files]\n",
    "    - repo: https://github.com/PyCQA/autoflake\n",
    "      rev: v2.1.1\n",
    "      hooks:\n",
    "          - id: autoflake\n",
    "    - repo: https://github.com/psf/black\n",
    "      rev: 23.3.0\n",
    "      hooks:\n",
    "          - id: black\n",
    "            language_version: python3\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "15",
   "metadata": {},
   "source": [
    "### Linters\n",
    "Linters are tools that check the code for errors and potential issues.\n",
    "We recommend to use [flake8](https://flake8.pycqa.org/en/latest/) as a linter.\n",
    "\n",
    "\n",
    "```yaml\n",
    "    - repo: https://github.com/PyCQA/flake8\n",
    "      rev: 6.0.0\n",
    "      hooks:\n",
    "          - id: flake8\n",
    "```\n",
    "\n",
    "Note, however, that with the default configuration `flake8` conflicts with `black`.\n",
    "To avoid this conflict, we need to configure `flake8` to ignore the formatting issues.\n",
    "Here is the configuration of `flake8` to be put to `.flake8` file in the root of the repository:\n",
    "\n",
    "```\n",
    "[flake8]\n",
    "extend-ignore =\n",
    "    E501\n",
    "    W503\n",
    "    E203\n",
    "```\n",
    "\n",
    "The vanilla `flake8` provides only basic checks.\n",
    "However, its functionality can be extended with plugins.\n",
    "For example, we recommend to use the following plugins:\n",
    "\n",
    "- [flake8-bugbear](https://github.com/PyCQA/flake8-bugbear) for finding common bugs and design problems.\n",
    "- [flake8-builtins](https://pypi.org/project/flake8-builtins/) for verifying that builtins are not used as variable names.\n",
    "- [flake8-comprehensions](https://pypi.org/project/flake8-comprehensions/) for writing better and consistent comprehensions.\n",
    "- [flake8-debugger](https://pypi.org/project/flake8-debugger/) for checking that there are no forgotten [breakpoints](https://docs.python.org/3/library/functions.html#breakpoint).\n",
    "- [flake8-eradicate](https://pypi.org/project/flake8-eradicate/) to avoid “dead” or commented code.\n",
    "- [flake8-logging-format](https://github.com/globality-corp/flake8-logging-format) for consistent logging.\n",
    "- [pep8-naming](https://pypi.org/project/pep8-naming/) for verifying that PEP8 naming conventions are followed.\n",
    "- [tryceratops](https://pypi.org/project/tryceratops/) to avoid exception anti-patterns.\n",
    "\n",
    "Here is the configuration of these plugins:\n",
    "\n",
    "```yaml\n",
    "    - repo: https://github.com/PyCQA/flake8\n",
    "      rev: 6.0.0\n",
    "      hooks:\n",
    "          - id: flake8\n",
    "            args: [--count, --show-source, --statistics]\n",
    "            additional_dependencies:\n",
    "                - flake8-bugbear\n",
    "                - flake8-builtins\n",
    "                - flake8-comprehensions\n",
    "                - flake8-debugger\n",
    "                - flake8-eradicate\n",
    "                - flake8-logging-format\n",
    "                - pep8-naming\n",
    "                - tryceratops\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "16",
   "metadata": {},
   "source": [
    "### Type checks\n",
    "\n",
    "Type checks are tools that check that the code is properly annotated with type hints.\n",
    "Proper type annotations help to catch bugs and make the code more readable.\n",
    "Also, they remove the need for an extended documentation.\n",
    "\n",
    "To make sure the types are properly check, we recommend to use the [`mypy`](https://github.com/python/mypy) type checker.\n",
    "To get more information on mypy we refer the reader to [this blog post](https://blog.wolt.com/engineering/2021/09/30/professional-grade-mypy-configuration/).\n",
    "Also, you can check this 10-minutes [video](https://www.youtube.com/watch?v=2xWhaALHTvU) to learn about `mypy`."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "17",
   "metadata": {},
   "source": [
    "\n",
    "## pre-commit.ci\n",
    "\n",
    "[pre-commit.ci](https://pre-commit.ci/) is a service that runs pre-commit hooks on every commit pushed to GitHub.\n",
    "This service is free for open source projects.\n",
    "To use this service, first make sure to have `.pre-commit-config.yaml` file in the root of the repository.\n",
    "Then, go to [pre-commit.ci](https://pre-commit.ci/), click on `Sign up with GitHub` and follow the instructions.\n",
    "\n",
    "Whenever you push a commit to GitHub, pre-commit.ci will run the pre-commit hooks and will report the result of the execution.\n",
    "\n",
    "Pre-commit.ci monitors pre-commit hook versions.\n",
    "When a new version is available, it automatically generates a pull request to update it.\n",
    "We suggest runnint g these checks quarterly to minimize excessive pull requests and maintain a clean project history.\n",
    "To configure that add at the top of your `.pre-commit-config.yaml` file the following lines:\n",
    "\n",
    "```yaml\n",
    "ci:\n",
    "    autoupdat_schedule: quarterly\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "18",
   "metadata": {},
   "source": [
    "## Exercise on pre-commit\n",
    "\n",
    "For the exercise, we will use the `mypackage` package that we have created in the basic tutorial.\n",
    "\n",
    "1. Install pre-commit as a development dependency.\n",
    "2. Enable basic pre-commit hooks (`end-of-file-fixer`, `trailing-whitespace`) and apply them to your repository.\n",
    "3. Enable `isort` pre-commit hook and apply it to your repository.\n",
    "4. Enable `autoflake` pre-commit hook and apply it to your repository.\n",
    "5. Enable `black` pre-commit hook and apply it to your repository.\n",
    "6. Enable `flake8` pre-commit hook and apply it to your repository.\n",
    "What issues does it find?\n",
    "Can you fix them?\n",
    "7. Enable pre-commit.ci for your repository."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "19",
   "metadata": {},
   "source": [
    "# Testing\n",
    "\n",
    "In this section we will discuss how to test your package.\n",
    "We will focus on the automated testing done with [pytest](https://docs.pytest.org/en/latest).\n",
    "\n",
    "Why do we need testing?\n",
    "The answer is simple: to make sure that the code works as expected.\n",
    "The other not-so-obvious reason is to make sure the old code continues to work as expected when new changes are introduced."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "20",
   "metadata": {},
   "source": [
    "## Types of tests\n",
    "\n",
    "Globally, the testing can be split into two categories: functional and non-functional testing.\n",
    "Functional testing is testing that the code does what it is supposed to do.\n",
    "Non-functional testing is testing that the code is written in secure, scalable and user-friendly way.\n",
    "In this tutorial we will focus on functional testing only.\n",
    "\n",
    "Functional testing can be further split into unit testing, integration testing, and system testing.\n",
    "\n",
    "* **Unit testing** is testing of individual units of code, usually functions and classes.\n",
    "\n",
    "* **Integration testing** is testing of the interaction between different units of code.\n",
    "The goal here is to make sure that the units of code work together as expected.\n",
    "\n",
    "* **System testing**.\n",
    "There are many sub-categories of system testing, but in general it is testing of the whole system.\n",
    "In our case, it is testing of the whole package.\n",
    "We consider the most relevant sub-category of system testing is **smoke testing**.\n",
    "Smoke testing is testing of the most important functionality of the system.\n",
    "Basically, the idea here is to launch the package with number of standard inputs and check that the outputs are as expected.\n",
    "\n",
    "In this tutorial we will focus on unit testing and smoke testing.\n",
    "If you want to know more, please refer to [this article](https://www.blazemeter.com/blog/functional-testing-types)."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "21",
   "metadata": {},
   "source": [
    "## Installation\n",
    "\n",
    "To install pytest, run the following command:\n",
    "\n",
    "```bash\n",
    "pip install pytest\n",
    "```\n",
    "\n",
    "But, as for the pre-commit, it is common to install pytest as part of the development dependencies, see [above](#Optional-dependencies)."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "22",
   "metadata": {},
   "source": [
    "## Write your first unit test\n",
    "\n",
    "Usually, tests are located in the `tests` directory in the root of the repository.\n",
    "We do not recommend to put the tests in the same directory as the code, as they don't need to be distributed with the package.\n",
    "The file names of the tests should start with `test_` and end with `.py`.\n",
    "The functions that contain the tests should start with `test_`.\n",
    "\n",
    "\n",
    "\n",
    "Let's write a simple test for the `divide` function that we have created in the basic tutorial.\n",
    "Place the code below to the `tests/test_divide.py` file of `mypackage` folder.\n",
    "\n",
    "```python\n",
    "def divide(a, b):\n",
    "    return a / b\n",
    "\n",
    "def test_divide():\n",
    "    assert divide(1, 2) == 0.5\n",
    "```\n",
    "\n",
    "\n",
    "The `assert` statement checks that the condition is `True`.\n",
    "If the condition is `False`, the `assert` statement raises an `AssertionError` exception and the test fails.\n",
    "\n",
    "\n",
    "<div class=\"alert alert-block alert-info\">\n",
    "A test is considered successful if no exceptions are raised during its execution.\n",
    "</div>\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "23",
   "metadata": {},
   "source": [
    "## Run the tests\n",
    "\n",
    "To run the tests, simply run the following command:\n",
    "\n",
    "```bash\n",
    "pytest\n",
    "```\n",
    "\n",
    "The `pytest` tool will automatically discover the tests and run them.\n",
    "For more information on the test discovery, see [here](https://docs.pytest.org/en/latest/goodpractices.html#test-discovery)."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "24",
   "metadata": {},
   "source": [
    "## Test driven development (TDD)\n",
    "\n",
    "Test driven development is a software development process that relies on the repetition of a very short development cycle.\n",
    "The cycle is as follows:\n",
    "1. Write a test that relies on the expected behavior of the code.\n",
    "2. Run the test that fails, as the code is not yet implemented.\n",
    "3. Write the code to implement the expected behavior.\n",
    "4. Run the test, if it passes go to the next test, otherwise go to step 3.\n",
    "5. Refactor the code.\n",
    "6. Run the test to make sure that the refactoring did not break anything.\n",
    "\n",
    "This might seem like a lot of work, but it is not.\n",
    "In practice you always test your code, so the only difference is that you write the test before the code.\n",
    "This approach has many advantages:\n",
    "  - You know when you are done with the implementation.\n",
    "  - You know when you break something.\n",
    "  - You prevent other from breaking your code."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "25",
   "metadata": {},
   "source": [
    "## Code coverage\n",
    "\n",
    "Test coverage is defined as the percentage of code that is being executed during the tests with respect to the total amount of loaded code.\n",
    "To make this clear, let's consider the following example.\n",
    "\n",
    "```python\n",
    "\n",
    "def do_something(condition):\n",
    "    if condition:\n",
    "        return 1\n",
    "    else:\n",
    "        return 2\n",
    "\n",
    "```\n",
    "\n",
    "In this example, the function `do_something` has two branches: one for `True` and one for `False`.\n",
    "If we only test the `True` branch, the test coverage won't be 100%, as the `False` branch is not tested:\n",
    "\n",
    "```python\n",
    "def test_do_something():\n",
    "    assert do_something(True) == 1\n",
    "```\n",
    "\n",
    "To request the test coverage, we need to add `--cov` flag to the `pytest` command.\n",
    "\n",
    "```bash\n",
    "pytest --cov\n",
    "```\n",
    "\n",
    "Also, we need to install the `pytest-cov` plugin:\n",
    "\n",
    "```bash\n",
    "pip install pytest-cov\n",
    "```\n",
    "\n",
    "However, as usual, it is common to install `pytest-cov` as part of the development dependencies, see [above](#Optional-dependencies).\n",
    "\n",
    "\n",
    "To achieve 100% test coverage, we need to test both branches:\n",
    "    \n",
    "```python\n",
    "def test_do_something():\n",
    "    assert do_something(True) == 1\n",
    "    assert do_something(False) == 2\n",
    "```\n",
    "\n",
    "The code coverage is a good indicator of the quality of the tests, but can we feel safe if the test coverage is 100%?\n",
    "The answer is no.\n",
    "The test coverage only tells us that the code is executed during the tests.\n",
    "However, there might be external factors that are not taken into account by the tests.\n",
    "Consider a simple example of a function that returns the division of two numbers:\n",
    "\n",
    "```python\n",
    "def divide(a, b):\n",
    "    return a / b\n",
    "```\n",
    "\n",
    "It is easy to write a test for this function, keeping the code coverage at 100%.\n",
    "\n",
    "```python\n",
    "def test_divide():\n",
    "    assert divide(1, 2) == 0.5\n",
    "```\n",
    "\n",
    "However, this test does not take into account the case when the second argument is zero.\n",
    "Try to run the test with `divide(1, 0)` and see what happens.\n",
    "\n",
    "<div class=\"alert alert-block alert-warning\">\n",
    "<b>Remember:</b> 100% code coverage does not mean that the code is bug-free, remember to test edge cases.\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "26",
   "metadata": {},
   "source": [
    "# Documentation"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "27",
   "metadata": {},
   "source": [
    "## Why document?\n",
    "\n",
    "Let's face it, writing documentation is rarely anyone's favourite task.\n",
    "Nevertheless, it plays a crucial role in the overall package, guiding users to navigate and understand its functionalities.\n",
    "After all, without users, the package loses its purpose.\n",
    "\n",
    "For those aspiring to develop an open-source package, the significance of documentation is heightened.\n",
    "It serves as the initial point of contact for potential contributors upon opening the package.\n",
    "Open-source projects live and die with their community, so make sure to make the documentation as good as possible to attract people to your project."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "28",
   "metadata": {},
   "source": [
    "## How document?\n",
    "\n",
    "Usually, the documentation of a package is written in [reStructuredText](https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html) or [Markdown](https://www.sphinx-doc.org/en/master/usage/markdown.html).\n",
    "However, it is also possible to write the documentation in [Jupyter notebooks](https://jupyter.org/) (as we do in this tutorial).\n",
    "\n",
    "Further, we will consider different levels of documentation: starting from comments and ending with the documentation website."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "29",
   "metadata": {},
   "source": [
    "## Comments\n",
    "\n",
    "Comments are strings that are written in the code and are used to explain the code.\n",
    "In Python, comments start with `#` and end with the end of the line.\n",
    "For example:\n",
    "\n",
    "```python\n",
    "# This is a comment.\n",
    "```\n",
    "Comments can be helpful in the following cases:\n",
    "\n",
    "1. To describe what you plan to do.\n",
    "It is often helpful to write a comment before writing the code to keep track of what you are doing.\n",
    "```python\n",
    "# Step 1: Import the data.\n",
    "# Step 2: Clean the data.\n",
    "# Step 3: Train the model.\n",
    "# Step 4: Evaluate the model.\n",
    "```\n",
    "\n",
    "2. To describe what the code does.\n",
    "Often, even with your best effort, the code is not self-explanatory.\n",
    "In this case, it is better to write a comment that explains what the code does.\n",
    "```python\n",
    "# This part of the code is responsible for importing the data.\n",
    "with open(\"data.csv\", \"r\") as f:\n",
    "    data = f.read()\n",
    "```\n",
    "\n",
    "3. Describe or reference an algorithm.\n",
    "```python\n",
    "# This part of the code implements the Newton-Raphson method.\n",
    "...very-complex-code...\n",
    "```\n",
    "\n",
    "4. Tagging.\n",
    "```python\n",
    "\n",
    "# TODO: Revise this part of the code in the future.\n",
    "```\n",
    "\n",
    "However, well written code is often self-explanatory.\n",
    "Therefore, it is not always necessary to write comments.\n",
    "Better spend your time on writing good code than on writing good comments that explain bad code."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "30",
   "metadata": {},
   "source": [
    "## Docstrings\n",
    "\n",
    "Docstrings are strings that are written in the code and are used to document the code.\n",
    "Docstrings are used by the `help` function and are also used by the documentation generators to generate the documentation.\n",
    "In Python, docstrings are written in the following way:\n",
    "\n",
    "```python\n",
    "def calculate_area(radius):\n",
    "    \"\"\"Calculates the area of a circle.\n",
    "\n",
    "    Args:\n",
    "        radius (float): The radius of the circle.\n",
    "\n",
    "    Returns:\n",
    "        float: The area of the circle.\n",
    "\n",
    "    Raises:\n",
    "        ValueError: If the radius is negative.\n",
    "    \"\"\"\n",
    "    if radius < 0:\n",
    "        raise ValueError(\"Radius cannot be negative.\")\n",
    "    \n",
    "    area = 3.14 * radius**2\n",
    "    return area\n",
    "```\n",
    "\n",
    "In the example above, we have used the [Google style](https://github.com/google/styleguide/blob/gh-pages/pyguide.md#38-comments-and-docstrings) for docstrings.\n",
    "There are several other styles, you can look them up [here](https://note.nkmk.me/en/python-docstring/).\n",
    "We are not in a position to tell you which style to use, but we recommend to use the same style for all the docstrings in your package.\n",
    "In other words, be consistent.\n",
    "\n",
    "\n",
    "Let's play a bit with the example above."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "31",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "def calculate_area(radius):\n",
    "    \"\"\"Calculates the area of a circle.\n",
    "\n",
    "    Args:\n",
    "        radius (float): The radius of the circle.\n",
    "\n",
    "    Returns:\n",
    "        float: The area of the circle.\n",
    "\n",
    "    Raises:\n",
    "        ValueError: If the radius is negative.\n",
    "    \"\"\"\n",
    "    if radius < 0:\n",
    "        raise ValueError(\"Radius cannot be negative.\")\n",
    "    \n",
    "    area = 3.14 * radius**2\n",
    "    return area"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "32",
   "metadata": {},
   "source": [
    "To get the docstring of a function, you can put a question mark after the function name and run the cell:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "33",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "calculate_area?"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "34",
   "metadata": {},
   "source": [
    "Another option is to use the `help` function:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "35",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "help(calculate_area)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "36",
   "metadata": {},
   "source": [
    "The docstring is stored in the `__doc__` attribute of the function:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "37",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "print(calculate_area.__doc__)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "38",
   "metadata": {},
   "source": [
    "Therefore, changing the docstring is as easy as changing the value of the `__doc__` attribute:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "39",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "calculate_area.__doc__ = \"Calculates the area of a circle.\"\n",
    "calculate_area?"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "40",
   "metadata": {},
   "source": [
    "Docstrings can be used to document classes, methods, functions, and modules.\n",
    "To make sure the docstring is recognized by the documentation generators, it is recommended to follow the [PEP 257](https://www.python.org/dev/peps/pep-0257/) style guide.\n",
    "To say it in a few words, the docstring should start with a one-line summary, followed by an empty line, followed by a more detailed description.\n",
    "Docstrings are always put directly below the object they document."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "41",
   "metadata": {},
   "source": [
    "## Type hints\n",
    "\n",
    "Type hints are annotations that are used to specify the types of the variables.\n",
    "Type hints are used by the type checkers to check that the code is properly annotated.\n",
    "In addition, type hints are used by the documentation generators to generate the documentation.\n",
    "\n",
    "Therefore, instead of describing the types in the docstrings, we can use type hints.\n",
    "Let's rewrite the example above using type hints:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "42",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "def calculate_area(radius: float) -> float:\n",
    "    \"\"\"Calculates the area of a circle.\n",
    "\n",
    "    Args:\n",
    "        radius: The radius of the circle.\n",
    "\n",
    "    Returns:\n",
    "        The area of the circle.\n",
    "\n",
    "    Raises:\n",
    "        ValueError: If the radius is negative.\n",
    "    \"\"\"\n",
    "    if radius < 0:\n",
    "        raise ValueError(\"Radius cannot be negative.\")\n",
    "    \n",
    "    area = 3.14 * radius**2\n",
    "    return area"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "43",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "calculate_area?"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "44",
   "metadata": {},
   "source": [
    "In this case, the type information is present in the type hints, and the docstring focuses on providing additional context and information about the function, parameters, and return values."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "45",
   "metadata": {},
   "source": [
    "## Markdown\n",
    "\n",
    "So far we talked about the documentation that is written in the code.\n",
    "However, most of the time the documentation is written in a separate file.\n",
    "\n",
    "Usually, the documentation is written in [reStructuredText](https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html) or [Markdown](https://www.sphinx-doc.org/en/master/usage/markdown.html).\n",
    "We will focus on Markdown, as it is more popular and easier to use.\n",
    "For example, this tutorial is written in Markdown language.\n",
    "\n",
    "Here are some basic rules of Markdown:\n",
    "\n",
    "- Headers are created with `#` signs.\n",
    "More `#` signs mean smaller headers.\n",
    "\n",
    "- Lists are created with `-` or `*` signs.\n",
    "Indentation is used to create sub-lists.\n",
    "\n",
    "- Links are created with `[text](url)`.\n",
    "For example, [this link](https://www.markdownguide.org/basic-syntax/) points to the Markdown guide.\n",
    "\n",
    "- Images are created with `![alt text](url)`.\n",
    "For example, ![this](https://www.i2clipart.com/cliparts/4/d/e/5/1282254de556299e91214246aa0733b660a85d.png) is a cat image.\n",
    "\n",
    "- Code blocks are created with three backticks.\n",
    "For example:\n",
    "\n",
    "```python\n",
    "def square(x):\n",
    "    return x**2\n",
    "```\n",
    "\n",
    "- Math formulas are created with `$` signs.\n",
    "For example, the formula $x^2$ is created with `$x^2$`.\n",
    "\n",
    "Now that we know the basics of Markdown, let's see where they can be used."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "46",
   "metadata": {},
   "source": [
    "## README.md\n",
    "\n",
    "README is the first thing that a potential user sees when they open the package.\n",
    "Therefore, it is important to make it as good as possible.\n",
    "\n",
    "It is not common (though possible) to pack all the documentation into the README file.\n",
    "Usually, the README file contains the following information:\n",
    "\n",
    "- Logo.\n",
    "- Badges.\n",
    "- The name of the package.\n",
    "- The description of the package.\n",
    "- Quick installation instructions and links to the more detailed ones.\n",
    "- Quick usage instructions and links to the more detailed ones.\n",
    "- Links to the documentation and the source code.\n",
    "- Other useful links (contributing guide, code of conduct, etc.).\n",
    "- License information.\n",
    "- Contact information.\n",
    "- Acknowledgements.\n",
    "\n",
    "Have a look at the README files of the following packages and see how they are structured:\n",
    "\n",
    "- [numpy](https://github.com/numpy/numpy)\n",
    "- [AiiDA](https://github.com/aiidateam/aiida-core)\n",
    "- [scikit-learn](https://github.com/scikit-learn/scikit-learn)\n",
    "- [this tutorial](https://github.com/empa-scientific-it/python-tutorial) (yes, we also have a README file, give us a star!)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "47",
   "metadata": {},
   "source": [
    "## Exercise on README.md\n",
    "\n",
    "- Add a README file to your package and make sure it is properly displayed on GitHub."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "48",
   "metadata": {},
   "source": [
    "## GitHub wiki\n",
    "\n",
    "GitHub provides a free wiki for an open source project.\n",
    "It can be found under the `Wiki` tab of the repository.\n",
    "\n",
    "GitHub Wiki is usually a great place to kickstart a more serious documentation.\n",
    "It is easy to use and it is easy to collaborate on it.\n",
    "The only basic knowledge it requires is the knowledge of Markdown, which you have already acquired.\n",
    "\n",
    "To start using the GitHub Wiki, simply click on the `Wiki` tab and then on the `Create the first page` button.\n",
    "Then, you can start writing the documentation in Markdown.\n",
    "Keep in mind that all revisions of the file are stored in the repository.\n",
    "\n",
    "With time the GitHub Wiki might become too small for your documentation.\n",
    "The Wiki, however, will still be a good place to write on the internal development policies, provide quick how-to guides, etc.\n",
    "\n",
    "All-in-all consider wiki more for the live documentation which is updated frequently and is not too big.\n",
    "The more static (end established) documentation should be moved to a separate website, which we will discuss in the next section."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "49",
   "metadata": {},
   "source": [
    "## Read the Docs\n",
    "\n",
    "[Read the Docs](https://readthedocs.org/) is a service that hosts documentation for open source projects for free.\n",
    "If you decide to use Read the Docs, you will need to create an account and link it to your GitHub account.\n",
    "Then, you will need to create a new project and link it to your GitHub repository.\n",
    "Click on the \"Import a Project\" button and follow the instructions.\n",
    "Once your project is imported, you will need to configure it.\n",
    "\n",
    "At this point you need to decide which documentation generator you want to use.\n",
    "The most popular ones are [Sphinx](https://www.sphinx-doc.org/en/master/) and [MkDocs](https://www.mkdocs.org/).\n",
    "Jupyter Book is also gaining popularity, and it is supported by Read the Docs.\n",
    "The official documentation of Read the Docs provides [examples](https://docs.readthedocs.io/en/stable/examples.html) of how to configure the project for each of these documentation generators.\n",
    "\n",
    "We will focus on MkDocs as it is easier to use and provides most of the functionality that we need.\n",
    "Of course, you are free to use any other documentation generator at any point of time.\n",
    "The good thing is that the markdown files are compatible between different documentation generators, so you can easily switch between them."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "50",
   "metadata": {},
   "source": [
    "### Configuration\n",
    "\n",
    "To configure MkDocs, we need to create a `mkdocs.yml` file in the root of the repository.\n",
    "It can be as simple as:\n",
    "\n",
    "```yaml\n",
    "site_name: My package\n",
    "theme: readthedocs\n",
    "```\n",
    "\n",
    "For more information on the configuration, see [here](https://www.mkdocs.org/user-guide/configuration/)."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "51",
   "metadata": {},
   "source": [
    "### Writing the documentation\n",
    "\n",
    "Once the configuration is done, we need to create the documentation.\n",
    "The documentation is written in Markdown and is stored in the `docs` directory in the root of the repository.\n",
    "Usually, you start with a single Markdown file named `index.md` that contains the main page of the documentation.\n",
    "Then, you can create sub-pages and sub-directories to organize the documentation.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "52",
   "metadata": {},
   "source": [
    "### Building the documentation\n",
    "\n",
    "To launch the documentation server locally, run the following command:\n",
    "\n",
    "```bash\n",
    "mkdocs serve --dev-addr=0.0.0.0:8000\n",
    "```\n",
    "\n",
    "To access the locally deployed web-site follow this link: http://localhost:8000/."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "53",
   "metadata": {},
   "source": [
    "### Deploying on Read the Docs\n",
    "\n",
    "Once the documentation is ready, we can deploy it on Read the Docs.\n",
    "Add the `.readthedocs.yml` file to the root of the repository with the following content:\n",
    "\n",
    "```yaml\n",
    "# .readthedocs.yaml\n",
    "# Read the Docs configuration file\n",
    "# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details\n",
    "\n",
    "# Required\n",
    "version: 2\n",
    "\n",
    "# Set the version of Python and other tools you might need\n",
    "# build:\n",
    "#   os: ubuntu-22.04\n",
    "#   tools:\n",
    "#     python: \"3.10\"\n",
    "\n",
    "mkdocs:\n",
    "  configuration: mkdocs.yml\n",
    "\n",
    "# Optionally declare the Python requirements required to build your docs\n",
    "python:\n",
    "    install:\n",
    "        - method: pip\n",
    "          path: .\n",
    "          extra_requirements:\n",
    "              - docs\n",
    "```\n",
    "\n",
    "In the example above, we have used the `docs` extra dependencies specified in the `pyproject.toml` file.\n",
    "\n",
    "\n",
    "Once everything is set up, you need to commit and push the changes to GitHub.\n",
    "If everything is done correctly, the documentation will be automatically deployed on Read the Docs."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "54",
   "metadata": {},
   "source": [
    "# Releasing package\n",
    "\n",
    "Releasing a package is a process of making it available to the users.\n",
    "As far as the definition goes, the release can be as simple as uploading the package to GitHub.\n",
    "However, in practice, when we talk about a Python package release, we almost always mean releasing a package on [Python Package Index (PyPI)](https://pypi.org/).\n",
    "This chapter will cover the release process on PyPI accompanied by the release on GitHub."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "55",
   "metadata": {},
   "source": [
    "## Why release?\n",
    "\n",
    "When developing a package, you usually put your changes to the `main` branch of your repository.\n",
    "So, in principle, the users can install the package directly from the repository mentioning the branch or the commit hash:\n",
    "```bash\n",
    "pip install git+https://github.com/numpy/numpy@main # Install the latest version from the main branch.\n",
    "pip install git+hhttps://github.com/numpy/numpy@198f339c859d87e68dfe92c2a79429ac6e5074c1 # Install the version using the commit sha.\n",
    "```\n",
    "\n",
    "But this would be a nightmare for them, because they would need to read all the Git history and understand all the changes that were made.\n",
    "\n",
    "In essense, the whole release process is about communicating the changes to the users and simplifying the installation/update process.\n",
    "\n",
    "We want to:\n",
    "- Communicate that the new version is available.\n",
    "- List all the new features.\n",
    "- List things that are deprecated.\n",
    "- Communicate the licklehood of breaking changes that can cause troubles.\n",
    "- Streamline the install/update process.\n",
    "\n",
    "Let's break it down to the steps and see how we can achieve this."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "56",
   "metadata": {},
   "source": [
    "## Update the version\n",
    "\n",
    "The first thing we need to do is to update the version of the package.\n",
    "The version is usually stored in the `pyproject.toml` file as well as in the `__init__.py` file of the package.\n",
    "Once the version is updated, we need to commit and push the changes to GitHub:\n",
    "\n",
    "```bash\n",
    "git add pyproject.toml mypackage/__init__.py\n",
    "git commit -m \"Bump version to x.y.z\"\n",
    "git push\n",
    "```\n",
    "\n",
    "Next, we need to create a new Git tag for the previous commit and push it to GitHub:\n",
    "\n",
    "```bash\n",
    "git tag -a x.y.z -m \"Release x.y.z\"\n",
    "git push origin --tags\n",
    "```\n",
    "\n",
    "Once this is done, only the people who are subscribed to the repository will know that the new version is available.\n",
    "Now, the new version is available on GitHub and can be installed using the tag:\n",
    "    \n",
    "```bash\n",
    "pip install git+https://github.com/numpy/numpy@v1.26.2\n",
    "```\n",
    "\n",
    "However, there is a better way to communicate the new version to the users, which is the next step."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "57",
   "metadata": {},
   "source": [
    "## Python Package Index (PyPI)\n",
    "\n",
    "PyPI is a repository of software for the Python programming language.\n",
    "It is used by `pip` to install packages.\n",
    "Once a package is released on PyPI, it can be directly installed with `pip`:\n",
    "\n",
    "```bash\n",
    "pip install mypackage\n",
    "```\n",
    "\n",
    "To release a package on PyPI, we need to create an account on [PyPI](https://pypi.org/).\n",
    "Once the account is created, you can upload the package to PyPI using the `flit` tool (which can be installed with `pip`):\n",
    "\n",
    "```bash\n",
    "flit publish\n",
    "```\n",
    "<div class=\"alert alert-block alert-warning\">\n",
    "<b>Remember:</b> usually, you don't want to test things on PyPI.\n",
    "Therefore, make sure to test the release on the <a href=\"https://test.pypi.org/\">Test PyPI</a> first.\n",
    "Once you have registered there, you can upload the package to Test PyPI using the following command: <code>flit publish --repository https://test.pypi.org/legacy/</code>.\n",
    "</div>\n",
    "\n",
    "Once the package is uploaded to PyPI, it can be installed with `pip`:\n",
    "\n",
    "```bash\n",
    "pip install mypackage\n",
    "```\n",
    "\n",
    "<div class=\"alert alert-block alert-warning\">\n",
    "<b>Remember:</b> to upload the package to PyPI, you need to pick a unique name for it.\n",
    "Once the name is taken, it cannot be used by anyone else.\n",
    "Therefore, please think carefully about the name of your package.\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "58",
   "metadata": {},
   "source": [
    "## Changelog\n",
    "\n",
    "The changelog contains the list of changes made to the package.\n",
    "One can store the changelog in the `CHANGELOG.md` file in the root of the repository."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "59",
   "metadata": {},
   "source": [
    "### CHANGELOG.md\n",
    "\n",
    "The changelog is usually structured as follows:\n",
    "\n",
    "- The latest version is at the top.\n",
    "- Each version has a release date.\n",
    "- Each version has a list of changes.\n",
    "- Each change can be classified as `New feature`, `Bug fix`, `Breaking change`, `Deprecation`, `Documentation`, `Internal`, `Tests`, `Maintenance`, etc...\n",
    "- Each change has a description.\n",
    "\n",
    "Here is an example of a changelog taken from the [AiiDA package](https://github.com/aiidateam/aiida-core/blob/main/CHANGELOG.md).\n",
    "\n",
    "\n",
    "```markdown\n",
    "# Changelog\n",
    "\n",
    "## v2.4.1 - 2023-11-15\n",
    "\n",
    "This patch release comes with an improved set of Docker images and a few fixes to provide compatibility with recent versions of `pymatgen`.\n",
    "\n",
    "### Docker\n",
    "- Improved Docker images [[fec4e3bc4]](https://github.com/aiidateam/aiida-core/commit/fec4e3bc4dffd7d15b63e7ef0f306a8034ca3816)\n",
    "- Add folders that automatically run scripts before/after daemon start in Docker image [[fe4bc1d3d]](https://github.com/aiidateam/aiida-core/commit/fe4bc1d3d380686094021515baf31babf47388ac)\n",
    "- Pass environment variable to `aiida-prepare` script in Docker image [[ea47668ea]](https://github.com/aiidateam/aiida-core/commit/ea47668ea9b38581fbe1b6c72e133824043a8d38)\n",
    "- Update the `.devcontainer` to use the new docker stack [[413a0db65]](https://github.com/aiidateam/aiida-core/commit/413a0db65cb31156e6e794dac4f8d36e74b0b2cb)\n",
    "\n",
    "### Dependencies\n",
    "- Add compatibility for `pymatgen>=v2023.9.2` [[1f6027f06]](https://github.com/aiidateam/aiida-core/commit/1f6027f062a9eca5d8006741df91545d8ec01ed3)\n",
    "\n",
    "### Devops\n",
    "- Tests: Make `PsqlDosStorage` profile unload test more robust [[f392459bd]](https://github.com/aiidateam/aiida-core/commit/f392459bd417bec8a3ce184ee8f753649bcb77b8)\n",
    "- Tests: Fix `StructureData` test breaking for recent `pymatgen` versions [[093037d48]](https://github.com/aiidateam/aiida-core/commit/093037d48a2d92cbb6f068c1111fe1564a4500c0)\n",
    "- Trigger Docker image build when pushing to `support/*` branch [[5cf3d1d75]](https://github.com/aiidateam/aiida-core/commit/5cf3d1d75e8d22d6a3f0909c84aa63cc228bcf4b)\n",
    "- Use `aiida-core-base` image from `ghcr.io` [[0e5b1c747]](https://github.com/aiidateam/aiida-core/commit/0e5b1c7473030dd5b5027ea4eb0a658db9174091)\n",
    "- Loosen trigger conditions for Docker build CI workflow [[22e8a8069]](https://github.com/aiidateam/aiida-core/commit/22e8a80690747b792b70f96a0e332906f0e65e97)\n",
    "- Follow-up docker build runner macOS-ARM64 [[1bd9bf03d]](https://github.com/aiidateam/aiida-core/commit/1bd9bf03d19dda4c462728fb87cf4712b74c5f39)\n",
    "- Upload artifact by PR from forks for docker workflow [[afc2dad8a]](https://github.com/aiidateam/aiida-core/commit/afc2dad8a68e280f01e89fcb5b13e7a60c2fd072)\n",
    "- Update the image name for docker image [[17507b410]](https://github.com/aiidateam/aiida-core/commit/17507b4108b5dd1cd6e074b08e0bc2535bf0a164)\n",
    "```\n",
    "\n",
    "There are tools that help to automatically build a changelog of a Git repository.\n",
    "If you are interested, have a look at [git-cliff](https://github.com/orhun/git-cliff)."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "60",
   "metadata": {},
   "source": [
    "### GitHub releases\n",
    "\n",
    "An alternative to the `CHANGELOG.md` file is to use the [GitHub releases](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository).\n",
    "The GitHub release can be created from the existing Git tag.\n",
    "The GitHub release can contain the changelog, the list of contributors, and the list of issues and pull requests that were closed in this release.\n",
    "The GitHub release can also contain the pre-built binaries for different platforms.\n",
    "\n",
    "The advantage of the GitHub releases is that the changelog can be automatically generated from the Git history.\n",
    "For that one needs to make the new changes using the [pull requests](https://docs.github.com/en/repositories/collaborating-with-pull-requests/about-pull-requests).\n",
    "\n",
    "To make a new release, go to the `Releases` tab of the repository and click on the `Draft a new release` button.\n",
    "Then, select the tag that you want to release and fill in the information about the release:\n",
    "\n",
    "- Title is usually the version number, e.g. `v1.0.0`.\n",
    "- Description is usually the changelog that can be generated automatically from the Git history by clicking on the `Generate release notes` button.\n",
    "\n",
    "The automatically generated changelog might not be perfect, so make sure to review it before publishing the release.\n",
    "For instance, you might want to split the changes into different categories as one usually does in `CHANGELOG.md` files.\n",
    "\n",
    "Once you have reviewed the changelog, click on the `Publish release` button."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "61",
   "metadata": {},
   "source": [
    "# Automate things\n",
    "\n",
    "Most of the things that we have discussed in this tutorial can (and should) be automated.\n",
    "In this section we will discuss how to automate:\n",
    "\n",
    "- Testing\n",
    "- Version update\n",
    "- Releasing"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "62",
   "metadata": {},
   "source": [
    "## Testing\n",
    "\n",
    "Testing can be automated using [GitHub Actions](https://docs.github.com/en/actions).\n",
    "GitHub Actions are workflows that are triggered by certain events.\n",
    "For example, we can create a workflow that is triggered by a push event.\n",
    "This workflow will run the tests and report the result of the execution.\n",
    "\n",
    "To create a workflow, we need to create a `.github/workflows` directory in the root of the repository.\n",
    "Then, we need to create a `ci.yml` file with the following content:\n",
    "\n",
    "```yaml\n",
    "name: Continuous Integration\n",
    "\n",
    "on: push\n",
    "\n",
    "jobs:\n",
    "  tests:\n",
    "    name: Test Suite\n",
    "    runs-on: ubuntu-latest\n",
    "    timeout-minutes: 30\n",
    "\n",
    "    steps:\n",
    "\n",
    "      - name: Check out repository\n",
    "        uses: actions/checkout@v3\n",
    "\n",
    "      - name: Set up Python 3.11\n",
    "        uses: actions/setup-python@v4\n",
    "        with:\n",
    "          python-version: 3.11\n",
    "\n",
    "      - name: Install python dependencies\n",
    "        run: |\n",
    "          pip install --upgrade pip\n",
    "          pip install -e .[dev]\n",
    "\n",
    "      - name: Run test suite\n",
    "        run: pytest\n",
    "```\n",
    "\n",
    "In the example above, we have created a workflow that is triggered by a push event.\n",
    "The workflow runs on the latest version of Ubuntu.\n",
    "Then, it checks out the repository, sets up Python 3.11, installs the package with the development dependencies, and runs the test suite.\n",
    "\n",
    "If pytest finds any errors, the workflow will fail."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "63",
   "metadata": {},
   "source": [
    "## Exercise on testing automation\n",
    "\n",
    "- Create a GitHub Action workflow that runs the tests on every push.\n",
    "- Check that the workflow is triggered and all the tests pass."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "64",
   "metadata": {},
   "source": [
    "## Version update\n",
    "\n",
    "To automate the version update we can use [bumpver](https://github.com/mbarkhau/bumpver) tool.\n",
    "To install it, run the following command:\n",
    "\n",
    "```bash\n",
    "pip install bumpver\n",
    "```\n",
    "\n",
    "However, as usual, it is common to install `bumpver` as part of the development dependencies, see [above](#Optional-dependencies).\n",
    "\n",
    "Let's see how we usually configure `bumpver` in the `pyproject.toml` file:\n",
    "\n",
    "```toml\n",
    "[tool.bumpver]\n",
    "current_version = \"v0.2.3\"\n",
    "version_pattern = \"vMAJOR.MINOR.PATCH[PYTAGNUM]\"\n",
    "commit_message = \"Bump version {old_version} -> {new_version}.\"\n",
    "commit = true\n",
    "tag = true\n",
    "push = true\n",
    "\n",
    "[tool.bumpver.file_patterns]\n",
    "\"mypackage/__init__.py\" = [\n",
    "    '__version__ = \"{pep440_version}\"',\n",
    "]\n",
    "\"pyproject.toml\" = [\n",
    "    'version = \"{pep440_version}\"',\n",
    "]\n",
    "```\n",
    "\n",
    "In the setup above we have configured `bumpver` to update the version in the `__init__.py` file of the package and in the `pyproject.toml` file.\n",
    "The current version is `v0.2.3` and the version pattern is `vMAJOR.MINOR.PATCH[PYTAGNUM]`, which corresponds to the [semantic versioning](https://semver.org/) scheme.\n",
    "The commit message will be `Bump version {old_version} -> {new_version}.`.\n",
    "The git actions such as the commit, tag, and push will be performed automatically by `bumpver`.\n",
    "\n",
    "To update the version, run the following command:\n",
    "\n",
    "```bash\n",
    "bumpver update --minor --dry\n",
    "```\n",
    "Since the `--dry` flag is used, the version will not be updated, but the proposed changes will be printed to the console.\n",
    "In the example above we expect only the `MINOR` part of the version to be updated, as we have used the `--minor` flag.\n",
    "Once you are happy with the changes, remove the `--dry` flag and run the command again.\n",
    "\n",
    "\n",
    "For more information on the configuration, see [bumpver documentation](https://github.com/mbarkhau/bumpver#readme)."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "65",
   "metadata": {},
   "source": [
    "## Exercise on version update automation\n",
    "\n",
    "- Configure `bumpver` in your package.\n",
    "- Update the version of your package using `bumpver`.\n",
    "- Go to GitHub and check that the version is updated."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "66",
   "metadata": {},
   "source": [
    "## Releasing\n",
    "\n",
    "To automate the release process we will use [GitHub Actions](https://docs.github.com/en/actions).\n",
    "We already did big part of the work in the section above, when talking about version update.\n",
    "The only missing part is to set up GitHub's machinery to automate the release process on both GitHub and PyPI.\n",
    "\n",
    "Let's add a new file to the `.github/workflows` directory in the root of the repository.\n",
    "Let's call it `release.yml` and put the following content there:\n",
    "\n",
    "```yaml\n",
    "name: Release\n",
    "\n",
    "on:\n",
    "  push:\n",
    "    tags:\n",
    "      - v[0-9]+.[0-9]+.[0-9]+*\n",
    "```\n",
    "\n",
    "So we configured to run the workflow when a new tag is pushed to GitHub.\n",
    "The tag should match the semantic versioning scheme, e.g. `v1.0.0` or `v1.0.0-alpha.1`.\n",
    "\n",
    "Now, let's add the actions that we want to perform when the workflow is triggered.\n",
    "First, we need to checkout the repository:\n",
    "\n",
    "```yaml\n",
    "jobs:\n",
    "  release:\n",
    "    runs-on: ubuntu-latest\n",
    "    if: startsWith(github.ref, 'refs/tags/v')\n",
    "\n",
    "    steps:\n",
    "    - name: Checkout\n",
    "      uses: actions/checkout@v3\n",
    "```\n",
    "\n",
    "In the above, we trigger the workflow only when the tag starts with `v`.\n",
    "The first step is to checkout the repository.\n",
    "\n",
    "Then, we need to install the dependencies which include Python 3.11 and flit (which we will use to build the package):\n",
    "\n",
    "```yaml\n",
    "    - name: Set up Python 3.11\n",
    "      uses: actions/setup-python@v4\n",
    "      with:\n",
    "        python-version: 3.11\n",
    "\n",
    "    - name: Install flit\n",
    "      run: pip install flit~=3.4\n",
    "```\n",
    "\n",
    "Once the dependencies are installed, we can build and publish the package:\n",
    "\n",
    "```yaml\n",
    "    - name: Build and publish\n",
    "      run: flit publish\n",
    "      env:\n",
    "        FLIT_USERNAME: __token__\n",
    "        FLIT_PASSWORD: ${{ secrets.PYPI_TOKEN }}\n",
    "```\n",
    "\n",
    "The secret token is used to authenticate on PyPI.\n",
    "It can be generated on the [PyPI website](https://pypi.org/manage/account/token/).\n",
    "Once the token is generated, it can be added to the repository secrets under the name `PYPI_TOKEN`.\n",
    "To add the secret, go to the `Settings` tab of the repository, then to the `Secrets and variables` tab, and choose `Actions`.\n",
    "Then, click on the `New repository secret` button and add the token generated on the PyPI website.\n",
    "\n",
    "\n",
    "Finally, we want to add a release to GitHub.\n",
    "```yaml\n",
    "    - name: Create release\n",
    "      uses: softprops/action-gh-release@v0.1.14\n",
    "      with:\n",
    "          files: |\n",
    "              dist/*\n",
    "          generate_release_notes: true\n",
    "```\n",
    "\n",
    "Once everything is done, and the workflow is configured, we can commit and push the changes to GitHub.\n",
    "  \n",
    "If everything is done correctly, the workflow will be triggered by a new tag.\n",
    "It is enough to run:\n",
    "  \n",
    "```bash\n",
    "bumpver update --minor\n",
    "```\n",
    "\n",
    "To trigger the full release machinery."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "67",
   "metadata": {},
   "source": [
    "## Exercises on releasing automation\n",
    "\n",
    "- Configure the release workflow in your package.\n",
    "You can use all steps from the example above except from the `Build and publish` step.\n",
    "This step should be replaced with the following one:\n",
    "\n",
    "```yaml\n",
    "    - name: Build and publish\n",
    "      run: flit build\n",
    "```\n",
    "- Update the version of your package using `bumpver`.\n",
    "\n",
    "**Optional:**\n",
    "\n",
    "- Only if you are working with your own package, you can try to release it on PyPI."
   ]
  }
 ],
 "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.11.1"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}