# Changelog2version
[](https://pepy.tech/project/changelog2version)
[](https://opensource.org/licenses/MIT)
[](https://app.codecov.io/github/brainelectronics/changelog2version)
Update version info file with latest changelog version entry
---------------
## General
Create version info files based on the latest changelog entry.
<!-- MarkdownTOC -->
- [Installation](#installation)
- [Usage](#usage)
- [Available default template files](#available-default-template-files)
- [C header file](#c-header-file)
- [Python package file](#python-package-file)
- [JSON output](#json-output)
- [Console](#console)
- [File](#file)
- [Validate generated file](#validate-generated-file)
- [Advanced](#advanced)
- [Custom regular expressions](#custom-regular-expressions)
- [Custom template file](#custom-template-file)
- [Additional version info content](#additional-version-info-content)
- [Contributing](#contributing)
- [Unittests](#unittests)
- [Credits](#credits)
<!-- /MarkdownTOC -->
## Installation
```bash
pip install changelog2version
```
## Usage
This example shows you how to parse the [repo's changelog](changelog.md) and
update the [package version file][ref-package-version-file] with that
version.
```bash
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][ref-package-version-file] |
| C/CPP | `c` | Header file with available version info |
#### C header file
```bash
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
```bash
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
```bash
changelog2version \
--changelog_file changelog.md \
--print \
--debug
```
```json
{"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
```bash
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
```bash
changelog2version \
--changelog_file changelog.md \
--output changelog.json \
--pretty \
--debug
```
See [example JSON file][ref-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.
```bash
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
```bash
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
```bash
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][ref-templates-folder] 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` |
```bash
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][ref-py-core-metadata-spec] and
[PEP440][ref-pep440]
```bash
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.
```bash
# 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
```bash
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][ref-pypa-sample]. Also a big thank you to
the creators and maintainers of [SemVer.org][ref-semver] for their
documentation and [regex example][ref-semver-regex-example]
<!-- Links -->
[ref-package-version-file]: src/changelog2version/version.py
[ref-templates-folder]: src/changelog2version/templates
[ref-example-json-file]: examples/changelog.json
[ref-py-core-metadata-spec]: https://packaging.python.org/specifications/core-metadat
[ref-pep440]: https://peps.python.org/pep-0440/
[ref-pypa-sample]: https://github.com/pypa/sampleproject
[ref-semver]: https://semver.org/
[ref-semver-regex-example]: https://regex101.com/r/Ly7O1x/3/
Raw data
{
"_id": null,
"home_page": "https://github.com/brainelectronics/changelog2version",
"name": "changelog2version",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7, <4",
"maintainer_email": "",
"keywords": "changelog,version,changelog-parser,versioning,extract",
"author": "brainelectronics",
"author_email": "info@brainelectronics.de",
"download_url": "https://files.pythonhosted.org/packages/a5/05/f8c95bb28e7ae31ff858a1341519665569e02c5712ef2464a27d1068fd67/changelog2version-0.10.0.tar.gz",
"platform": null,
"description": "# Changelog2version\n\n[](https://pepy.tech/project/changelog2version)\n\n\n[](https://opensource.org/licenses/MIT)\n[](https://app.codecov.io/github/brainelectronics/changelog2version)\n\nUpdate version info file with latest changelog version entry\n\n---------------\n\n## General\n\nCreate version info files based on the latest changelog entry.\n\n<!-- MarkdownTOC -->\n\n- [Installation](#installation)\n- [Usage](#usage)\n - [Available default template files](#available-default-template-files)\n - [C header file](#c-header-file)\n - [Python package file](#python-package-file)\n - [JSON output](#json-output)\n - [Console](#console)\n - [File](#file)\n - [Validate generated file](#validate-generated-file)\n- [Advanced](#advanced)\n - [Custom regular expressions](#custom-regular-expressions)\n - [Custom template file](#custom-template-file)\n - [Additional version info content](#additional-version-info-content)\n- [Contributing](#contributing)\n - [Unittests](#unittests)\n- [Credits](#credits)\n\n<!-- /MarkdownTOC -->\n\n\n## Installation\n\n```bash\npip install changelog2version\n```\n\n## Usage\n\nThis example shows you how to parse the [repo's changelog](changelog.md) and\nupdate the [package version file][ref-package-version-file] with that\nversion.\n\n```bash\nchangelog2version \\\n --changelog_file changelog.md \\\n --version_file examples/version.py \\\n --debug\n```\n\n### Available default template files\n\nBy default a Python version file is generated. Check the table below and the\nexample usage for further details and supported template files\n\n| Type | Parameter | Description |\n| ------ | --------- | ----------- |\n| Python | `py` | See [example package version][ref-package-version-file] |\n| C/CPP | `c` | Header file with available version info |\n\n#### C header file\n\n```bash\nchangelog2version \\\n --changelog_file changelog.md \\\n --version_file examples/version_info.h \\\n --version_file_type c \\\n --debug\n```\n\n```\n//\n// version_info.h\n//\n// Created automatically by script\n//\n\n#ifndef version_info_h\n#define version_info_h\n\n#define MAJOR_VERSION 0 //< major software version\n#define MINOR_VERSION 4 //< minor software version\n#define PATCH_VERSION 0 //< patch software version\n\n#endif\n```\n\n#### Python package file\n\n```bash\nchangelog2version \\\n --changelog_file changelog.md \\\n --version_file examples/version.py \\\n --version_file_type py \\\n --debug\n```\n\n```\n#!/usr/bin/env python3\n# -*- coding: UTF-8 -*-\n\n__version_info__ = (\"0\", \"4\", \"0\")\n__version__ = '.'.join(__version_info__)\n\n```\n\n#### JSON output\n\nThe additional, optional argument `--pretty` will output the JSON data with an\nindentation of 4 in order to provide the data in an easy to read format.\n\n##### Console\n\n```bash\nchangelog2version \\\n --changelog_file changelog.md \\\n --print \\\n --debug\n```\n\n```json\n{\"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\"}]}}\n```\n\nTo get the latest version and description in the console as environment\nvariables use the following call\n\n```bash\nLATEST_VERSION=$(changelog2version --changelog_file changelog.md --print | python -c \"import sys, json; print(json.load(sys.stdin)['info']['version'])\")\nLATEST_CHANGE=$(changelog2version --changelog_file changelog.md --print | python -c \"import sys, json; print(json.load(sys.stdin)['info']['description'])\")\n\necho \"The latest version extracted from the changelog is ${LATEST_VERSION}\"\n# The latest version extracted from the changelog is 0.7.0\n\necho \"Description of the latest change\"\necho \"${LATEST_CHANGE}\"\n# ### Added\n# - Changelog parsed as JSON contains a new key `description` like the PyPi package JSON info, compare to `https://pyp\n# i.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 s\n# ome other location in the file\n# - Output of `changelog2version` call with `--print` but without `--debug` option is JSON compatible\n```\n\n##### File\n\n```bash\nchangelog2version \\\n --changelog_file changelog.md \\\n --output changelog.json \\\n --pretty \\\n --debug\n```\n\nSee [example JSON file][ref-example-json-file]\n\n### Validate generated file\n\nTo validate an already generated version file agains the latest available\nchangelog the `--validate` option can be used.\n\nThe following command will exit with a non-zero code in case of a difference\nbetween the generated version file (`examples/version.py`) and the latest\nchangelog content.\n\n```bash\nchangelog2version \\\n --changelog_file changelog.md \\\n --version_file examples/version.py \\\n --validate \\\n --debug\n```\n\nBy default a Python version file is assumed, for a C header version file the\ncall has to be extended with the `version_file_type` option\n\n```bash\nchangelog2version \\\n --changelog_file changelog.md \\\n --version_file examples/version_info.h \\\n --version_file_type c \\\n --validate \\\n --debug\n```\n\n## Advanced\n\n### Custom regular expressions\n\nTo extract a version line from a given changelog file with an alternative\nregex, the `version_line_regex` argument can be used as shown below. The\nexpression is validated during the CLI argument parsing\n\n```bash\nchangelog2version \\\n --changelog_file changelog.md \\\n --version_file src/changelog2version/version.py \\\n --version_line_regex \"^\\#\\# \\[\\d{1,}[.]\\d{1,}[.]\\d{1,}\\]\" \\\n --debug\n```\n\nSame applies for a custom semver line regex in order to extract the semantic\nversion part from a full version line, use the `semver_line_regex` argument to\nadjust the regular expression to your needs.\n\n### Custom template file\n\nBeside the default supported [template files][ref-templates-folder] users can\nalso provide custom template files.\n\nThis is the list of currently available variables\n\n| Name | Description |\n| ----------------------------- | --------------------------------------------------------- |\n| `major_version` | Major version, incompatible API changes |\n| `minor_version` | Minor version, add functionality (backwards-compatible) |\n| `patch_version` | Patch version, bug fixes (backwards-compatible) |\n| `prerelease_data` | pre-release data, if available |\n| `build_data` | Build metadata, if available |\n| `file_name` | User specified name of rendered file |\n| `file_name_without_suffix` | User specified name of rendered file without suffix |\n| `template_name` | Name of rendered template file |\n| `template_name_without_suffix`| Name of rendered template file without suffix |\n| Custom keyword | Provided by the user via `--additional_template_data` |\n\n```bash\nadditional_data=\"{\\\"creation_datetime\\\": \\\"$(date +\"%Y-%m-%dT%H:%M:%S\")\\\", \\\"machine_name\\\": \\\"$(whoami)\\\"}\"\nchangelog2version \\\n --changelog_file changelog.md \\\n --version_file examples/version_info.c \\\n --template_file examples/version_info.c.template \\\n --additional_template_data \"${additional_data}\" \\\n --debug\n\n# or less fancy\nchangelog2version \\\n --changelog_file changelog.md \\\n --version_file examples/version_info.c \\\n --template_file examples/version_info.c.template \\\n --additional_template_data '{\"creation_datetime\": \"2022-08-05T21:11:12\", \"machine_name\": \"Death Star\"}' \\\n --debug\n```\n\nExecuting the created example file `examples/version_info.c` will print the\nfollowing content (datetime and creator might be different)\n\n```\nScript version is (major.minor.patch): 0.4.0\nPrerelease data: None\nPrerelease data: None\nCreation datetime: 2022-08-05T21:11:12\nCreated by Death Star\n```\n\n### Additional version info content\n\nTo create custom release candidate packages the python version file variable\n`__version__` can be exended with a custom string.\n\nChoose the additional version info content carefully as not everything is\nsupported by PyPi, see the\n[Python Core metadata specifications][ref-py-core-metadata-spec] and\n[PEP440][ref-pep440]\n\n```bash\nchangelog2version \\\n --changelog_file changelog.md \\\n --version_file examples/version.py \\\n --version_file_type py \\\n --additional_version_info=\"rc1234\" \\\n --debug\n```\n\n```\n#!/usr/bin/env python3\n# -*- coding: UTF-8 -*-\n\n__version_info__ = (\"0\", \"5\", \"0\")\n__version__ = '.'.join(__version_info__) + '-rc1234'\n\n```\n\n## Contributing\n\n### Unittests\n\nRun the unittests locally with the following command after installing this\npackage in a virtual environment or by using `tox` to create one on each run.\n\n```bash\n# install the package with all its development dependencies\npip install .[dev]\n\n# run all tests\nnose2 --config tests/unittest.cfg\n\n# run only one specific tests\nnose2 tests.test_extract_version.TestExtractVersion.test_version_line_regex\n```\n\nGenerate the coverage files with\n\n```bash\npython create_report_dirs.py\ncoverage html\n```\n\nThe coverage report is placed at `reports/coverage/html/index.html`\n\n## Credits\n\nBased on the [PyPa sample project][ref-pypa-sample]. Also a big thank you to\nthe creators and maintainers of [SemVer.org][ref-semver] for their\ndocumentation and [regex example][ref-semver-regex-example]\n\n<!-- Links -->\n[ref-package-version-file]: src/changelog2version/version.py\n[ref-templates-folder]: src/changelog2version/templates\n[ref-example-json-file]: examples/changelog.json\n[ref-py-core-metadata-spec]: https://packaging.python.org/specifications/core-metadat\n[ref-pep440]: https://peps.python.org/pep-0440/\n[ref-pypa-sample]: https://github.com/pypa/sampleproject\n[ref-semver]: https://semver.org/\n[ref-semver-regex-example]: https://regex101.com/r/Ly7O1x/3/\n",
"bugtrack_url": null,
"license": "",
"summary": "Update version info file with latest changelog version entry",
"version": "0.10.0",
"project_urls": {
"Bug Reports": "https://github.com/brainelectronics/changelog2version/issues",
"Homepage": "https://github.com/brainelectronics/changelog2version",
"Source": "https://github.com/brainelectronics/changelog2version/"
},
"split_keywords": [
"changelog",
"version",
"changelog-parser",
"versioning",
"extract"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7f350d1cfa790f1522c1fc536b3c675be0eb298389880986cd744d9d1d600595",
"md5": "093001b652406af63e0d6bb0eb8ad23f",
"sha256": "b6388815415a1bae6101458bef46754420f1ae4b4666ddf53a55fd8d1307823e"
},
"downloads": -1,
"filename": "changelog2version-0.10.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "093001b652406af63e0d6bb0eb8ad23f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7, <4",
"size": 15231,
"upload_time": "2023-07-08T08:57:05",
"upload_time_iso_8601": "2023-07-08T08:57:05.188190Z",
"url": "https://files.pythonhosted.org/packages/7f/35/0d1cfa790f1522c1fc536b3c675be0eb298389880986cd744d9d1d600595/changelog2version-0.10.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a505f8c95bb28e7ae31ff858a1341519665569e02c5712ef2464a27d1068fd67",
"md5": "af693fcf4fc38ae09b927857b112dfe1",
"sha256": "1652564cead72d5d71aaf8866e6a39faa57d7e8ea6c6684537da253c07afe54e"
},
"downloads": -1,
"filename": "changelog2version-0.10.0.tar.gz",
"has_sig": false,
"md5_digest": "af693fcf4fc38ae09b927857b112dfe1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7, <4",
"size": 23217,
"upload_time": "2023-07-08T08:57:06",
"upload_time_iso_8601": "2023-07-08T08:57:06.802693Z",
"url": "https://files.pythonhosted.org/packages/a5/05/f8c95bb28e7ae31ff858a1341519665569e02c5712ef2464a27d1068fd67/changelog2version-0.10.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-07-08 08:57:06",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "brainelectronics",
"github_project": "changelog2version",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"requirements": [],
"tox": true,
"lcname": "changelog2version"
}
JSON
