brainelectronics / changelog2version

Update version info file with latest changelog version entry

Changelog2version

Update version info file with latest changelog version entry

---

General

Create version info files based on the latest changelog entry.

• Installation
• Usage
  • Available default template files
    • C header file
    • Python package file
    • JSON output
      • Console
      • File
  • Validate generated file
• Advanced
  • Custom regular expressions
  • Custom template file
  • Additional version info content
• Contributing
  • Unittests
• Credits

Installation

pip install changelog2version

Usage

This example shows you how to parse the repo's changelog and update the package version file with that version.

changelog2version \
    --changelog_file changelog.md \
    --version_file examples/version.py \
    --debug

Available default template files

By default a Python version file is generated. Check the table below and the example usage for further details and supported template files

Type	Parameter	Description
Python	py	See example package version
C/CPP	c	Header file with available version info

C header file

changelog2version \
    --changelog_file changelog.md \
    --version_file examples/version_info.h \
    --version_file_type c \
    --debug

//
//  version_info.h
//
//  Created automatically by script
//

#ifndef version_info_h
#define version_info_h

#define MAJOR_VERSION   0     //< major software version
#define MINOR_VERSION   4     //< minor software version
#define PATCH_VERSION   0     //< patch software version

#endif

Python package file

changelog2version \
    --changelog_file changelog.md \
    --version_file examples/version.py \
    --version_file_type py \
    --debug

#!/usr/bin/env python3
# -*- coding: UTF-8 -*-

__version_info__ = ("0", "4", "0")
__version__ = '.'.join(__version_info__)

JSON output

The additional, optional argument --pretty will output the JSON data with an indentation of 4 in order to provide the data in an easy to read format.

Console

changelog2version \
    --changelog_file changelog.md \
    --print \
    --debug

{"info": {"version": "0.7.0", "description": "### Added\n- Changelog parsed as JSON contains a new key `description` like the PyPi package JSON info, compare to `https://pypi.org/pypi/changelog2version/json`, with the description/content of the latest change, see #19, relates to #18\n- Increase unittest coverage above 95%\n\n### Changed\n- Line breaks are no longer used in this changelog for enumerations\n- Issues are referenced as `#123` instead of `[#123][ref-issue-123]` to avoid explicit references at the bottom or some other location in the file\n- Output of `changelog2version` call with `--print` but without `--debug` option is JSON compatible\n"}, "releases": {"0.7.0": [{"upload_time": "2022-11-11"}], "0.6.0": [{"upload_time": "2022-10-26"}], "0.5.0": [{"upload_time": "2022-10-20"}], "0.4.0": [{"upload_time": "2022-08-07"}], "0.3.0": [{"upload_time": "2022-08-05"}], "0.2.0": [{"upload_time": "2022-08-03"}], "0.1.1": [{"upload_time": "2022-07-31"}], "0.1.0": [{"upload_time": "2022-07-31"}]}}

To get the latest version and description in the console as environment variables use the following call

LATEST_VERSION=$(changelog2version --changelog_file changelog.md --print | python -c "import sys, json; print(json.load(sys.stdin)['info']['version'])")
LATEST_CHANGE=$(changelog2version --changelog_file changelog.md --print | python -c "import sys, json; print(json.load(sys.stdin)['info']['description'])")

echo "The latest version extracted from the changelog is ${LATEST_VERSION}"
# The latest version extracted from the changelog is 0.7.0

echo "Description of the latest change"
echo "${LATEST_CHANGE}"
# ### Added
# - Changelog parsed as JSON contains a new key `description` like the PyPi package JSON info, compare to `https://pyp
# i.org/pypi/changelog2version/json`, with the description/content of the latest change, see #19, relates to #18
# - Increase unittest coverage above 95%

# ### Changed
# - Line breaks are no longer used in this changelog for enumerations
# - Issues are referenced as `#123` instead of `[#123][ref-issue-123]` to avoid explicit references at the bottom or s
# ome other location in the file
# - Output of `changelog2version` call with `--print` but without `--debug` option is JSON compatible

File

changelog2version \
    --changelog_file changelog.md \
    --output changelog.json \
    --pretty \
    --debug

See example JSON file

Validate generated file

To validate an already generated version file agains the latest available changelog the --validate option can be used.

The following command will exit with a non-zero code in case of a difference between the generated version file (examples/version.py) and the latest changelog content.

changelog2version \
    --changelog_file changelog.md \
    --version_file examples/version.py \
    --validate \
    --debug

By default a Python version file is assumed, for a C header version file the call has to be extended with the version_file_type option

changelog2version \
    --changelog_file changelog.md \
    --version_file examples/version_info.h \
    --version_file_type c \
    --validate \
    --debug

Advanced

Custom regular expressions

To extract a version line from a given changelog file with an alternative regex, the version_line_regex argument can be used as shown below. The expression is validated during the CLI argument parsing

changelog2version \
    --changelog_file changelog.md \
    --version_file src/changelog2version/version.py \
    --version_line_regex "^\#\# \[\d{1,}[.]\d{1,}[.]\d{1,}\]" \
    --debug

Same applies for a custom semver line regex in order to extract the semantic version part from a full version line, use the semver_line_regex argument to adjust the regular expression to your needs.

Custom template file

Beside the default supported template files users can also provide custom template files.

This is the list of currently available variables

Name	Description
major_version	Major version, incompatible API changes
minor_version	Minor version, add functionality (backwards-compatible)
patch_version	Patch version, bug fixes (backwards-compatible)
prerelease_data	pre-release data, if available
build_data	Build metadata, if available
file_name	User specified name of rendered file
file_name_without_suffix	User specified name of rendered file without suffix
template_name	Name of rendered template file
template_name_without_suffix	Name of rendered template file without suffix
Custom keyword	Provided by the user via --additional_template_data

additional_data="{\"creation_datetime\": \"$(date +"%Y-%m-%dT%H:%M:%S")\", \"machine_name\": \"$(whoami)\"}"
changelog2version \
    --changelog_file changelog.md \
    --version_file examples/version_info.c \
    --template_file examples/version_info.c.template \
    --additional_template_data "${additional_data}" \
    --debug

# or less fancy
changelog2version \
    --changelog_file changelog.md \
    --version_file examples/version_info.c \
    --template_file examples/version_info.c.template \
    --additional_template_data '{"creation_datetime": "2022-08-05T21:11:12", "machine_name": "Death Star"}' \
    --debug

Executing the created example file examples/version_info.c will print the following content (datetime and creator might be different)

Script version is (major.minor.patch): 0.4.0
Prerelease data: None
Prerelease data: None
Creation datetime: 2022-08-05T21:11:12
Created by Death Star

Additional version info content

To create custom release candidate packages the python version file variable __version__ can be exended with a custom string.

Choose the additional version info content carefully as not everything is supported by PyPi, see the Python Core metadata specifications and PEP440

changelog2version \
    --changelog_file changelog.md \
    --version_file examples/version.py \
    --version_file_type py \
    --additional_version_info="rc1234" \
    --debug

#!/usr/bin/env python3
# -*- coding: UTF-8 -*-

__version_info__ = ("0", "5", "0")
__version__ = '.'.join(__version_info__) + '-rc1234'

Contributing

Unittests

Run the unittests locally with the following command after installing this package in a virtual environment or by using tox to create one on each run.

# install the package with all its development dependencies
pip install .[dev]

# run all tests
nose2 --config tests/unittest.cfg

# run only one specific tests
nose2 tests.test_extract_version.TestExtractVersion.test_version_line_regex

Generate the coverage files with

python create_report_dirs.py
coverage html

The coverage report is placed at reports/coverage/html/index.html

Credits

Based on the PyPa sample project. Also a big thank you to the creators and maintainers of SemVer.org for their documentation and regex example

changelog2version's Issues

Parse Changelog to JSON

Extract all Changelog versions and dump the result into a JSON file or to stdout if no file is specified.

Output should be similar to https://pypi.org/pypi/PACKAGENAME/json

Create test release on every PR push

The same version that is released to Test PyPi should be available as tag on the repo. The release shall be labeled as "pre-release"

Use full semver regex

Extend the version line regex and the semver line to support the full semver content including buildmeta data, prerelease and so on.

See SemVer Regex101 example

"^(?P<major>0|[1-9]\d*)\.(?P<minor>0|[1-9]\d*)\.(?P<patch>0|[1-9]\d*)(?:-(?P<prerelease>(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+(?P<buildmetadata>[0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$"gm

Provide description of latest change in JSON file

Required by #18

The parsed JSON file should contain a new key description with the content of the latest changes being made.

{
    "info": {
        "version": "0.7.0",
        "description": "### Added\n- As JSON parsed changelog contains a new key `description` as the PyPi ..."
    },
    "releases": {
        "0.7.0": [
            {
                "upload_time": "2022-11-11"
            }
        ]
    }
}

Release action uses invalid changelog parsing command

https://github.com/brainelectronics/changelog2version2/blob/0c2fff7ab55f2e5c3e33629bd3a86becee1873ba/.github/workflows/release.yml#L33

change to
changelog2version \

Split coverage into extra workflow

Split the unit test with nose2 and coverage Generation with coverage from existing Workflows and run it on every brach as a separate workflow on a single python version

Render version file from template

Render (any) version file from a (user given) template file

• allow custom template files as CLI argument
• render other templates with all available infos
• provide list of available keywords for custom templates

Add support for additional version information text

As required by Issue 5 of micropython-package-template additional version informations should be attachable to the version file during rendering.

Add option --additional_version_info to the changelog2version script to render the python version file like the following example if called with --additional_version_info="-rc1234"
The version has to follow Python Core metadata specifications and PEP440

#!/usr/bin/env python3
# -*- coding: UTF-8 -*-

__version_info__ = ("0", "1", "1")
__version__ = '.'.join(__version_info__) + '-rc1234'

Add coverage badge to README

Show the unittest coverage of the package in the root README file

Convert update_version to class

Create class ExtractVersion to get the release version line and its semver.

• add properties for both regex
• add two new CLI parameters to provide regex

Allow setting of logger level

Logging level can't be set to something different than DEBUG, see

changelog2version/src/changelog2version/update_version.py

Line 169 in d846e61

logger.setLevel(logging.DEBUG)

if --debug is used. Otherwise INFO is set as level.

Additionally the version of changelog2version can't be requested.