D 2014-12-08T17:26:35.000
L AutoupdateChangelog
N text/x-markdown
P 71c98b92b242351f40ec85d67c5dfaf290e1d99c
U mario
W 4309
Many open source projects already provide a Changelog / News / Release-Notes file. There's [no standardized format](wiki/UnifiedChangeLog) for them, but common formatting practices.
#### Common structure
Freshcode [autoupdating](wiki/Autoupdate) 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](wiki/UnifiedChangeLog).
#### 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](wiki/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.
#### Interval
Same as with other modules an additional `interval = 7` rule can be used to enforce a minimum delay between fetched/published releases.
#### Exclude
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.
#### State
<i>implemented, working</i>
Z 9d88a490c24adc11e130937f6706db26