Automated Changelog/release note generation

Overview

doculog

README generated with Documatic.

Quickly generate changelogs and release notes by analysing your git history. A tool written in python, but works on any language. Once installed, simply run

doculog

in a terminal in a git-enabled project directory, and a changelog will be generated. For advanced changelog generation, you can use the Documatic API.

Getting started

Requirements

  • python >= 3.8
  • git
  • "good" commit messages
  • Git version tags

Minimum python 3.8. Project actively supports python 3.8, 3.9, 3.10. To install, clone the repository and run pip install -e . to package locally OR pip install doculog.

Doculog works by reading git commit messages and inferring what changes are being made. It assumes that you are writing your commit messages as actions: e.g. "Add some feature", "Fix a particular bug". While it's good practice to have the action in the present, imperitive tense, doculog accepts past verbs. See git best practices for more information on this git commit writing style. Standard doculog looks through a list of expected verbs (open an issue/contribute a PR if there are some missing!), but the extended version includes additional logic for classifying commit message, which allows you to be more lax with your commit messages.

API key

To generate a changelog with a full feature-set, doculog requires a (free) API key. Join the waitlist for an API key by signing up here. Someone will be in touch with your API key. In the meantime, doculog works without an API key (you just won't have access to advanced features).

doculog uses python-dotenv to load environment variables stored in a .env file. To use your API key, create a .env file in your project root directory with the following fields:

DOCUMATIC_API_KEY = 
   

   

IMPORTANT: DO NOT ADD .env TO VERSION CONTROL. YOUR API KEY MUST BE KEPT SECRET.

Generate a Changelog

In a terminal, run doculog to create a CHANGELOG.md from your git commit history, or update an existing changelog. The "Unreleased" section corresponds to updates not attached to a version. Each changelog update version may contain the following sections: "Added", "Removed", "Deprecated", "Fixed", "Changed". Each section header will only appear in the version if it has at least one update. Note: doculog will overwrite changes made to the "Unreleased" section every time it is run, however tagged versions are not overwritten. Therefore, you can manually edit and add updates to a version release.

To get the best out of the changelog, read the concepts below for information on configuration, git commits and version tags.

Concepts

Git commit parsing

The initial logic for generating a changelog comes from reading your git commit messages. doculog expects commit messages to begin with an imperitive verb, and to written passively. doculog parses the message for signalling words and phrases.

E.g. Rename 'my_func' to 'my_awesome_func' will get interpreted as a "Changed" feature. Whereas 'my_func' -> 'my_awesome_func' will not.

Version tags

Changelogs break down your project's featureset by each release. Currently, doculog infers a release has been made by reading the git tags of your project. If you don't have any git tags, your changelog will only have an "Unreleased" section. To make a git tag, run git tag -a v - - (and git push --tags to push to your remote); This assumes you're using semver versioning system.

Note: not using semver or git tags to release your project? Open an issue on the doculog repo detailing your method to get it supported by doculog.

Configuration

You can configure how doculog runs by adding a tool.doculog section to pyproject.toml.

Field Purpose Required Default value
changelog Name of changelog file generated. ".md" suffix added if not present. No CHANGELOG.md
project The name of your project. Used to title the changelog No The name of your root project folder
local If true, use a local sever for advanced features. Only used for project development No false

For example, your pyproject.toml file might be:

[tool.doculog]
changelog = "CHANGELOG"
project = "My Cool Project"

Developers

Read the contributing guide for information on coding styles and workflow.

Run pip install -r requirements-dev.txt to get developer requirements.

CI file Purpose
test.yml Linting and unit testing. Runs on every pull request

FAQ

I want more intelligent featureset generation. What can I do?

Request access to the free Documatic API to generate a changelog driven by machine learning. Follow Documatic on GitHub and socials to stay up to date with the latest features and releases.

How do I get my API key?

Once you've joined the waitlist, we will be in touch shortly with your API key.

The changelog is great, but I want more!

Get in touch - [email protected].

I'm not getting a complete changelog. What's gone wrong?

Check that you have appropriate version tags and commit messages. If you have the advanced featureset (i.e. have an API key) then you will get better changelog updates which don't require you to follow the commit process so strictly. If you're still not getting good results, please open a bug report.

Can I contribute to doculog?

Absolutely: feature requests, bug fixes, bug reports and PRs of all shapes and sizes are welcome. See the developers section.

License

Licensed under GNU GPL3. Please see the [LICENSE] for terms in full.

Generated by Documatic.

Owner
Documatic
Documatic
A Python simple Dice Simulator just for fun

Dice Simulator 🎲 A Simple Python Dice Simulator 🧩 🎮 💭 Description: That program make your RPG session more easy and simple. Roll the dice never be

Lauro Brant 17 May 14, 2022
Beancount Importers for DKB (Deutsche Kredit Bank) CSV Exports

Beancount DKB Importer beancount-dkb provides an Importer for converting CSV exports of DKB (Deutsche Kreditbank) account summaries to the Beancount f

Siddhant Goel 24 Aug 06, 2022
Generate Azure Blob Storage account authentication headers for Munki

Azure Blob Storage Authentication for Munki The Azure Blob Storage Middleware allows munki clients to connect securely, and directly to a munki repo h

Oliver Kieselbach 10 Apr 12, 2022
A fast python implementation of DTU MVS 2014 evaluation

DTUeval-python A python implementation of DTU MVS 2014 evaluation. It only takes 1min for each mesh evaluation. And the gap between the two implementa

82 Dec 27, 2022
Online HackerRank problem solving challenges

LinkedListHackerRank Online HackerRank problem solving challenges This challenge is part of a tutorial track by MyCodeSchool You are given the pointer

Sefineh Tesfa 1 Nov 21, 2021
本仓库整理了腾讯视频、爱奇艺、优酷、哔哩哔哩等视频网站中,能够观看的「豆瓣电影 Top250 榜单」影片。

Where is top 250 movie ? 本仓库整理了腾讯视频、爱奇艺、优酷、哔哩哔哩等视频网站中,能够观看的「豆瓣电影 Top250 榜单」影片,点击 Badge 可跳转至相应的电影首页。

MayanDev 123 Dec 22, 2022
Password manager using MySQL and Python 3.10.2

Password Manager Password manager using MySQL and Python 3.10.2 Installation Install my-project with github git clone https://github.com/AyaanSiddiq

1 Feb 18, 2022
Python Function to manage users via SCIM

Python Function to manage users via SCIM This script helps you to manage your v2 users. You can add and delete users or groups, add users to groups an

4 Oct 11, 2022
IPO Checker for NEPSE

IPO Checker Checks more than one account for an IPO. Usage: ipo_checker.py [-h] --file FILE IPO Checker for a list. optional arguments: -h, --help

Sagar Tamang 4 Sep 20, 2022
A library for pattern matching on symbolic expressions in Python.

MatchPy is a library for pattern matching on symbolic expressions in Python. Work in progress Installation MatchPy is available via PyPI, and

High-Performance and Automatic Computing 151 Dec 24, 2022
This python module allows to extract data from the RAW-file-format produces by devices from Thermo Fisher Scientific.

fisher_py This Python module allows access to Thermo Orbitrap raw mass spectrometer files. Using this library makes it possible to automate the analys

8 Oct 14, 2022
Basic infrastructure for writing scripts in Python

Base Script Python is an excellent language that makes writing scripts very straightforward. Over the course of writing many scripts, we realized that

Deep Compute, LLC 9 Jan 07, 2023
Pyrmanent - Make all your classes permanent in a flash 💾

Pyrmanent A base class to make your Python classes permanent in a flash. Features Easy to use. Great compatibility. No database needed. Ask for new fe

Sergio Abad 4 Jan 07, 2022
An useful scripts for Misskey

misskey-scripts This place storing useful scripts which made by me. icon-repair Repair broken remote user's icon.

CyberRex 5 Sep 09, 2022
A module to prevent invites and joins to Matrix rooms by checking the involved server(s)' domain.

Synapse Domain Rule Checker A module to prevent invites and joins to Matrix rooms by checking the involved server(s)' domain. Installation From the vi

matrix.org 4 Oct 24, 2022
Hello, Welcome to this repo. don't forget to read guidelines in readme.md

Hacktoberfest_2021 If you looking for your first contribution, we are here to help. Just create a simple program using any language you like in our fo

Wafa Rifqi Anafin 117 Dec 14, 2022
Entitlement AND Hardened Runtime Check

Python3 script for macOS to recursively check /Applications and also check /usr/local/bin, /usr/bin, and /usr/sbin for binaries with problematic/interesting entitlements. Also checks for hardened run

Cedric Owens 79 Nov 16, 2022
Demo of patching a python context manager

patch-demo-20211203 demo of patching a python context manager poetry install poetry run python -m my_great_app to run the code poetry run pytest to te

Brad Smith 1 Feb 09, 2022
HungryBall to prosta gra, w której gracz wciela się w piłkę.

README POLSKI Opis gry HungryBall to prosta gra, w której gracz wciela się w piłkę. Sterowanie odbywa się za pomocą przycisków w, a, s i d lub opcjona

Karol 1 Nov 24, 2021
Scalene: a high-performance, high-precision CPU, GPU, and memory profiler for Python

Scalene: a high-performance CPU, GPU and memory profiler for Python by Emery Berger, Sam Stern, and Juan Altmayer Pizzorno. Scalene community Slack Ab

PLASMA @ UMass 7k Dec 30, 2022