Package: doculog
doculogREADME generated withDocumatic.Quickly generate changelogs
and release notes
by analysing your git history.
A tool written in python,
but works on any language.
Once installed,
simply rundoculogin a terminal
in a git-enabled
project directory,
and a changelog will be generated.
For advanced changelog generation,
you can use theDocumatic API.Getting startedRequirementspython >= 3.8git"good" commit messagesGit version tagsMinimum python 3.8.
Project actively supports python 3.8,
3.9,
3.10.
To install,
clone the repository
and runpip install -e .to package locally
ORpip install doculog.Doculogworks 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. "Addsome feature",
"Fixa particular bug".
While it's good practice to have the action
in the present,
imperitive tense,doculogaccepts past verbs.
Seegit best practicesfor more information
on this git commit writing style.
Standarddoculoglooks through a list
of expected verbs
(open an issue/contribute a PR if there are some missing!),
but theextended versionincludes additional logic
for classifying commit message,
which allows you to be more lax
with your commit messages.API keyTo generate a changelog
with a full feature-set,
doculog requires a (free)
API key.
Join the waitlist
for an API key
by signing uphere.
Someone will be in touch with your API key.
In the meantime,
doculogworks without an API key(you just won't have access to advanced features).doculogusespython-dotenvto load environment variables
stored in a.envfile.
To use your API key,
create a.envfile
in your project root directory
with the following fields:DOCUMATIC_API_KEY = <your-api-key>IMPORTANT: DO NOT ADD.envTO VERSION CONTROL.
YOUR API KEY MUST BE KEPT SECRET.Generate a ChangelogIn a terminal,
rundoculogto create
aCHANGELOG.mdfrom 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:doculogwill 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 onconfiguration,git commitsandversion tags.ConceptsGit commit parsingThe initial logic for generating a changelog
comes from reading
your git commit messages.doculogexpects
commit messages to begin with an imperitive verb,
and to written passively.doculogparses 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 tagsChangelogs break down your project's featureset
by each release.
Currently,doculoginfers 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,
rungit tag -a v<MAJOR>-<MINOR>-<PATCH>(andgit push --tagsto push to your remote);
This assumes you're usingsemverversioning system.Note:not using semver or git tags to release your project?
Open an issue on thedoculogrepo
detailing your method to get it supported
bydoculog.ConfigurationYou can configure howdoculogruns
by adding atool.doculogsection
topyproject.toml.FieldPurposeRequiredDefault valuechangelogName of changelog file generated. ".md" suffix added if not present.NoCHANGELOG.mdprojectThe name of your project. Used to title the changelogNoThe name of your root project folderlocalIftrue, use a local sever for advanced features. Only used for project developmentNofalseFor example,
yourpyproject.tomlfilemightbe:[tool.doculog]
changelog = "CHANGELOG"
project = "My Cool Project"DevelopersRead thecontributing guidefor information on coding styles
and workflow.Runpip install -r requirements-dev.txtto get developer requirements.CI filePurposetest.ymlLinting and unit testing. Runs on every pull requestFAQI want more intelligent featureset generation. What can I do?Request access to the free Documatic API
to generate a changelog
driven by machine learning.
FollowDocumaticon 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 -info@documatic.com.I'm not getting a complete changelog. What's gone wrong?Check that you have appropriateversion tagsandcommit 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 thedeveloperssection.LicenseLicensed under GNU GPL3.
Please see the [LICENSE]
for terms in full.Generated byDocumatic.