freshcode.club

Dr. Changelog

Freshcode.club can automatically track your software releases. There are various alternatives for uncovering them. Try them out. Retrieval method

releases.json defines a concrete scheme for publishing version and release notes.

{
  "version": "1.0.0",
  "changes": "Fixes and adds lots
              of new functions ..",
  "state": "stable",
  "scope": "major feature",
  "download": "http://exmpl.org/"
}

While a Changelog text file is likely the easiest, given a coherent format and style.

1.0.0 (2024-04-18)
------------------
 * Changes foo and bar.
 + Adds baz baz.
 - Some more bugs removed.
 
0.9.9 (2014-02-27)
------------------
 * Now uses Qt5
 - Removed all the bugs

0.9.1 (2014-01-20)
------------------
 * Initial release with

Github extraction prefers /releases notes. But may as last resort condense a git commit log.

Using regex/xpath is however the most universal way to extract from project websites.

# load page
changes = http://exmpl/news

# jQuery
changes = $("body .release")
 
# RegExp
version = /Version \d+\.\d+/

Autoupdate URL Add the URL to your Changelog, releases.json, or GitHub project here. For the regex method this will also be the first page to be extracted from.

Content Scraping

Picking out from your own project website can be surprisingly simple. Define a list for at least version = ... and changes = ... - Add source URLs and apply RegExp, XPath, or jQuery selectors for extraction. Extraction Rules (URLs, Regex, Xpath, jQuery)

Assigning new URLs is only necessary when there's different data to extract from.

RegExps like version = /Changes for ([\d.]+)/ often match headlines well.

A common XPath rule for extracting the first bullet point list is changes = (//ul)[1]/li.

While changes = $("section#main article .release") narrows it down for HTML pages.

You often can mix extractors - e.g. first an XPath/jQuery expression, then a RegExp.

Rules for state=, scope= and download= are optional.

The changelog parser allows a header = /^Name ([\d.]+)/m customization rule, btw.

Generic rules like interval = 3 days and exclude = 0.9.9, 1.2.3 work for all retrieval methods.

with some debug notices

Know your audience

Whatever source you choose for release announcements, try to keep them user-friendly.

End users aren't fond of commit logs. While "merged pull request XY" might be technically highly relevant (for e.g. libraries), it's gibberish to most everyone else.

So be careful with the GitHub module in particular. If you're not using githubs /release tool, a commit log may be used still. Only basic filtering is applied. 🔧 And it's sort of broken at the momement :/

Likewise write Changelogs as summaries. (They're better and more correctly called NEWS or RELEASE-NOTES files actually.)