Many open source projects already provide a Changelog / News / Release-Notes file. There's no standardized format for them, but common formatting practices.

Common structure

Freshcode autoupdating understands plain text, MarkDown and ReStructuredText variants following the common scheme:

1.0.0 (2014-08-20)
------------------
  * Added foo and bar.
  * Fixed file saving bugs.

0.9.9 (2013-12-31)
------------------
  * Adds better manpages.
  * Removes old logos.

Most importantly releases should be ordered newest first.

• Each version header must contain a version number.
• And an ISO date or timestring.
• Changes, fixes should be in some form of bullet list.

Quite a few custom formats are still supported. In particular release headlines are often marked up using MarkDown or Wiki or ReStructuredText headers:

## 1.2.0 / 2014-07-17

  * Changes xyz, baz.

Version prefixes

The version number may be prefixed by:

• Changes for or Changes in
• Version or Release
• or just a v or R prefix

The date is commonly enclosed in parens, but may be separated using slashes, hyphens, etc.

Semantic lists

Bullet point lists can obviously use other list markers than *.
A more recent development (in plain text release notes) are for instance semantic bullet lists:

===== 1.3.0 - 2015-01-01 =====
  - Removed something.
  * Changes feature.
  + Added function.

Freshcode tries to add periods at the end of sentences.

Subheadings

It's also common and therefore supported to insert (MarkDown) taglines between change lists:

## Version 1.7.5 (2015-02-30)

#### Core:
  * Changes xyz.
  * Fixes bar.

#### UI:
  * New logo.

Freshcode adds colons for subtitles, so it can overall be used as flow text.

Supported Extensions

Freshcodes autoupdate module supports one extension to the common formats, in that it permits release tags in version headlines:

 ## v2.0.0-rc1 minor bugfix prerelease (2015-05-20)

This avoids lengthy version suffix chains. But again, is non-standard.

Unreleased development version

Sometimes a Changelog is only extended prior actual release. Often the ChangeLog is kept updated as part of the development process. In such cases the future version number is often preset by an established numbering scheme.

To prevent Changelogs being interpreted prematurely as signifying a finished release, leave out the release date:

 ## 3.1.7 (unrelease/trunk)

Because the date/timestamp crowns a changelog entry, this often suffices. Prefixing "development version" or even leaving out the version number until it's done works just as well.

Why aren't other variations supported?

To reduce false positives. In particular the version headers come in various other formats. Not uncommonly the project title is prepended, or spacy indentation used.

The format constrains OTOH permit release news sections to be part of a README without ambiguity.

Regex rules

The AutoupdateRegex module allows to extract from any custom/non-standard NEWS file format with a bit extra effort. As the Changelog module is basically just a specialization of that, a single regex can be used here too for overriding the version header format:

 header = /^(\d+\.\d+(?:\.\d+)+\b\V*)/m

For example picks up any line that starts with a version number. It's important that exactly one regex capture group is used, which preferrably matches the version number.

State

functional, testing