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 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.

However, the AutoupdateRegex module or a custom local Changelog reformatting tool could be used for non-standard release news files instead.

State

functional, testing