Merge pull #962: Site Docs: Add Details To Alert Creation Process

README.md

@@ -538,34 +538,148 @@ is the particular version:
 
 ### Alerts
 
-Network alerts should be placed in `_alerts/YYYY-MM-DD-SHORTITLE.html` and adhere to this format:
+1. [Who to contact](#who-to-contact)
+2. [Basic alert](#basic-alert) (emergency fast instructions)
+3. [Detailed alert](#detailed-alert)
+4. [Clearing an alert](#clearing-an-alert)
 
-```
+#### Who to Contact
+
+The following people can publish alerts on Bitcoin.org.  Their email
+addresses are on the linked GitHub profiles.
+
+- Saïvann Carignan, [@saivann](https://github.com/saivann), saivann on Freenode
+- Dave Harding, [@harding](https://github.com/harding), harding on Freenode
+- Wladimir van der Laan, [@laanwj](https://github.com/laanwj), wumpus on Freenode
+- Theymos, [@theymos](https://github.com/theymos), theymos on Freenode
+
+Several of the above are only occasionally on Freenode.  Alert
+coordination is usually conducted in #bitcoin-dev on Freenode.
+
+#### Basic Alert
+
+1. Open your editor on a file named `_alerts/YYYY-MM-DD-short-title.md`
+   (the alert will appear as <https://bitcoin.org/en/alert/YYYY-MM-DD-short-title>).
+
+2. Paste the following text into the top of the file:
+
+    ```
+    ---
+    ## Title displayed on alert page
+    title: "11/12 March 2013 Chain Fork"
+    ## Short URL for use in P2P network alerts: https://bitcoin.org/<shorturl>
+    shorturl: "chainfork"
+    ## Active alerts will display the banner (below) on all bitcoin.org content pages
+    active: true
+    ## Banner displayed if 'active: true'.  Can use HTML formatting
+    banner: "<b>Chain fork</b> - Please stop mining on bitcoin version 0.8.0. Click here for more information."
+    ---
+
+    {% comment %}
+    First paragraph should indicate whose bitcoins are safe, to avoid
+    starting a panic.
+    {% comment %}
+
+    Your bitcoins are safe if you received them in transactions
+    confirmed before 2015-07-06 00:00 UTC.
+
+    {% comment %}
+    Second paragraph should summarize the problem, and subsequent
+    text should indicate what people should do immediately.
+    Consider: users (by wallet type), merchants, and miners.
+    {% comment %}
+
+    However, there has been a problem with a planned upgrade. For
+    bitcoins received later than the time above, confirmation scores are
+    significantly less reliable then they usually are for users of
+    certain software:
+
+    - Lightweight (SPV) wallet users should wait an additional 30
+      confirmations more than you would normally wait. Electrum users,
+      please see this note.
+    ```
+
+- Edit the file.  It is written in [Markdown format][].
+
+- Commit it.
+
+    - **Note:** the commit must be signed by one of the people in the
+      [Who to Contact](#who-to-contact) section for site
+      auto-building to work.
+
+- Push the commit to the master branch. Rebuilding the site occurs
+  automatically and takes 7 to 15 minutes.
+
+    - **Note:** do not push additional commits until the alert is
+      displayed on the live site.  The site build aborts and starts over
+      when new commits are found.
+
+- Give the `shorturl` URL (`bitcoin.org/<shorturl>`) to the P2P alert message
+  key holders to use in any alert messages they send.
+
+- Proceed to the next section to improve the alert.
+
+#### Detailed Alert
+
+In addition to providing more information about how users should respond
+to the situation, you can enhance the alert in several ways described
+below.
+
+The following fields may be defined in the the alert YAML header:
+
+```yaml
 ---
+## (Required; HTML text) Title displayed on alert page
 title: "11/12 March 2013 Chain Fork"
-alias: "chainfork"
+## (Optional; display ASCII only) Short URL for use in P2P network alerts: https://bitcoin.org/<shorturl>
+shorturl: "chainfork"
+## (Optional; default=false) Active alerts will display the banner (below) on all bitcoin.org content pages
 active: true
+## (Optional; HTML text) Banner displayed if 'active: true'.  Can use HTML formatting
 banner: "<b>Chain fork</b> - Please stop mining on bitcoin version 0.8.0. Click here for more information."
+## (Optional; default=alert) CSS class to set banner color
+##   alert = red  |  warning = orange  |  success = green  | info = blue
+bannerclass: alert
 ---
+```
 
-<p>
+The time of the last update should be placed on the page somewhere. UTC
-A chain fork is happening. Please stop mining on bitcoin version 0.8.0. Your bitcoins are safe but it is recommended that you postpone your Bitcoin transactions for the next hours.
+should be used for all dates, and RFC 2822 format ( date -uR ) is
-</p>
+recommended for long dates. For example, place the date in the footer of
-<p>
+the document:
-More information will follow.
+
-</p>
+```html
 <div style="text-align:right">
   <i>This notice last updated: Thu, 16 May 2013 01:37:00 UTC</i>
 </div>
-
 ```
-* `SHORTTITLE` is used to construct the URL.
+
-* `title: ...` will be used as the title in the layout.
+You may also want to create a page on the Wiki to allow anyone to
-* `alias: ...` (optional) a short alias for Bitcoin Core alerts. Ex. "dos" will produce /dos.html
+provide additional information.  If you do so, link to it from the
-* `active: ...` (true or false) define if the alert should appear as ongoing in the network status page.
+alert.
-* `banner: ...` (optional) a short text that will be displayed in an alert banner and link to the alert page.
+
-* `bannerclass: ...` (optional) a CSS class that sets the color of the banner. Possible values: alert (default red), warning (orange), success (green), info (blue).
+#### Clearing An Alert
-* `last updated: ...` should be kept up to date and be in RFC 2822 format ( date -uR ).
+
+To stop advertising an alert on every Bitcoin.org page, change the YAML
+header field `active` to *false*:
+
+```yaml
+## (Optional; default=false) Active alerts will display the banner (below) on all bitcoin.org content pages
+active: false
+```
+
+Alternatively, for a few days you can change the message and set the
+CSS `bannerclass` to *success* to indicate the problem has been resolved.
+
+```yaml
+## (Optional; HTML text) Banner displayed if 'active: true'.  Can use HTML formatting
+banner: "<b>Chain fork</b> - situation resolved"
+## (Optional; default=alert) CSS class to set banner color
+##   alert = red  |  warning = orange  |  success = green  | info = blue
+bannerclass: success
+```
+
+[markdown format]: https://help.github.com/articles/markdown-basics/
 
 ## Wallets
 

_alerts/2012-02-18-protocol-change.html

@@ -1,6 +1,6 @@
 ---
 title: "February 20, 2012 Protocol Changes"
-alias: "feb20"
+shorturl: "feb20"
 active: false
 banner: ""
 ---

_alerts/2012-03-16-critical-vulnerability.html

@@ -1,6 +1,6 @@
 ---
 title: "Potentially Critical Security Vulnerability"
-alias: "critfix"
+shorturl: "critfix"
 active: false
 banner: ""
 ---

_alerts/2012-05-14-dos.html

@@ -1,6 +1,6 @@
 ---
 title: "CVE-2012-2459: Critical Vulnerability (denial-of-service)"
-alias: "dos"
+shorturl: "dos"
 active: false
 banner: ""
 ---

_alerts/2013-03-11-chain-fork.html

@@ -1,6 +1,6 @@
 ---
 title: "11/12 March 2013 Chain Fork Information"
-alias: "chainfork"
+shorturl: "chainfork"
 active: false
 banner: ""
 ---

_alerts/2013-03-15-upgrade-deadline.html

@@ -1,6 +1,6 @@
 ---
 title: "15 May 2013 Upgrade Deadline"
-alias: "may15"
+shorturl: "may15"
 active: false
 banner: ""
 ---

_alerts/2013-08-11-android.html

@@ -1,7 +1,7 @@
 ---
 title: "Android Security Vulnerability"
 active: false
-alias: "android"
+shorturl: "android"
 banner: ""
 ---
 

_alerts/2014-04-11-heartbleed.html

@@ -1,6 +1,6 @@
 ---
 title: "OpenSSL Heartbleed vulnerability"
-alias: "heartbleed"
+shorturl: "heartbleed"
 active: false
 banner: ""
 ---

_alerts/2015-07-04-spv-mining.md

@@ -3,7 +3,7 @@
 ## http://opensource.org/licenses/MIT.
 
 title: "Some Miners Generating Invalid Blocks"
-alias: "spv-mining"
+shorturl: "spv-mining"
 active: false
 #banner: "WARNING: many wallets currently vulnerable to double-spending of confirmed transactions (click here to read)"
 bannerclass: "alert"

_plugins/alerts.rb

@@ -12,7 +12,7 @@
 #variable is set, allowing a clickable alert banner to be
 #displayed in _layouts/base.html .
 
-#If "alias" variable is set in one alert file, a short alias
+#If "shorturl" variable is set in one alert file, a short alias
 #file for the alert (like /android.html) is generated for
 #Bitcoin Core non-clickable alerts.
 
@@ -47,9 +47,9 @@ module Jekyll
         if self.data.has_key?('active') and !self.data['active'].nil? and self.data['active'] == true
           site.config['STATUS'] = 1
         end
-        if self.data.has_key?('alias')
+        if self.data.has_key?('shorturl')
-          site.pages << AlertPage.new(site, base, lang, srcdir, src, '', self.data['alias']+'.'+extension, date)
+          site.pages << AlertPage.new(site, base, lang, srcdir, src, '', self.data['shorturl']+'.'+extension, date)
-          site.pages << AlertPage.new(site, base, lang, srcdir, src, '', self.data['alias']+'/index.'+extension, date)
+          site.pages << AlertPage.new(site, base, lang, srcdir, src, '', self.data['shorturl']+'/index.'+extension, date)
         end
       end
     end