`histofile`¶

histofile is a small tool to aid in the management of NEWS files for a project.

The intention is that each time you commit or merge a change that warrants an entry in your NEWS file you also add a new histofile data file. When it is time to cut a new release you tell histofile, and it updates your NEWS file from your pre-existing entries.

This should save an enormous amount of time, as it reduces the need to scan through the commit log then manually create a NEWS file.

The data files are stored as plaintext in your chosen directory with one file per entry, which means unlike a developer updated NEWS file in your repository histofile should work easily across merges [1].

It is written in moonscript, and requires v0.3.0 or later. histofile is released under the GPL v3.

Git repository:	https://github.com/JNRowe/histofile/
Issue tracker:	https://github.com/JNRowe/histofile/issues/
Contributors:	https://github.com/JNRowe/histofile/contributors/

Contents¶

Background¶

One of the most important aspects of creating a new software release is updating your users with all the fancy new features, deprecated functionality and breaking changes that may have happened. Depressingly, this important task is often rushed in five minutes or skipped entirely. It can definitely be annoying having to pour over hundreds of commits to find the important user facing items, and there should be a tool to automate some of that.

The features I need in a tool for this task are:

Support for multiple branches without having to spend three hours shuffling merges
Easily accessible data, in a format that can be processed simply
Ability to work off-line, because those times are considerably more common than some people seem to think
Works on all the platforms I regularly use; desktop, mobile phone, ZipIt, and more

Now histofile is born, and I should be able to realise those dreams!

Philosophy¶

NEWS entries should be:

Written when the commit is made, you shouldn’t need to scan diffs from six months ago.
Self-contained, you shouldn’t need to handle a heap of merge conflicts because you have multiple branches or developers.
Easy to generate
Easy to mass process

Usage¶

The histofile script is the main workhorse of histofile.

See Getting started for basic usage examples.

Options¶

--version¶: Show the version and exit.

-d <directory>, --directory=<directory>¶: Database location, defaults to .histofile.

--help¶: Show help message and exit.

Commands¶

`list` - List history entries¶

histofile list [--help]

--help¶: Show help message and exit.

`new` - Add new history entry¶

histofile new <entry>

--help¶: Show help message and exit.

`update` - Update history file¶

histofile update [--help] <version> <file>

-d <date>, --date <date>¶: Date of release, defaults to today.

-o <file>, --output <file>¶: Output file name.

-t <name>, --template <name>¶: Template name, defaults to “default”

-k, --keep¶: Keep old data files after update (default when writing to stdout).

--help¶: Show help message and exit.

Getting started¶

Basic usage¶

The command interface is hopefully quite intuitive. The following is a sample session:

$ histofile new "Add support for cake baking"
$ histofile new "Removed support for window cleaning"
$ histofile list
2016-02-10T12:03:00     Add support for cake baking
2016-02-10T12:03:05     Removed support for window cleaning
$ histofile update --output - 0.2.0 NEWS.rst
<fancy new NEWS.rst>
$ histofile update 0.2.0 NEWS.rst
<NEWS.rst is updated in place>

Help on individual subcommands is available via histofile <subcommand> --help or in the Usage document.

histofile¶

Manage version history files¶

SYNOPSIS¶

histofile [option]... <command>

DESCRIPTION¶

histofile is a small tool to aid in the management of NEWS files for a project.

OPTIONS¶

`--version`	Show the version and exit.
`-d <directory>, --directory <directory>`
	Location to store history entries, defaults to `.histofile`.
`--help`	Show help message and exit.

COMMANDS¶

`list`¶

List history entries.

--help

Show help message and exit.

`new`¶

Add new history entry.

--help

Show help message and exit.

`update`¶

Update history file.

`-d <date>, --date <date>`
	Date of release, defaults to today.
`-o <file>, --output <file>`
	Output file name.
`-t <name>, --template <name>`
	Template name, defaults to “default”
`-k, --keep`	Keep old data files after update (default when writing to stdout).
`--help`	Show help message and exit.

BUGS¶

None known.

AUTHOR¶

Written by James Rowe

RESOURCES¶

Issue tracker: https://github.com/JNRowe/histofile/issues/

COPYING¶

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

Frequently Asked Questions ¶

Contents

Frequently Asked Questions

Alternatives¶

Before diving in and spitting out this package I looked for alternatives, but couldn’t find anything beyond suggestions about formatting to make a developer updated NEWS file more manageable.

If I have missed something please drop me a mail.

Release HOWTO¶

Prepare release¶

Update the version data in version.moon
Update NEWS.rst, with histofile ;)
Commit the release notes and version changes
Create a signed tag for the release
Push the changes, including the new tag, to the GitHub repository
Create new release on GitHub

Announce release¶

Check the generated tarballs for errors; missing files, stale files, &c

You should also perform test installations, to check the experience histofile users will have.

API documentation¶

Note

The documentation in this section is aimed at people wishing to contribute to histofile, and can be skipped if you are simply using the tool from the command line.

Command line¶

Note

The documentation in this section is aimed at people wishing to contribute to histofile, and can be skipped if you are simply using the tool from the command line.

Commands¶

commands.list(args)¶

List history entries.

Parameters:	args (table) – Parsed arguments
Return type:	int
Returns:	0 on success, 2 when no entries are found

commands.new(args)¶

Add new history entry.

Parameters:	args (table) – Parsed arguments
Return type:	int
Returns:	0 on success, 5 when writing fails

commands.update(args)¶

Update history file.

Parameters:	args (table) – Parsed arguments
Return type:	int
Returns:	0 on success, 2 when no entries are found

Entry points¶

main()¶: Main entry point.

CLI support¶

parse_args()¶

Parse command line arguments.

Return type:	table
Returns:	Processed command line arguments

Miscellaneous¶

Note

The documentation in this section is aimed at people wishing to contribute to histofile, and can be skipped if you are simply using the tool from the command line.

Templates¶

HISTORY_TEMPLATE¶: Header template for NEWS file.

MARKER_STRING¶: Location to insert new entries.

Utilities¶

Note

The documentation in this section is aimed at people wishing to contribute to histofile, and can be skipped if you are simply using the tool from the command line.

Data loading¶

find_entries(path)¶

Parameters:	path (str) – Path to search
Return type:	table
Returns:	Matching entries

find_marker(file)¶

Find location to insert new entries

Parameters:	file (str) – File to operate on
Return type:	int
Returns:	Line to insert new entries

File creation¶

build_file(file, marker, entries, version, date)¶

Generate new NEWS file

Parameters:	file (str) – File to operate on marker (int) – Line to insert new text at entries (table) – New entries to insert
Return type:	table
Returns:	Lines comprising complete output

write_output(ofile, output, use_temp)¶

Write output to file or stdout

Parameters:	ofile (str) – Output file name output (str) – Output to write

Text formatting¶

colourise(text, colour, bold, underline)¶

Generate coloured output for the terminal.

Parameters:	text (str) – Text to colourise colour (str) – Colour to use bold (bool) – Use bold output underline (bool) – Use underline output
Return type:	str
Returns:	Colourised output

success(text, bold)¶

Standardised success message.

Parameters:	text (str) – Text to colourise bold (bool) – Use bold output
Return type:	str
Returns:	Prettified success message

fail(text, bold)¶

Standardised failure message.

Parameters:	text (str) – Text to colourise bold (bool) – Use bold output
Return type:	str
Returns:	Prettified failure message

warn(text, bold)¶

Standardised warning message.

Parameters:	text (str) – Text to colourise bold (bool) – Use bold output
Return type:	str
Returns:	Prettified warning message

wrap_entry(text, width, initial_indent, subsequent_indent)¶

Wrap text for output

Parameters:	text (str) – Text to format int – Width of formatted text initial_indent (str) – String to indent first line with subsequent_indent (str) – String to indent all but the first line with
Return type:	str
Returns:	Line wrapped text

Indices and tables¶

[1]	`git`, and some other VCSes, do support per-file merge tools that can make a simple edited file approach work. Using that may be the best option for you!

histofile¶

Contents¶

Background¶

Philosophy¶

Usage¶

Options¶

Commands¶

list - List history entries¶

new - Add new history entry¶

update - Update history file¶

Getting started¶

Basic usage¶

histofile¶

Manage version history files¶

SYNOPSIS¶

DESCRIPTION¶

OPTIONS¶

COMMANDS¶

list¶

new¶

update¶

BUGS¶

AUTHOR¶

RESOURCES¶

COPYING¶

Frequently Asked Questions¶

Alternatives¶

Release HOWTO¶

Prepare release¶

Announce release¶

API documentation¶

Command line¶

Commands¶

Entry points¶

CLI support¶

Miscellaneous¶

Templates¶

Utilities¶

Data loading¶

File creation¶

Text formatting¶

Indices and tables¶

`histofile`¶

`list` - List history entries¶

`new` - Add new history entry¶

`update` - Update history file¶

`list`¶

`new`¶

`update`¶

Frequently Asked Questions ¶