Automated Changelog/release note generation

Documatic

Last update: Jan 3, 2023

Related tags

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.

Comments

Does not recognise git on windows
Describe the bug Doculog uses the python package subprocess to run git under the hood to collect commits. This works fine for linux (i believe macOS as well), but fails with windows because subprocess cannot find.

We have introduced a function to get git from path, but that does not seem to work either (https://github.com/DocumaticAI/doculog/blob/master/doculog/git.py#L13). We have tried setting shell=True, but that also doesn't seem to work Can someone please confirm the above?

To Reproduce Steps to reproduce the behavior:

Be on a windows machine

Run `subprocess.check_output["git", "log"])

This will fail with a FileNotFoundError

Expected behavior We should be able to get git logs on windows!

A fix to this issue will update doculog/git.py to work on windows and non-windows with the same functionality

Screenshots None

System:

OS: windows

Doculog: all

Additional context N/A
:bug: bug :fire: priority: high
opened by TTitcombe 16
Format code

Simple PR to format code with black and isort. Necessary because a PR from an external contributor did not pass the linting check, but the merge was high priority so easier to bypass lint check and open this PR

opened by TTitcombe 0
Improve API key error messaging
This PR:*

Prints the error message from a 403 API call

Sets the validation request content type to application/json

No particular reason, but doing this just in case it's an os specific issue with a different default content type

Related to #25
opened by TTitcombe 0
Support DOCUMATIC_API_KEY environment variable

Documatic's other documentation tools (email [email protected] for info!) use DOCUMATIC_API_KEY environment variable to set api keys. This PR combines api keys and streamlines usage of multiple tools by allowing doculog to consume DOCUMATIC_API_KEY vars. Also deprecates use of DOCULOG_API_KEY, which is to be removed in 0.2.0

opened by TTitcombe 0
Make api process clearer in README
Updates README:

Link to imperitive mood git commit style

Explain git tagging/version process for changelogs

Make API acquisition process a bit clearer
opened by TTitcombe 0
Fix empty unreleased section updates (date bug)

The "unreleased" section gets commits from the date of the last release to some date in the future. This used to be 2100-12-31, but for some reason this began to yield empty git logs. Therefore, this future date was changed to 2099-01-01, which seems to work. This is a temporary workaround and should be fixed properly separate to this PR.

opened by TTitcombe 0
Hotfix - Handle non-git project gracefully
Doculog was generating an error if run on a project without git. This PR:

Creates a simple function to check if git enabled

Does not generate or save a changelog if git not enabled

Slightly Improves test coverage of git functionality

Bumps Doculog patch version
opened by TTitcombe 0
Initial Changelog functionality
This PR:

Adds CI checks

Adds unit tests

Adds basic Changelog structure

Adds config parsing code

Validates API key before use

Sends unclassified commits to server
opened by TTitcombe 0
False Incorrect API key message

Describe the bug Some users are reporting getting an invalid API key message, but I've checked their key and it is valid. The first confirmed reportee was windows, but I'm not sure if it's an OS-specific issue.

If this happens to you, please comment below with your system information (do not post your api key)

To Reproduce Steps to reproduce the behavior: N/A. Not easily reproducible as "incorrect" keys work when I try them.

Expected behavior All valid API keys are recognised as valid
:bug: bug

opened by TTitcombe 0
Mock git behaviour in unit testing

Functionality of doculog relies on git. This makes it difficult to unit test because git cannot, as far as I know, easily have its behaviour altered/mocked for unit tests. It is possible to mock the responses to subprocess calls (which invoke git), but this requires the test writer to create a string of git log/diff output and isn't scalable.

We need to find a way to mock git behaviour for unit testing. I.e. start a git repo local to that test / test suite, easily add commits and tags.
help wanted :gear: test

opened by TTitcombe 2
Empty Git log with certain future dates
Describe the bug The "Unreleased" section gets git commits in a date range between the last version tag and some future date. The future date used to be 2100-12-31, but this began to yield empty commits for some reason. To circumvent this issue, #17 changed the date to 2099-01-01, which seems to work. On limited testing, only some future dates in 2100-01-DD work.

To Reproduce Steps to reproduce the behavior:

Run git log --since 2021-12-30 --until 2100-12-31 This should not yield anything

Run git log --since 2021-12-30 --until 2099-01-01. This should yield commits

Expected behavior All the commits since the --since date should be returned. Perhaps the Unreleased section should be updated so it only calls git log with a --since tag but no --until tag. Either that or discover what the issue with git log dates is.

Screenshots N/A

System:

OS: ubuntu 20.04

Python version: 3.8

Doculog version: 0.1.4

Additional context N/A
:bug: bug help wanted
opened by TTitcombe 0
Categorise commits in merge collectively

Is your feature request related to a problem? Please describe. Sometimes (often) it takes several commits to make one complete feature change. as doculog currently works, this create false positive/duplicate features in the changelog. doculog should interpret

Describe the solution you'd like A clear and concise description of what you want to happen.

Describe alternatives you've considered None

Additional context N/A
:raising_hand: feature request

opened by TTitcombe 0
Contents section for releases

Is your feature request related to a problem? Please describe. For changelogs with lots of releases, it would be useful to have an overview of releases in the form on a contents at the top of the document.

Describe the solution you'd like Add a contents section, with each release as a new entry. Release entries should be of the form - <VERSION> - <DATE, just like their headers. Clicking a release entry jumps you to the relevant release section.

Describe alternatives you've considered None

Additional context N/A
:raising_hand: feature request

opened by TTitcombe 0