{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#hide\n",
    "from fastrelease import *"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# fastrelease\n",
    "\n",
    "> Auto-generated tagged releases, and release notes (from GitHub issues)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`fastrelease` provides two commands that you can run from your shell:\n",
    "\n",
    "- `nbdev_changelog`: creates a CHANGELOG.md file from closed and labeled GitHub issues\n",
    "- `nbdev_tag_release`: tags and creates a release in GitHub for the current version."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Install"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`fastrelease` has no prerequisites and will run on Python 3.4 or later. You can install from pip:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`pip install fastrelease`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "...or conda:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`conda install -c fastai fastrelease`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## How to use"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Set up"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "First, create a `settings.ini` file with the following contents (replacing the values as described below):\n",
    "\n",
    "```\n",
    "[DEFAULT]\n",
    "lib_name = fastrelease\n",
    "user = fastai\n",
    "version = 0.0.1\n",
    "```\n",
    "\n",
    "Set `lib_name` to the name of GitHub repo, `user` to the owner of that repo, and `version` to the version number of your library. (Note that if you use [nbdev](https://nbdev.fast.ai) then you'll already have this information, so you don't need to do anything further to set it up.)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You'll need to get a GitHub [personal access token](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token) if you haven't already. To do so, [click here](https://github.com/settings/tokens/new) and enter \"fastrelease\" in the \"Note\" section, and click the `repo` checkbox.\n",
    "\n",
    "Then click \"Generate Token\" at the bottom of the screen, and copy the token (the long string of letters and numbers shown). You can easily do that by clicking the little clipboard icon next to the token.\n",
    "\n",
    "<img alt=\"Copying your token\" width=\"743\" caption=\"Copying your token\" src=\"images/att_00001.png\">\n",
    "\n",
    "Paste that token into a file called `token` into the root of your repo. You can run the following in your terminal (`cd` to the root of your repo first) to create that file:\n",
    "\n",
    "    echo XXX > token\n",
    "\n",
    "Replace *XXX* above with the token you copied. Also, ensure that this file isn't added to git, by running this in your terminal:\n",
    "\n",
    "    echo token >> .gitignore"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Creating release notes"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now you're ready to create your release notes. These are created in a file called `CHANGELOG.md`. Here's an example of what it creates: [nbdev CHANGELOG](https://github.com/fastai/nbdev/blob/master/CHANGELOG.md).\n",
    "\n",
    "All issues with the label **bug**, **enhancement**, or **breaking** that have been closed in your repo since your last release will be added to the top of this file. If you haven't made any releases before, then all issues with those labels will be included.\n",
    "\n",
    "Therefore, before you create or update `CHANGELOG.md`, go to your GitHub issues page, remove `is:open` from the filter, and label any issues you want included with one of the labels above. When you've done that, you can create or update your release notes by running in your terminal:\n",
    "\n",
    "    fastrelease_changelog"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The titles and bodies of each issue will be added. Open `CHANGELOG.md` in your editor and make any edits that you want, and then commit the file to your repo (remember to `git add` it!)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Tagging a release"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It's important that you now tag a release. This will create a tag in GitHub with your current version number in `settings.ini`, and will then make it into a release:\n",
    "\n",
    "    fastrelease_release\n",
    "\n",
    "After you run this, be sure to increment your version number in `settings.ini`. You can either edit it manually, or if you use nbdev it can be done for you by running:\n",
    "\n",
    "    nbdev_bump_version"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}