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
Canim1 - Simple python tool to search for packages without m1 wheels in poetry lockfiles

canim1 Usage Clone the repo. Run poetry install. Then you can use the tool: ❯ po

Korijn van Golen 1 Jan 25, 2022
A full-featured, hackable tiling window manager written and configured in Python

A full-featured, hackable tiling window manager written and configured in Python Features Simple, small and extensible. It's easy to write your own la

Qtile 3.8k Dec 31, 2022
A log likelihood fit for extracting neutrino oscillation parameters

A-log-likelihood-fit-for-extracting-neutrino-oscillation-parameters Minimised the negative log-likelihood fit to extract neutrino oscillation paramete

Vid Homsak 1 Jan 23, 2022
Scrapper For Paste.pics

PrntScScrapper Scrapper for Paste.pics If you are bored you can find some random screenshots from prnt.sc Features Saving screenshots Open in Browser

Fareusz 1 Dec 29, 2021
【幼盾】个性化图片徽章服务!

【幼盾】个性化图片徽章服务! 你对方形的徽章感到无聊了吗?想要定制属于自己的开源项目徽章了吗? 快来使用unv-shield吧! unv-shield提供包含自定义图片的徽章服务,可以让你的项目主页更加个性化!

黄巍 130 Dec 23, 2022
Python script which allows for automatic registration in Golfbox

Python script which allows for automatic registration in Golfbox

Guðni Þór Björnsson 8 Dec 04, 2021
Xoroshiro-cairo - A xoroshiro128** pseudorandom number generator implementation in Cairo

xoroshiro-cairo A xoroshiro128** pseudorandom number generator implementation in

Milan Cermak 26 Oct 05, 2022
AdventOfCode 2021 solutions from the Devcord server

adventofcode-21 Ein Sammel-Repository für Advent of Code 2021-Lösungen der deutschen DevCord-Community. A repository collecting Advent of Code 2021 so

Devcord 12 Aug 26, 2022
Insert a Spotify Playlist, Get a list of YouTube URLs from it.

spotbee This is a module that spits out YouTube URLs from Spotify Playlist URLs Why use this? It is asynchronous which makes it compatible to use with

Nishant Sapkota 10 Apr 06, 2022
This is the Quiz that I made using Python Programming Language. This can only run in the Terminal

This is the Quiz that I made using Python Programming Language. This can only run in the Terminal

YOSHITHA RATHNAYAKE 1 Apr 08, 2022
ASCII-Wordle - A port of the game Wordle to terminal emulators/CMD

ASCII-Wordle A 'port' of Wordle to text-based interfaces A near-feature complete

32 Jun 11, 2022
The Open edX platform, the software that powers edX!

This is the core repository of the Open edX software. It includes the LMS (student-facing, delivering courseware), and Studio (course authoring) compo

edX 6.2k Jan 01, 2023
Powerful virtual assistant in python

Virtual assistant in python Powerful virtual assistant in python Set up Step 1: download repo and unzip Step 2: pip install requirements.txt (if py au

Arkal 3 Jan 23, 2022
Add any Program in any language you like or add a hello world Program ❣️ if you like give us :star:

Welcome to the Hacktoberfest 2018 Hello-world 📋 This Project aims to help you to get started with using Github. You can find a tutorial here What is

Aniket Sharma 1.5k Nov 16, 2022
Turn crypto miner on/off depending on powerwall charge level

Mining Crypto with Tesla Solar and Powerwalls This script turns a crypto miner on and off when the Tesla Powerwall level drops/rises above a certain t

Matt 1 Nov 09, 2021
This is an example manipulation package of for a robot manipulator based on Drake with ROS2.

This is an example manipulation package of for a robot manipulator based on Drake with ROS2.

Sotaro Katayama 1 Oct 21, 2021
Launcher program to select which version of the Q-Sys software to launch.

QSC-QSYS Launcher Launcher program to select which version of the Q-Sys software to launch. Instructions To use the application simply save the "Q-Sys

Zach Lisko 2 Sep 28, 2022
Werkzeug has a debug console that requires a pin. It's possible to bypass this with an LFI vulnerability or use it as a local privilege escalation vector.

Werkzeug Debug Console Pin Bypass Werkzeug has a debug console that requires a pin by default. It's possible to bypass this with an LFI vulnerability

Wyatt Dahlenburg 23 Dec 17, 2022
Set up a sidechain for the XRPL quickly and easily

Sidechain Launch Kit Introduction This directory contains python scripts to tests and explore side chains. This document walks through the steps to se

Xpring Engineering 15 Dec 08, 2022
Choice Coin 633 Dec 23, 2022