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.

--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 0.2.0 NEWS.rst
<fancy new NEWS.rst>

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.
--help Show help message and exit.

BUGS

None known.

AUTHOR

Written by James Rowe

COPYING

Copyright © 2016 James Rowe.

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.

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.

Convenience functions
list_entries(path)
Parameters:path (str) – Path to search
Return type:table
Returns:Matching entries
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!