⌈⌋ branch:  freshcode

Artifact Content

  • File page_drchangelog.php — part of check-in [a53e4ee480] at 2016-05-05 02:13:03 on branch trunk — Add `debian` changelog autoupdating method. (user: mario

Artifact d4c38a1da0b2df730234c6991c95c389cd729008:

 * type: page
 * title: Dr. Changelog
 * description: Tool to experiment and try out Autoupdate modules
 * version: 0.2
 * license: AfferoGPL
 * Reuses fields from /submit form to start a live check run with
 * actual Autoupdate modules.

$header_add = "<meta name=robots content=noindex>";

#-- Output formatted results
class TestProject extends ArrayObject {
    function update($result) {
        #-- output formatted
        print "<dl>\n";
        foreach ($result as $key=>$value) {
            print "<dt><b>$key</b></dt>\n<dd>" . input::html($value) . "</dd>\n";
        print "</dl>";

// run test
if ($_REQUEST->has("test")) {

    #-- prepare
    $run = new Autoupdate();
    $run->debug = $_REQUEST->boolean["debug"] ? 3 : 0;
    $project = new TestProject(array(
         "name" => "testproject",
         "version" => "",
         "t_published" => 0,
         "homepage" => "",
         "download" => "",
         "urls" => "",
         "autoupdate_module" => $_REQUEST->id->in_array("autoupdate_module", "none,release.json,changelog,regex,github,sourceforge,launchpad,debian"),
         "autoupdate_url" => $_REQUEST->url["autoupdate_url"],
         "autoupdate_regex" => $_REQUEST->raw["autoupdate_regex"],
    #-- exec
    $method = $run->map[$project["autoupdate_module"]];
    print "<h3>Results for <em>$method</em> extraction</h3>\n";
    $result = $run->$method($project);
    $result = new TestProject((array)$result);

// display form
else {

   $data = $_REQUEST->list->html["name,autoupdate_module,autoupdate_url,autoupdate_regex"];
   $data["autoupdate_regex"] or $data["autoupdate_regex"] = "\n\n"; # "version = /Version ([\d.]+)/\n\nchanges = http://example.org/news.html\nchanges = $('article pre#release')\nchanges = ~ ((add|fix|change) \V+) ~mix*";
   $current_date = strftime("%Y-%m-%d", time());

   $select = "form_select_options";

 * page-specific layout
.autoupdate-alternatives { border-spacing: 5pt; }
.autoupdate-alternatives td {
    padding: 3pt;
    width: 25%;
    vertical-align: top;
    background: #fcfcfc linear-gradient(to bottom, #f7f0e9, #fff);
    box-shadow: 2px 2px 3px 1px #f9f5f1;
    border-radius: 10pt;
    font-size: 95%;
.autoupdate-alternatives td .hidden {
    position: absolute;
    display: none;
.autoupdate-alternatives td:hover .hidden {
    display: block;
.autoupdate-alternatives td .hidden pre {
    position: relative; top: -30pt; left: -30pt;
    padding: 7pt;
    border: 7px solid #111;
    border-radius: 7pt;
    background: #f7f7f7;
    background-image: radial-gradient(circle at 50% 50%, rgb(255,255,255), rgb(244,244,244));
li {
    padding: 1.5pt;
   <h3>Dr. Changelog</h3> 
   <form action=drchangelog method=POST>
        <img src=img/drchangelog.png align=right alt="birdy big eyes" title="Don't ask me, I'm just a pictogram.">
           Freshcode.club can automatically track your software releases. There are
           <a href="http://fossil.include-once.org/freshcode/wiki/Autoupdate">various
           alternatives for</a> uncovering them. Try them out.

               Retrieval method
               <select name=autoupdate_module>
                   {$select("release.json,changelog,regex,github,sourceforge,launchpad,debian", $data["autoupdate_module"])}

           <table class=autoupdate-alternatives><tr>
             <a href="http://fossil.include-once.org/freshcode/wiki/releases.json"><em>releases.json</em></a>
             defines a concrete scheme for publishing version and release notes.
<span class=hidden><pre>
  "version": "1.0.0",
  "changes": "Fixes and adds lots
              of new functions ..",
  "state": "stable",
  "scope": "major feature",
  "download": "http://exmpl.org/"
           <td>While a <a href="http://fossil.include-once.org/freshcode/wiki/AutoupdateChangelog"><em>Changelog</em></a>
             text file is likely the easiest, given a coherent format and style.
<span class=hidden><pre>
1.0.0 ($current_date)
 * 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
           <td><a href="http://fossil.include-once.org/freshcode/wiki/AutoupdateGithub"><em>Github</em></a>
            extraction prefers <nobr>/releases</nobr> notes. But may as last resort condense a git commit log.
<span class=hidden><pre><a href="https://github.com/blog/1547-release-your-software"><img src="https://camo.githubusercontent.com/9f23f54df9e2f69047fb0f9f80b2e33c8339606f/68747470733a2f2f662e636c6f75642e6769746875622e636f6d2f6173736574732f32312f3733373136362f62643163623637652d653332392d313165322d393064312d3361656365653930373339662e6a7067" width=400 height=200></a></pre></span>
           <td>Using <a href="http://fossil.include-once.org/freshcode/wiki/AutoupdateRegex"><em>regex/xpath</em></a>
             is however the most universal way to extract from project websites.
<span class=hidden><pre>
<span style=color:gray># load page</span>
changes = http://exmpl/news

<span style=color:gray># jQuery</span>
changes = $("body .release")
<span style=color:gray># RegExp</span>
version = /Version \d+\.\d+/


               Autoupdate URL
               <input name=autoupdate_url type=url size=80 value="$data[autoupdate_url]" placeholder="https://github.com/user/repo/tags.atom" maxlength=250>
           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.

           <h4>Content Scraping</h4>
           Picking out from your own project website can be surprisingly simple. Define a list for at
           least <code>version = ...</code> and <code>changes = ...</code> - Add source URLs
           and apply
           <a href="http://fossil.include-once.org/freshcode/wiki/AutoupdateRegex">
           RegExp, XPath, or jQuery</a> selectors for extraction.
               Extraction Rules <em>(URLs, Regex, Xpath, jQuery)</em>
               <textarea cols=67 rows=10 name=autoupdate_regex placeholder="version = /-(\d+\.\d+\.\d+)\.txz/" maxlength=2500>$data[autoupdate_regex]</textarea>
               <li>Assigning new URLs is only necessary when there's different data to extract from.</li>
               <li>RegExps like <code>version = /Changes for ([\d.]+)/</code> often match headlines well.</li>
               <li>A common XPath rule for extracting the first bullet point list is <code>changes = (//ul)[1]/li</code>.</li>
               <li>While <code>changes = $("section#main article .release")</code> narrows it down
                   for HTML pages.</li>
               <li>You often can mix extractors - e.g. first an XPath/jQuery expression, then a RegExp.</li>
               <li>Rules for state=, scope= and download= are optional.</li>
               <li>The <b>changelog</b> parser allows a <code>header = /^Name ([\d.]+)/m</code> customization rule, btw.</li>
               <li>Generic rules like <code>interval = 3 days</code> and  <code>exclude = 0.9.9, 1.2.3</code> work for all retrieval methods.</li>
          <input type=submit name=test value=Test-Run>
          <label style="font-weight: normal"><input style="display: inline" type=checkbox name=debug value=yes> with some debug notices</label>

<td id=sidebar>
  <h5>Know your audience</h5>
  <p> Whatever source you choose for release announcements, try to keep them <b>user-friendly</b>. </p>
  <p> 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.</p>
  <p> So be careful with the <em>GitHub</em> module in particular. If you're not using githubs
      /release tool, a commit log may be used still. Only basic filtering is applied.
      <em>🔧 And it's sort of broken at the momement :/</em></p>
  <p> Likewise write <em>Changelogs</em> as <b>summaries</b>. (They're better and more correctly called NEWS
      or RELEASE-NOTES files actually.)</p>