Scriv
Scriv changelog management tool
.. begin-badges
| |pypi-badge| |ci-badge| |coverage-badge| |doc-badge| | |pyversions-badge| |license-badge| |sponsor-badge| |mastodon-nedbat|
.. end
Scriv is a command-line tool for helping developers maintain useful changelogs. It manages a directory of changelog fragments. It aggregates them into entries in a CHANGELOG file.
Scriv writes changelog fragments into a directory called "changelog.d". Start by creating this directory. (By the way, like many aspects of scriv's operation, you can choose a different name for this directory.)
To make a new changelog fragment, use the scriv create command. It will
make a new file with a filename using the current date and time, your GitHub or
Git user name, and your branch name. Changelog fragments should be committed
along with all the other changes on your branch.
When it is time to release your project, the scriv collect command
aggregates all the fragments into a new entry in your changelog file.
You can also choose to publish your changelog entries as GitHub releases with
the scriv github-release command. It parses the changelog file and
creates or updates GitHub releases to match. It can be used even with
changelog files that were not created by scriv.
Full documentation is at https://scriv.readthedocs.org.
The code in this repository is licensed under the Apache Software License 2.0 unless otherwise noted.
Please see LICENSE.txt for details.
Contributions are very welcome. Thanks to all the contributors so far:
.. begin-contributors
| Ned Batchelder | Abhilash Raj | Agustín Piqueres | Flo Kuepper | James Gerity | Javier Sagredo | Kurt McKee | Matias Guijarro | Rodrigo Girão Serrão | Ronny Pfannschmidt
.. end
.. begin-badge-links
.. |pypi-badge| image:: https://img.shields.io/pypi/v/scriv.svg :target: https://pypi.python.org/pypi/scriv/ :alt: PyPI
.. |ci-badge| image:: https://github.com/nedbat/scriv/workflows/Test%20Suite/badge.svg :target: https://github.com/nedbat/scriv/actions?query=workflow%3A%22Test+Suite%22 :alt: Build status
.. |coverage-badge| image:: https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/nedbat/5a304c1c779d4bcc57be95f847e9327f/raw/covbadge.json :target: https://github.com/nedbat/scriv/actions?query=workflow%3A%22Test+Suite%22 :alt: Coverage
.. |doc-badge| image:: https://readthedocs.org/projects/scriv/badge/?version=latest :target: http://scriv.readthedocs.io/en/latest/ :alt: Documentation
.. |pyversions-badge| image:: https://img.shields.io/pypi/pyversions/scriv.svg :target: https://pypi.python.org/pypi/scriv/ :alt: Supported Python versions
.. |license-badge| image:: https://img.shields.io/github/license/nedbat/scriv.svg :target: https://github.com/nedbat/scriv/blob/master/LICENSE.txt :alt: License
.. |mastodon-nedbat| image:: https://img.shields.io/badge/dynamic/json?style=flat&labelColor=450657&logo=mastodon&logoColor=ffffff&link=https%3A%2F%2Fhachyderm.io%2F%40nedbat&url=https%3A%2F%2Fhachyderm.io%2Fusers%2Fnedbat%2Ffollowers.json&query=totalItems&label=Mastodon :target: https://hachyderm.io/@nedbat :alt: nedbat on Mastodon
.. |sponsor-badge| image:: https://img.shields.io/badge/%E2%9D%A4-Sponsor%20me-brightgreen?style=flat&logo=GitHub :target: https://github.com/sponsors/nedbat :alt: Sponsor me on GitHub
.. end
.. this will be appended to README.rst
.. All enhancements and patches to scriv will be documented in this file. It adheres to the structure of http://keepachangelog.com/ , but in reStructuredText instead of Markdown (for ease of incorporation into Sphinx documentation and the PyPI description).
This project adheres to Semantic Versioning (http://semver.org/).
See the fragment files in the changelog.d directory_.
.. _changelog.d directory: https://github.com/nedbat/scriv/tree/master/changelog.d
.. scriv-insert-here
.. _changelog-1.5.1:
Fixed .....
issue 118_... _issue 118: https://github.com/nedbat/scriv/issues/118
.. _changelog-1.5.0:
Added .....
RST to Markdown conversion can now be stricter. Using the --fail-if-warn
option on the scriv github-releases command will fail the command if your
RST conversion generates warnings, for example due to malformed link
references.
The scriv github-release command now has a --check-links option to
check URLs. Each is fetched, and if an error occurs, warnings will show the
URLs that didn't succeed.
Fixed .....
.. _changelog-1.4.0:
Added .....
Literals can be extracted from .cabal files.
Thanks Javier Sagredo <pull 91_>_.
Use the git config scriv.user_nick for the user nick part
of the fragment file. Thanks to Ronny Pfannschmidt <pull 106_>,
fixing issue 103.
Settings can now be prefixed with command: to execute the rest of the
setting as a shell command. The output of the command will be used as the
value of the setting.
Fixed .....
If there are no changelog fragments, scriv collect now exits with status
code of 2, fixing issue 110_.
Changelogs with non-version headings now produce an understandable error
message from scriv collect, thanks to James Gerity <pull 101_>, fixing
issue 100.
.. _pull 91: https://github.com/nedbat/scriv/pull/91 .. _issue 100: https://github.com/nedbat/scriv/issues/100 .. _pull 101: https://github.com/nedbat/scriv/pull/101 .. _issue 103: https://github.com/nedbat/scriv/pull/103 .. _pull 106: https://github.com/nedbat/scriv/pull/106 .. _issue 110: https://github.com/nedbat/scriv/issues/110
.. _changelog-1.3.1:
Fixed .....
scriv github-release
command. This is now fixed... _changelog-1.3.0:
Added .....
.cfg files can now be read with literal: settings, thanks to Matias Guijarro <pull 88_>_... _pull 88: https://github.com/nedbat/scriv/pull/88
Fixed .....
PEP 440, comparing version numbers now ignores a
leading "v" character. This makes scriv more flexible about how you present
version numbers in various places (code literals, changelog entries, git
tags, and so on). Fixes issue 89... _PEP 440: https://peps.python.org/pep-0440/ .. _issue 89: https://github.com/nedbat/scriv/issues/89
.. _changelog-1.2.1:
Fixed .....
Scriv would fail trying to import tomllib on Python <3.11 if installed
without the [toml] extra. This is now fixed, closing issue 80_.
Settings specified as file: will now search in the changelog directory
and then the current directory for the file. The only exception is if the
first component is . or .., then only the current directory is
considered. Fixes issue 82_.
Python variables with type annotations can now be read with literal:
settings, fixing issue 85_.
Error messages for mis-formed literal: configuration values are more
precise, as requested in issue 84_.
Error messages from settings validation are ScrivExceptions now, and report configuration problems more clearly and earlier in some cases.
.. _issue 80: https://github.com/nedbat/scriv/issues/80 .. _issue 82: https://github.com/nedbat/scriv/issues/82 .. _issue 84: https://github.com/nedbat/scriv/issues/84 .. _issue 85: https://github.com/nedbat/scriv/issues/85
.. _changelog-1.2.0:
Added .....
scriv github-release now has a --repo= option to specify which GitHub
repo to use when you have multiple remotes.Changed .......
scriv github-release when a GitHub repo
can't be identified among the git remotes... _changelog-1.1.0:
Added .....
The scriv github-release command has a new setting, ghrel_template.
This is a template to use when building the release text, to add text before
or after the Markdown extracted from the changelog.
The scriv github-release command now has a --dry-run option to show
what would happen, without posting to GitHub.
Changed .......
File names specified for file: settings will be interpreted relative to
the current directory if they have path components. If the file name has no
slashes or backslashes, then the old behavior remains: the file will be found
in the fragment directory, or as a built-in template.
All exceptions raised by Scriv are now ScrivException.
Fixed .....
Parsing changelogs now take the insert-marker setting into account. Only
content after the insert-marker line is parsed.
More internal activities are logged, to help debug operations.
.. _changelog-1.0.0:
Added .....
issue 69.
Thanks, Florian Küpper <pull 70_>... _pull 70: https://github.com/nedbat/scriv/pull/70 .. _issue 69: https://github.com/nedbat/scriv/issues/69
Fixed .....
issue 63_... _issue 63: https://github.com/nedbat/scriv/issues/63
.. _changelog-0.17.0:
Added .....
collect command now has a --title=TEXT option to provide the
exact text to use as the title of the new changelog entry. Finishes issue 48_... _issue 48: https://github.com/nedbat/scriv/issues/48
Changed .......
The github_release command now only considers the top-most entry in the
changelog. You can use the --all option to continue the old behavior of
making or updating GitHub releases for all of the entries.
This change makes it easier for projects to start using scriv with an existing populated changelog file.
Closes issue 57_.
.. _issue 57: https://github.com/nedbat/scriv/issues/57
Fixed .....
scriv collect would make a new empty
section in the changelog. This was wrong, and is now fixed. Now the
changelog remains unchanged in this case. Closes issue 55_... _issue 55: https://github.com/nedbat/scriv/issues/55
github-release command will now issue a warning for changelog entries
that have no version number. These can't be made into releases, so they are
skipped. (issue 56_)... _issue 56: https://github.com/nedbat/scriv/issues/56
scriv collect will end with an error now if the version number would
duplicate a version number on an existing changelog entry. Fixes issue 26_... _issue 26: https://github.com/nedbat/scriv/issues/26
.. _changelog-0.16.0:
Added .....
github_release command will use a GitHub personal access token stored
in the GITHUB_TOKEN environment variable, or from a .netrc file.Fixed .....
The github_release command was using git tags as a command when it should
have used git tag.
Anchors in the changelog were being included in the previous sections when
creating GitHub releases. This has been fixed, closing issue 53_.
.. _issue 53: https://github.com/nedbat/scriv/issues/53
.. _changelog-0.15.2:
Fixed .....
.. _changelog-0.15.1:
Added .....
scriv github-release.Fixed .....
.. _changelog-0.15.0:
Removed .......
Added .....
The github-release command parses the changelog and creates GitHub releases
from the entries. Changed entries will update the corresponding release.
Added a --version option.
Changed .......
.. _changelog-0.14.0:
Added .....
scriv collect
so URLs for the sections are predictable and stable for each new version
(Fixes issue 46_). Thanks Abhilash Raj and Rodrigo Girão Serrão.Fixed .....
.. _issue 46: https://github.com/nedbat/scriv/issues/46
Added .....
pyproject.toml)
using the literal configuration directive. Thanks, Kurt McKeeAdded .....
skip_fragments, a glob pattern. The default
value is "README.*". This lets you put a README.md file in that directory to
explain its purpose, as requested in issue 40_... _issue 40: https://github.com/nedbat/scriv/issues/40
Changed .......
Fixed .....
format=md didn't properly cascade into other default settings,
leaving you with RST settings that needed to be explicitly overridden
(issue 39_). This is now fixed... _issue 39: https://github.com/nedbat/scriv/issues/39
Added .....
Changed .......
Fixed .....
Added .....
issue 9_... _issue 9: https://github.com/nedbat/scriv/issues/9
Changed .......
The default entry header no longer puts the version number in square brackets: this was a misunderstanding of the keepachangelog formatting.
Respect the existing newline style of changelog files. (#14_)
This means that a changelog file with Linux newlines on a Windows platform
will be updated with Linux newlines, not rewritten with Windows newlines.
Thanks, Kurt McKee.
.. _#14: https://github.com/nedbat/scriv/issues/14
Fixed .....
Support Windows' directory separator (\) in unit test output. (#15_)
This allows the unit tests to run in Windows environments. Thanks, Kurt
McKee.
Explicitly specify the directories and files that Black should scan. (#16_)
This prevents Black from scanning every file in a virtual environment.
Thanks, Kurt McKee.
Using "literal:" values in the configuration file didn't work on Python 3.6
or 3.7, as reported in issue 18_. This is now fixed.
.. _#15: https://github.com/nedbat/scriv/issues/15 .. _#16: https://github.com/nedbat/scriv/issues/16 .. _issue 18: https://github.com/nedbat/scriv/issues/18
Added .....
Markdown format is supported, both for fragments and changelog entries.
Fragments can be mixed (some .rst and some .md). They will be collected and output in the format configured in the settings.
Documentation.
"python -m scriv" now works.
Changed .......
Added .....
issue 2_.).. _issue 2: https://github.com/nedbat/scriv/issues/2
Changed .......
issue 1_)... _issue 1: https://github.com/nedbat/scriv/issues/1
Fixed .....
issue 3_). This is now fixed... _issue 3: https://github.com/nedbat/scriv/issues/3
Added .....
Added the collect command.
Configuration is now read from setup.cfg or tox.ini.
A new configuration setting, rst_section_char, determines the character used in the underlines for the section headings in .rst files.
The new_entry_template configuration setting is the name of the template
file to use when creating new entries. The file will be found in the
fragment_directory directory. The file name defaults to new_entry.FMT.j2.
If the file doesn't exist, an internal default will be used.
Now the collect command also includes a header for the entire entry. The underline is determined by the "rst_header_char" settings. The heading text is determined by the "header" setting, which defaults to the current date.
The categories list in the config can be empty, meaning entries are not categorized.
The create command now accepts --edit (to open the new entry in your text editor), and --add (to "git add" the new entry).
The collect command now accepts --edit (to open the changelog file in an editor after the new entries have been collected) and --add (to git-add the changelog file and git rm the entries).
The names of the main git branches are configurable as "main_branches" in the configuration file. The default is "master", "main", and "develop".
Configuration values can now be read from files by prefixing them with "file:". File names will be interpreted relative to the changelog.d directory, or will be found in a few files installed with scriv.
Configuration values can interpolate the currently configured format (rst or md) with "${config:format}".
The default value for new templates is now "file: new_entry.${config:format}.j2".
Configuration values can be read from string literals in Python code with a "literal:" prefix.
"version" is now a configuration setting. This will be most useful when used with the "literal:" prefix.
By default, the title of collected changelog entries includes the version if it's defined.
The collect command now accepts a --version option to set the version
name used in the changelog entry title.
Changed .......
RST now uses minuses instead of equals.
The create command now includes the time as well as the date in the entry
file name.
The --delete option to collect is now called --keep, and defaults to False. By default, the collected entry files are removed.
Created file names now include the seconds from the current time.
"scriv create" will refuse to overwrite an existing entry file.
Made terminology more uniform: files in changelog.d are "fragments." When collected together, they make one changelog "entry."
The title text for the collected changelog entry is now created from the "entry_title_template" configuration setting. It's a Jinja2 template.
Combined the rst_header_char and rst_section_char settings into one: rst_header_chars, which much be exactly two characters.
Parsing RST fragments is more flexible: the sections can use any valid RST header characters for the underline. Previously, it had to match the configured RST header character.
Fixed .....
FAQs
Scriv changelog management tool
We found that scriv demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.