Setuptools extension to help generate change logs
This project is a setuptools extension which helps to generate change logs from fragments. This way of changelog management is conflict free, what is extremely helpful for PR/MR driven workflow.
Python 2.7, 3.5+;
setuptools (31+, but the latest release is better);
Your project follows Semantic Versioning or uses it simplified (X.Y version) form;
Add setuptools-changelog as development dependency to your project;
Create changelog.d directory in your project root directory (where setup.py is located)
Create there fragments files according the changes you made. Fragments files have the following format:
name: fragment name. If it starts with a number and you have issue tracker specified, this number will turn into issue reference automatically. Otherwise there could be just some mnemonic name to simplify navigation.
type: fragment type. By default, the following types are available
epic: Massive epic change that completely changes underlying project platform. This could be a shift to completely new base library, framework, etc. Epic changes are very rare and are the reason for major release.
breaking: Breaking change means changes in the project public API which makes old code incompatible with them. Incompatibility means that things were removed or their behavior had changed.
security: This is an important security fix. Users must update ASAP. If security fix causes breaking change, two separate changelog fragments should be issued.
deprecation: Deprecations are friendly warnings about upcoming breaking changes in the public API.
feature: New features brings something to project and they must be available for users via public API.
bug: When something works in the way it’s not expected or supposed to we do a bug fix.
improvement: This could be speed optimizations, internals refactoring, making code more stable etc. Improvements are never changes the existed behaviour or public API.
build: Changes, related to project build routines, packaging, etc.
doc: Documentation updates, clarifications, typo fixes, etc.
test: Work around project testing, test suite, CI, etc.
misc: Misc changes which doesn’t suites any existed category. For instance, they could be announcements about project life: new committers, endorsements, etc.
ext: file extension. Currently, we support only rst one.
You can always preview changelog via:
python setup.py changelog
Once you’ll be ready for release, you can update your changelog file like:
python setup.py changelog --update=CHANGELOG.rst
This command will prepend generated changelog to your file.
Review your changelog file content and everything is fine commit it and remove fragments:
git rm changelog.d/* git commit CHANGELOG.rst changelog.d/
Example configuration for setup.cfg using defaults:
[changelog] changelog_fragments_path = changelog.d major_changes_types = epic = Epic Changes breaking = Breaking Changes removal = Breaking Changes minor_changes_types = security = Security Fixes deprecation = Deprecations feature = New Features patch_changes_types = bug = Bug Fixes bugfix = Bug Fixes improvement = Improvements build = Build doc = Documentation test = Tests Suite misc = Miscellaneous
Automatic version generation
If your project follows Semantic Versioning strategy, you can achieve not just changelog generation, but also automatic version management depending on changes it has.
Integration with towncrier
This project was started because there are several reasons for me to not use towncrier for changelog management. But
Why have enemies, when you can have?
—King Arthur: Legend of the Sword
Instead, we can support fragments, made for towncrier with the following config:
[changelog] changelog_fragments_path = changelog.d major_changes_types = removal = Breaking Changes minor_changes_types = feature = New Features patch_changes_types = bugfix = Bug Fixes doc = Documentation misc = Miscellaneous use_towncrier = true
And that’s it!
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Hashes for setuptools-changelog-1.0.0.tar.gz
Hashes for setuptools_changelog-1.0.0-py3-none-any.whl