CHANGELOG Management Activity (rever.activities.changelog)

Activity for keeping a changelog from news entries.

class rever.activities.changelog.Changelog(*, deps=frozenset({}))

Manages keeping a changelog up-to-date.

This activity may be configured with the following envionment variables:

$CHANGELOG_FILENAME

str, path to input file. The default is ‘CHANGELOG’.

$CHANGELOG_PATTERN

str, Python regex that is used to find the location in the file where new changelog entries should be placed. The default is '.. current developments'.

$CHANGELOG_HEADER

str or callable that accepts a single version argument, this is the replacement that goes above the new merge entries. This should contain a string that matches the pattern arg so that the next release may be inserted automatically. The default value is:

.. current developments

v$VERSION

====================

$CHANGELOG_NEWS

str, path to directory containing news files. The default is 'news'.

$CHANGELOG_IGNORE

list of str, regexes of filenames in the news directory to ignore. The default is to ignore the template file.

$CHANGELOG_LATEST

str, file to write just the latest part of the changelog to. This defaults to $REVER_DIR/LATEST. This is evaluated in the current environment. If this file is not within $REVER_DIR, it is added to the repository.

$CHANGELOG_TEMPLATE

str, filename of the template file in the news directory. The default is 'TEMPLATE'.

$CHANGELOG_CATEGORIES

iterable of str, the news categories that are used. Default:('Added', 'Changed', 'Deprecated', 'Removed', 'Fixed', 'Security')

$CHANGELOG_CATEGORY_TITLE_FORMAT

str or callable, a format string with {category} entry for formatting changelog and template category titles. If this is a callable, it is a function which takes a single category argument and returns the title string. The default is ``”{category}:

“``.

$CHANGELOG_AUTHORS_TITLE

str or bool, If this is a non-empty string and the authors activitiy is being run, this will append an authors section to this changelog entry that contains all of the authors that contributed to this version. This string is the section title and is formatted as if it were a category with $CHANGELOG_CATEGORY_TITLE_FORMAT. The default is "Authors".

$CHANGELOG_AUTHORS_FORMAT

str, this is a format string that formats each author who contributed to this release, if an authors section will be appened. This is evaluated in the context of the authors, see the authors activity for more details on the available fields. The default is ``”* {name}

“``.

Parameters

namestr, optional

Name of the activity.

depsset of str, optional

Set of activities that must be completed before this activity is executed.

funccallable, optional

Function to perform as activity when this activities is executed (called).

undocallable, optional

Function to undo this activities behaviour and reset the repo state.

setupcallable, optional

Function to help initialize the activity.

checkcallable, optional

Function to check if the activity can be run sucessfully on the user’s machine, with their credentials, etc. This function should return True if the activity can be run, and False otherwise.

requiresdict or None, optional

A dict of dicts of the following form that specifies the command line utility and import requirements for this activity.

{
    "commands": {"<cli name>": "<package name>", ...}
    "imports": {"<module name>": "<package name>", ...}
}

The top-level keys are both optional, and this will default to an empty dict.

argstuple, optional

Arguments to be supplied to the func(*args), if needed.

kwargsmapping, optional

Keyword arguments to be supplied to the func(**kwargs), if needed.

descstr, optional

A short description of this activity

all_kwargs()

Returns all kwargs for this activity.

check()

Calls this activity’s check() function.

check_requirements()

Checks that an activities requirements are actually available.

checker(check)

Decorator that sets the check function for this activity.

clear_kwargs_from_env()

Removes kwarg from the environment, if they exist.

generate_authors(title_format, title, format)

Generates author portion of changelog.

keep_file(filename, ignore)

Returns whether or not a file should be kept based on ignore rules.

kwargs_from_env()

Obtains possible func() kwarg from the environment.

merge_news(news='news', ignore=('TEMPLATE'), categories=('Added', 'Changed', 'Deprecated', 'Removed', 'Fixed', 'Security'), category_title_format='**{category}:**\n\n')

Reads news files and merges them.

setup()

Calls this activity’s setup() initialization function.

setup_func()

Initializes the changelog activity by starting a news dir, making a template file, and starting a changlog file.

setupper(setup)

Decorator that sets the setup function for this activity.

undo()

Reverts to the last instance of this activity. This default implementation uses the revision in the log file from the last time that the activity was started. This may be overridden in a subclass.

undoer(undo)

Decorator that sets the undo function for this activity.

property env_names

Dictionary mapping parameter names to the names of environment varaibles that the activity looks for when it is executed.