| Name | chlog JSON |
| Version |
0.8.0
JSON |
| download |
| home_page | None |
| Summary | Keep changelogs the easy way |
| upload_time | 2023-04-18 15:28:13 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9,<4 |
| license | None |
| keywords |
cli
console
changelog
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# chlog
## TL;DR
1. Maintains changelog files in Markdown format.
1. Does not overwrite your manual edits.
1. Helps you comply with
[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
1. Adheres to [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
by default.
1. Can be configured to support other changelog templates.
## Usage
When you commit a (set of) software modification(s) that users of the project should know about, add a corresponding change note, phrased to be meaningful to the users of the project, to your CHANGELOG.md file. Examples:
```sh
% chlog added "Export to PDF."
% chlog fixed "File -> Save As no longer overwrites files without a warning."
% chlog changed "Improved the error handling during imports."
% chlog changed --breaking "Configuration files now use the TOML format."
% chlog deprecated "The foobar feature will be removed in v2.0.0."
% chlog removed "INI files are no longer supported."
% chlog security "In certain conditions an attacker might discover user data."
```
`chlog freeze` replaces "## [Unreleased]" with a version number and the current date. It suggests the new version number based on the content of the Unreleased section and the rules of [Semantic Versioning](https://semver.org/spec/v2.0.0.html). You can accept or reject that number.
`chlog freeze 2.0.0` applies the version number provided.
`chlog print` renders the Markdown in the changelog file to the terminal. It's beautiful.
Instead of "added", "fixed", "removed", and "freeze", you can say "new", "fix", "rm", and "tag".
## Using chlog versus maintaining the changelog in an editor
There is no conflict here. Round trips between command line use and manual modifications in a text editor are safe. `chlog` only ever changes the Unreleased section of the changelog. It does not even look at what comes before and after it. It is also safe to add, remove, reorder, or rephrase change notes which were added to the Unreleased section via the command line. In rare cases, `chlog` might change white space but it will not otherwise overwrite or reformat your work.
## chlog and changelogs not created by itself
If your existing changelog already conforms to the [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) template, `chlog` will simply load it and add change notes to it. If your existing changelog uses a different template, `chlog` will be unable to recognize the types of changes that are recorded in it. If, for instance, the changelog says "### New Features" instead of "### Added", change notes created with `chlog added` will appear under "### Added". The imported "### New Features" section will be appended to the end of the Unreleased section. However, you can customize chlog to support your project's changelog template.
## Customization
`chlog` can be adapted to support a variety of projects. This is done via `[tool.chlog]` tables in TOML files. For example:
```toml
[tool.chlog]
chlog-filename = "CHANGELOG.md"
```
determines the file name to use for the changelog. The table array `[[tool.chlog.commands]]` can be used to redefine existing commands and change note types. For example, projects which use "### New Features" instead of "### Added" include the statement
```toml
[[tool.chlog.commands]]
command = "added"
heading = "New Features"
```
To define an entirely new command and change note type, include something like
```toml
[[tool.chlog.commands]]
command = "breaking"
heading = "Breaking Changes"
insert-before = 3
help = "record a breaking change in the changelog"
description='''
Records breaking changes in the Unreleased section of the changelog.
'''
```
in the TOML configuration file. That will allow to issue `chlog breaking "A change note."` commands and insert a "### Breaking Changes" section into the changelog.
To customize `chlog` in this way, a Python project would add the tool.chlog tables to its `pyproject.toml`. Other projects use `chlog.toml` or `.chlog`.
TODO: Document this in more detail.
## Planned for the next version
Expand issue numbers in new change notes. For example
`chlog fixed "Fixed the line-too-long bug issue#1234."`
adds
`- Fixed the line-too-long bug [#1234](<issues-url>/1234).`
to the changelog. For this to work, the TOML config must specify the issues URL e.g.
```toml
[project.urls]
Issues = "https://github.com/myaccount/myproject/issues/"
```
or
```toml
[tool.chlog.urls]
issues = "https://github.com/myaccount/myproject/issues/"
```
Raw data
{
"_id": null,
"home_page": null,
"name": "chlog",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9,<4",
"maintainer_email": null,
"keywords": "cli,console,changelog",
"author": null,
"author_email": "Ralf Luetkemeier <foss@rlue.de>",
"download_url": "https://files.pythonhosted.org/packages/24/aa/e396b00283a6a3ee30f8ae1d441d2ef6b360488b18f2af8e55f6a93ccb76/chlog-0.8.0.tar.gz",
"platform": null,
"description": "# chlog\n\n## TL;DR\n\n1. Maintains changelog files in Markdown format.\n1. Does not overwrite your manual edits.\n1. Helps you comply with\n [Semantic Versioning](https://semver.org/spec/v2.0.0.html).\n1. Adheres to [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)\n by default.\n1. Can be configured to support other changelog templates.\n\n## Usage\n\nWhen you commit a (set of) software modification(s) that users of the project should know about, add a corresponding change note, phrased to be meaningful to the users of the project, to your CHANGELOG.md file. Examples:\n\n```sh\n% chlog added \"Export to PDF.\"\n% chlog fixed \"File -> Save As no longer overwrites files without a warning.\"\n% chlog changed \"Improved the error handling during imports.\"\n% chlog changed --breaking \"Configuration files now use the TOML format.\"\n% chlog deprecated \"The foobar feature will be removed in v2.0.0.\"\n% chlog removed \"INI files are no longer supported.\"\n% chlog security \"In certain conditions an attacker might discover user data.\"\n```\n\n`chlog freeze` replaces \"## [Unreleased]\" with a version number and the current date. It suggests the new version number based on the content of the Unreleased section and the rules of [Semantic Versioning](https://semver.org/spec/v2.0.0.html). You can accept or reject that number.\n\n`chlog freeze 2.0.0` applies the version number provided.\n\n`chlog print` renders the Markdown in the changelog file to the terminal. It's beautiful.\n\nInstead of \"added\", \"fixed\", \"removed\", and \"freeze\", you can say \"new\", \"fix\", \"rm\", and \"tag\".\n\n## Using chlog versus maintaining the changelog in an editor\n\nThere is no conflict here. Round trips between command line use and manual modifications in a text editor are safe. `chlog` only ever changes the Unreleased section of the changelog. It does not even look at what comes before and after it. It is also safe to add, remove, reorder, or rephrase change notes which were added to the Unreleased section via the command line. In rare cases, `chlog` might change white space but it will not otherwise overwrite or reformat your work.\n\n## chlog and changelogs not created by itself\n\nIf your existing changelog already conforms to the [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) template, `chlog` will simply load it and add change notes to it. If your existing changelog uses a different template, `chlog` will be unable to recognize the types of changes that are recorded in it. If, for instance, the changelog says \"### New Features\" instead of \"### Added\", change notes created with `chlog added` will appear under \"### Added\". The imported \"### New Features\" section will be appended to the end of the Unreleased section. However, you can customize chlog to support your project's changelog template.\n\n## Customization\n\n`chlog` can be adapted to support a variety of projects. This is done via `[tool.chlog]` tables in TOML files. For example:\n\n```toml\n[tool.chlog]\nchlog-filename = \"CHANGELOG.md\"\n```\n\ndetermines the file name to use for the changelog. The table array `[[tool.chlog.commands]]` can be used to redefine existing commands and change note types. For example, projects which use \"### New Features\" instead of \"### Added\" include the statement\n\n```toml\n[[tool.chlog.commands]]\ncommand = \"added\"\nheading = \"New Features\"\n```\n\nTo define an entirely new command and change note type, include something like\n\n```toml\n[[tool.chlog.commands]]\ncommand = \"breaking\"\nheading = \"Breaking Changes\"\ninsert-before = 3\nhelp = \"record a breaking change in the changelog\"\ndescription='''\n Records breaking changes in the Unreleased section of the changelog.\n'''\n```\n\nin the TOML configuration file. That will allow to issue `chlog breaking \"A change note.\"` commands and insert a \"### Breaking Changes\" section into the changelog.\n\nTo customize `chlog` in this way, a Python project would add the tool.chlog tables to its `pyproject.toml`. Other projects use `chlog.toml` or `.chlog`.\n\nTODO: Document this in more detail.\n\n## Planned for the next version\n\nExpand issue numbers in new change notes. For example\n`chlog fixed \"Fixed the line-too-long bug issue#1234.\"`\nadds\n`- Fixed the line-too-long bug [#1234](<issues-url>/1234).`\nto the changelog. For this to work, the TOML config must specify the issues URL e.g.\n\n ```toml\n [project.urls]\n Issues = \"https://github.com/myaccount/myproject/issues/\"\n ```\n\nor\n\n ```toml\n [tool.chlog.urls]\n issues = \"https://github.com/myaccount/myproject/issues/\"\n ```\n",
"bugtrack_url": null,
"license": null,
"summary": "Keep changelogs the easy way",
"version": "0.8.0",
"split_keywords": [
"cli",
"console",
"changelog"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "df80f95503f9ff3f2a55ec9ef74436ebc519657bbc57819bda442fe5a71ca90d",
"md5": "d498d1ae6991a8cbb4721e324427d18e",
"sha256": "838fda3d9e2896906ca3c3d6e15f0088090aab687212b7083406610b6781b922"
},
"downloads": -1,
"filename": "chlog-0.8.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d498d1ae6991a8cbb4721e324427d18e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9,<4",
"size": 14155,
"upload_time": "2023-04-18T15:28:11",
"upload_time_iso_8601": "2023-04-18T15:28:11.013568Z",
"url": "https://files.pythonhosted.org/packages/df/80/f95503f9ff3f2a55ec9ef74436ebc519657bbc57819bda442fe5a71ca90d/chlog-0.8.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "24aae396b00283a6a3ee30f8ae1d441d2ef6b360488b18f2af8e55f6a93ccb76",
"md5": "8f66337e0240ae3460d560349cce4a35",
"sha256": "c7ea4ecf292af16eaa614ede5f8937830033c1bb0b3639f645ebb8b7d59a784a"
},
"downloads": -1,
"filename": "chlog-0.8.0.tar.gz",
"has_sig": false,
"md5_digest": "8f66337e0240ae3460d560349cce4a35",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9,<4",
"size": 20984,
"upload_time": "2023-04-18T15:28:13",
"upload_time_iso_8601": "2023-04-18T15:28:13.843423Z",
"url": "https://files.pythonhosted.org/packages/24/aa/e396b00283a6a3ee30f8ae1d441d2ef6b360488b18f2af8e55f6a93ccb76/chlog-0.8.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-04-18 15:28:13",
"github": false,
"gitlab": false,
"bitbucket": false,
"lcname": "chlog"
}
