Releases: Variablize Release Notes

Add additional variables to the release note files to allow setting the
version number and date.  The version number is required, and can be
used to automatically set the release notes title.  The date is optional
and can be set hours/days after the release.

Additionally, a Makefile test is added that checks whether the download
files exist on the Bitcoin.org server.  This can help prevent creating a
broken Download page.

* Set variables for all previous releases

* Document variables in README.md

* Update code and templates to use variables

* Add the Download page links to the "dl" CSS class. Also add newlines
  to make the HTML a bit easier to parse using sed

* Add a new Liquid plugin to print warnings. This is used to print a
  non-error warning if any release is created without the optional date

Makefile

@@ -48,7 +48,8 @@ pre-build-tests: pre-build-tests-fast
 	@ true
 
 ## All post-build tests, including those which might take multiple minutes
-post-build-tests: post-build-tests-fast
+post-build-tests: post-build-tests-fast \
+    check-for-broken-bitcoin-core-download-links
 	@ true ## SOMEDAY: use linkchecker to find broken links 
 	@      ## after this bug is fixed: https://github.com/wummel/linkchecker/issues/513
 
@@ -197,3 +198,14 @@ manual-check-diff-sha256sums:
 	  | sort - _site/sha256sums.txt \
 	  | uniq -u \
 	  | sort -k2
+
+check-for-broken-bitcoin-core-download-links:
+	$S grep 'class="dl"' _site/en/download.html \
+	  | sed 's/.*href="//; s/".*//' \
+	  | while read url ; do \
+	    if [ "$${url##http*}" ]; then \
+	      curl -sI "https://bitcoin.org$$url" ; \
+	    else \
+	      curl -sI "$$url" ; \
+	    fi | grep -q '200 OK' || echo "Error: Could not retrieve $$url" ; \
+	  done | eval $(ERROR_ON_OUTPUT)

README.md

@@ -303,21 +303,55 @@ issue][] if a Bitcoin meetup event isn't displayed.)
 
 ### Release Notes
 
-Release notes should be placed in `_releases/YYYY-MM-DD-VERSION.md` and adhere to this format:
+To create a new Bitcoin Core release, create a new file in the
+`_releases/` directory. Any file name ending in `.md` is fine, but we
+recommend naming it after the release, such as `0.10.0.md`
 
-```
+Then copy in the following YAML header (the part between the three dashes, ---):
+~~~
 ---
-title: Bitcoin Core version 0.9.0 released
+## Required value below populates the %v variable (note: % needs to be escaped in YAML if it starts a value)
+required_version: 0.10.0
+## Optional release date.  May be filled in hours/days after a release
+optional_date: 2015-02-16
+## Optional title.  If not set, default is: Bitcoin Core version %v released
+optional_title: Bitcoin Core version %v released
+## Optional magnet link.  To get it, open the torrent in a good BitTorrent client
+## and View Details, or install the transmission-cli Debian/Ubuntu package
+## and run: transmission-show -m <torrent file>
+#
+## Link should be enclosed in quotes and start with: "magnet:?
+optional_magnetlink:
+
+## The --- below ends the YAML header. After that, paste the release notes.
+## Warning: this site's Markdown parser commonly requires you make two
+## changes to the release notes from the Bitcoin Core source tree:
+##
+## 1. Make sure both ordered and unordered lists are preceeded by an empty
+## (whitespace only) line, like the empty line before this list item.
+##
+## 2. Place URLs inside angle brackets, like <http://bitcoin.org/bin>
+
 ---
+```
 
-Bitcoin Core v0.9.0 is now available for download at
-<https://bitcoin.org/bin/0.9.0/>
+Then start at the top of the YAML header and read the comments, filling
+in and replacing information as necessary, and then reformatting the
+release notes (if necessary) as described by the last lines of the YAML
+header.
 
-...
-```
-* `VERSION` is used to define the version and construct the URL. It should adhere to this format: `v0.3.24`.
-* `title: ...` will be used as the title.
-* `magnetlink: ...` (optional) the urlencoded torrent magnet link on the download page.
+Download links will automatically be set to the defaults using the current
+release version number, but if you need to change any download URL, edit
+the file `_templates/download.html`
+
+[Once Travis is enabled] You can then create a pull request to the
+master branch and Travis CI will automatically build it and make sure
+the links you provided return a "200 OK" HTTP header. (The actual files
+will not be downloaded to save bandwidth.) Alternatively, you can build
+the site locally with `make all` to run the same quality assurance tests.
+
+The file can be edited later to add any optional information (such as a
+release date) that you didn't have when you created the file.
 
 ### Alerts
 

_config.yml

@@ -122,6 +122,27 @@ redirects:
   /it/bitcoin-per-appassionati: /it/innovazione
   /nl/bitcoin-voor-liefhebbers: /nl/innovatie
   /pl/bitcoin-dla-entuzjastow: /pl/innowacje
+  ## Old releases pages; stop adding to this list after 0.8.2
+  /releases/2011/04/27/v0.3.21: /en/release/v0.3.21
+  /releases/2011/06/05/v0.3.22: /en/release/v0.3.22
+  /releases/2011/06/14/v0.3.23: /en/release/v0.3.23
+  /releases/2011/07/08/v0.3.24: /en/release/v0.3.24
+  /releases/2011/09/23/v0.4.0: /en/release/v0.4.0
+  /releases/2011/11/21/v0.5.0: /en/release/v0.5.0
+  /releases/2011/12/15/v0.5.1: /en/release/v0.5.1
+  /releases/2012/01/09/v0.5.2: /en/release/v0.5.2
+  /releases/2012/03/14/v0.5.3: /en/release/v0.5.3
+  /releases/2012/03/16/v0.5.3.1: /en/release/v0.5.3.1
+  /releases/2012/03/30/v0.6.0: /en/release/v0.6.0
+  /releases/2012/05/04/v0.6.1: /en/release/v0.6.1
+  /releases/2012/05/08/v0.6.2: /en/release/v0.6.2
+  /releases/2012/06/25/v0.6.3: /en/release/v0.6.3
+  /releases/2012/09/17/v0.7.0: /en/release/v0.7.0
+  /releases/2012/10/19/v0.7.1: /en/release/v0.7.1
+  /releases/2012/12/14/v0.7.2: /en/release/v0.7.2
+  /releases/2013/02/19/v0.8.0: /en/release/v0.8.0
+  /releases/2013/03/18/v0.8.1: /en/release/v0.8.1
+  /releases/2013/05/29/v0.8.2: /en/release/v0.8.2
 
 aliases:
   --author=Satoshi Nakamoto: Satoshi Nakamoto

_layouts/release.html

@@ -7,7 +7,7 @@
 ---
 <link rel="alternate" type="application/rss+xml" href="/en/rss/releases.rss" title="Bitcoin Core releases">
 <div class="versiontext">
-  <h1>{{ page.title }}<br><small>{{ page.date | date:"%e %B %Y" }}</small></h1>
+  <h1>{{ page.title }}{% if page.optional_date %}<br><small>{{ page.optional_date | date:"%e %B %Y" }}</small>{% endif %}</h1>
   {{ content }}
 </div>
 <a href="/en/version-history">Go back to the version history</a>

_plugins/liquid-die.rb

@@ -17,10 +17,12 @@ class LiquidDie < Liquid::Tag
 
     def initialize(tag_name, text, tokens)
       super
+      @error = text
     end
 
     def render(context)
-        abort("Liquid die tag called.  Dying...")
+        ## Produces: Liquid die tag called. [<Error.>] -- Error creating output [in <output file name>]
+        abort("Liquid die tag called. " + @error + " -- Error creating output" )
     end
   end
 end

_plugins/liquid-warn.rb

@@ -0,0 +1,31 @@
+# This file is licensed under the MIT License (MIT) available on
+# http://opensource.org/licenses/MIT.
+
+## liquid-warn.rb prints a warning to stdout (not stderr). This can allow
+## someone manually building the site (or reviewing logs) to detect a problem
+
+## Example:
+## {% if some_variable_is_set %}
+##     ...content...
+## {% else %}
+##     {% warn "Optional message" %}
+## {% endif %}
+
+module Jekyll
+
+  class LiquidWarn < Liquid::Tag
+
+    def initialize(tag_name, text, tokens)
+      super
+      @warning = text
+    end
+
+    def render(context)
+        ## Use "notice" instead of "warning" because we use grep to
+        ## treat some Jekyll warnings as errors
+        print "Notice: " + @warning + "\n"
+    end
+  end
+end
+
+Liquid::Template.register_tag('warn', Jekyll::LiquidWarn)

_plugins/releases.rb

@@ -5,46 +5,58 @@
 #and assign them the 'release' category.
 
 #This is later used to loop through site.pages in order
-#to display the release's list in chronological order, both
+#to display the release's list in version order, both
 #on the "Version history" page and RSS file.
 
-#This plugin also set site.DOWNLOAD_VERSION to the latest
-#available version of Bitcoin Core, which is used everywhere
-#in the download page.
-
-#Alias redirection pages are generated in /releases to avoid
-#breaking previous links in various websites.
+# This plugin also finds the highest required_version of
+# Bitcoin Core and populates the Download page with variables set in
+# that release file
 
 require 'yaml'
 
 module Jekyll
-  
+
   class ReleasePage < Page
 
-    def initialize(site, base, lang, srcdir, src, dstdir, dst, year, month, day)
+    def initialize(site, base, lang, srcdir, src, output_directory)
       @site = site
       @base = base
-      @dir = '/'+dstdir
-      @name = dst.gsub('.md','.html')
-      self.process(dst)
+      @dir = '/' + output_directory
+
+      ## Read in the file's YAML header
       self.read_yaml(File.join(base, srcdir), src)
+
+      ## Die if required_ variables aren't set
+      if self.data['required_version']
+        version = self.data['required_version']
+      else
+        abort("Error: Variable required_version not set when processing " + src)
+      end
+
+      ## Output file is v<version>.md (converted later to HTML)
+      output_file = "v" + version + ".md"
+      @name = output_file
+      self.process(output_file)
+
+      ## Title required for <title></title> in _layouts/base.html
+      self.data['title'] = self.data['optional_title'] ? self.data['optional_title'] : "Bitcoin Core version %v released"
+      self.data['title'].gsub!('%v', version)
+
+      ## For translation, but currently always set to "en"
       self.data['lang'] = lang
-      self.data['date'] = year + '-' + month + '-' + day
-      self.data['version'] = dst.gsub('.md','').gsub(/[a-z]/,'')
-      self.data['versionint'] = versiontoint(self.data['version'])
+
+      ## Only processes numeric version numbers with up to five decimals
+      self.data['versionint'] = versiontoint(self.data['required_version'])
+
       self.data['layout'] = 'release'
-      if dstdir.index('/releases/') === 0
-        self.data['redirect'] = '/en/release/' + dst.gsub('.md','')
-        self.data['layout'] = 'redirect'
-      else
-        self.data['category'] = 'release'
-        if !site.config.has_key?('DOWNLOAD_VERSION') or site.config['DOWNLOAD_VERSIONINT'] < self.data['versionint']
-          site.config['DOWNLOAD_VERSIONINT'] = self.data['versionint']
-          site.config['DOWNLOAD_VERSION'] = self.data['version']
-          site.config.delete('DOWNLOAD_MAGNETLINK') if site.config.has_key?('DOWNLOAD_MAGNETLINK')
-          site.config['DOWNLOAD_MAGNETLINK'] = self.data['magnetlink'] if self.data.has_key?('magnetlink')
-        end
-        site.pages << ReleasePage.new(site, base, lang, srcdir, src, '/releases/' + year + '/' + month + '/' + day, dst, year, month, day)
+      self.data['category'] = 'release'
+
+      ## If this is the highest version we've seen so far...
+      if !site.config.has_key?('DOWNLOAD_VERSION') or site.config['DOWNLOAD_VERSIONINT'] < self.data['versionint']
+        site.config['DOWNLOAD_VERSIONINT'] = self.data['versionint']
+        site.config['DOWNLOAD_VERSION'] = self.data['required_version']
+
+        site.config['DOWNLOAD_MAGNETLINK'] = self.data['optional_magnetlink'] ? self.data['optional_magnetlink'] : nil
       end
     end
 
@@ -73,18 +85,9 @@ def generate(site)
         next if file == '.' or file == '..'
         lang = 'en'
         src = file
-        dst = file.split('-')
-        next if dst.length < 4
-        year = dst.shift()
-        month = dst.shift()
-        day = dst.shift()
-        next if !/^[0-9]{4}$/.match(year)
-        next if !/^[0-9]{2}$/.match(month)
-        next if !/^[0-9]{2}$/.match(day)
-        dst = dst.join('-')
         srcdir = '_releases'
-        dstdir = lang + '/release'
-        site.pages << ReleasePage.new(site, site.source, lang, '_releases', src, dstdir, dst, year, month, day)
+        output_directory = lang + '/release'
+        site.pages << ReleasePage.new(site, site.source, lang, '_releases', src, output_directory)
       end
       #TODO releases are only generated for english language,
       #but they could also be translated at some point. They would however

_releases/2011-04-27-v0.3.21.md

@@ -1,5 +1,8 @@
 ---
-title: Bitcoin version 0.3.21 released
+## Please see _releases/0.10.0.md for a release template
+required_version: 0.3.21
+optional_date: 2011-04-27
+optional_title: Bitcoin version 0.3.21 released
 ---
 
 Binaries for Bitcoin version 0.3.21 are available at:

_releases/2011-06-05-v0.3.22.md

@@ -1,5 +1,8 @@
 ---
-title: Bitcoin version 0.3.22 released
+## Please see _releases/0.10.0.md for a release template
+required_version: 0.3.22
+optional_date: 2011-06-05
+optional_title: Bitcoin version 0.3.22 released
 ---
 
 Download URL: <http://sourceforge.net/projects/bitcoin/files/Bitcoin/bitcoin-0.3.22/>

_releases/2011-06-14-v0.3.23.md

@@ -1,5 +1,8 @@
 ---
-title: Bitcoin version 0.3.23 released
+## Please see _releases/0.10.0.md for a release template
+required_version: 0.3.23
+optional_date: 2011-06-14
+optional_title: Bitcoin version 0.3.23 released
 ---
 Win32, Linux, MacOSX and source releases for bitcoin v0.3.23 have been uploaded to
 <http://sourceforge.net/projects/bitcoin/files/Bitcoin/bitcoin-0.3.23/>

_releases/2011-07-08-v0.3.24.md

@@ -1,5 +1,8 @@
 ---
-title: Bitcoin version 0.3.24 released
+## Please see _releases/0.10.0.md for a release template
+required_version: 0.3.24
+optional_date: 2011-07-08
+optional_title: Bitcoin version 0.3.24 released
 ---
 [Full announcement (including signatures)](http://sourceforge.net/mailarchive/message.php?msg_id=27771039)
 

_releases/2011-09-23-v0.4.0.md

@@ -1,5 +1,8 @@
 ---
-title: Bitcoin version 0.4.0 released
+## Please see _releases/0.10.0.md for a release template
+required_version: 0.4.0
+optional_date: 2011-09-23
+optional_title: Bitcoin version 0.4.0 released
 ---
 [Full announcement (including signatures)](http://sourceforge.net/mailarchive/message.php?msg_id=28132490)
 

_releases/2011-11-21-v0.5.0.md

@@ -1,5 +1,8 @@
 ---
-title: Bitcoin-Qt version 0.5.0 released
+## Please see _releases/0.10.0.md for a release template
+required_version: 0.5.0
+optional_date: 2011-11-21
+optional_title: Bitcoin-Qt version 0.5.0 released
 ---
 Bitcoin-Qt version 0.5.0 is now available for download at:
   <http://sourceforge.net/projects/bitcoin/files/Bitcoin/bitcoin-0.5.0/>

_releases/2011-12-15-v0.5.1.md

@@ -1,5 +1,8 @@
 ---
-title: Bitcoin-Qt version 0.5.1 released
+## Please see _releases/0.10.0.md for a release template
+required_version: 0.5.1
+optional_date: 2011-12-15
+optional_title: Bitcoin-Qt version 0.5.1 released
 ---
 Bitcoin-Qt version 0.5.1 is now available for download at:
 <http://sourceforge.net/projects/bitcoin/files/Bitcoin/bitcoin-0.5.1/>

_releases/2012-01-09-v0.5.2.md

@@ -1,5 +1,8 @@
 ---
-title: Bitcoin-Qt version 0.5.2 released
+## Please see _releases/0.10.0.md for a release template
+required_version: 0.5.2
+optional_date: 2012-01-09
+optional_title: Bitcoin-Qt version 0.5.2 released
 ---
 Bitcoin-Qt version 0.5.2 is now available for download at:
 <http://sourceforge.net/projects/bitcoin/files/Bitcoin/bitcoin-0.5.2/>

_releases/2012-03-14-v0.5.3.md

@@ -1,5 +1,8 @@
 ---
-title: Bitcoin-Qt version 0.5.3 released
+## Please see _releases/0.10.0.md for a release template
+required_version: 0.5.3
+optional_date: 2012-03-14
+optional_title: Bitcoin-Qt version 0.5.3 released
 ---
 Bitcoin-Qt version 0.5.3 is now available for download at:
 <http://sourceforge.net/projects/bitcoin/files/Bitcoin/bitcoin-0.5.3/>

_releases/2012-03-16-v0.5.3.1.md

@@ -1,5 +1,8 @@
 ---
-title: Bitcoin-Qt version 0.5.3.1 released
+## Please see _releases/0.10.0.md for a release template
+required_version: 0.5.3.1
+optional_date: 2012-03-16
+optional_title: Bitcoin-Qt version 0.5.3.1 released
 ---
 Bitcoin-Qt version 0.5.3.1 for Windows is now available for download at:
 <http://sourceforge.net/projects/bitcoin/files/Bitcoin/bitcoin-0.5.3/>

_releases/2012-03-30-v0.6.0.md

@@ -1,5 +1,8 @@
 ---
-title: Bitcoin-Qt version 0.6.0 released
+## Please see _releases/0.10.0.md for a release template
+required_version: 0.6.0
+optional_date: 2012-03-30
+optional_title: Bitcoin-Qt version 0.6.0 released
 ---
 Bitcoin-Qt version 0.6.0 is now available for download at:
   <http://sourceforge.net/projects/bitcoin/files/Bitcoin/bitcoin-0.6.0/>