Many open source projects already provide a Changelog / News / Release-Notes file. There's no standardized format for them, but common formatting practices.
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.
The version number may be prefixed by:
- or just a
The date is commonly enclosed in parens, but may be separated using slashes, hyphens, etc.
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.
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.
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 (unreleased/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. (There's also support for "[YANKED]" tagging in place of release dates; in accordance with keepachangelog.)
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.
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:
# matches "1.2.3 anything" header = /^(\d+\.\d+(?:\.\d+)+\b\V*)/m
Or for multiline headers:
# matches "Name 1.2.3-rc1\n12-12-2012" header = /^Projectname ([\d.-\w]+)\s+\d+-\d+-\d+\V*/m
It's important that exactly one regex capture group is used, which preferrably matches the version number.
Same as with other modules an additional
interval = 7 rule can be used to enforce a minimum delay between fetched/published releases.
In case you manually submitted the newest release, but the Changelog is only current with something previous, an additional
exclude = 1.2.3 rule can be given. It may list multiple versions to skip
exclude = 1.0-beta, 2.0-beta even.