From b21bf33bcc6e3a0aa4eebd2256438cce8ae3caa2 Mon Sep 17 00:00:00 2001 From: "David A. Harding" Date: Tue, 14 Jul 2015 10:53:40 -0400 Subject: [PATCH 1/2] Site Docs: Add Details To Alert Creation Process Closes #934 [skip ci] --- README.md | 146 ++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 130 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 15fe83f3..a064a58a 100644 --- a/README.md +++ b/README.md @@ -535,34 +535,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 ). + +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/ + alias: "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: "Chain fork - 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 `alias` URL (`bitcoin.org/`) 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" +## (Optional; display ASCII only) Short URL for use in P2P network alerts: https://bitcoin.org/ alias: "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: "Chain fork - 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 --- +``` -

-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. -

-

-More information will follow. -

+The time of the last update should be placed on the page somewhere. UTC +should be used for all dates, and RFC 2822 format ( date -uR ) is +recommended for long dates. For example, place the date in the footer of +the document: + +```html
This notice last updated: Thu, 16 May 2013 01:37:00 UTC
- ``` -* `SHORTTITLE` is used to construct the URL. -* `title: ...` will be used as the title in the layout. -* `alias: ...` (optional) a short alias for Bitcoin Core alerts. Ex. "dos" will produce /dos.html -* `active: ...` (true or false) define if the alert should appear as ongoing in the network status page. -* `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). -* `last updated: ...` should be kept up to date and be in RFC 2822 format ( date -uR ). + +You may also want to create a page on the Wiki to allow anyone to +provide additional information. If you do so, link to it from the +alert. + +#### Clearing An Alert + +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: "Chain fork - 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 From ec6c93e224a43ec4dc03040fdd6e1e5ff30b8393 Mon Sep 17 00:00:00 2001 From: "David A. Harding" Date: Sat, 25 Jul 2015 10:10:02 -0400 Subject: [PATCH 2/2] Alerts: Change 'Alias' Field To 'Shorturl' MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Suggested by Saïvann (thanks!) --- README.md | 12 ++++++------ _alerts/2012-02-18-protocol-change.html | 2 +- _alerts/2012-03-16-critical-vulnerability.html | 2 +- _alerts/2012-05-14-dos.html | 2 +- _alerts/2013-03-11-chain-fork.html | 2 +- _alerts/2013-03-15-upgrade-deadline.html | 2 +- _alerts/2013-08-11-android.html | 2 +- _alerts/2014-04-11-heartbleed.html | 2 +- _alerts/2015-07-04-spv-mining.md | 2 +- _plugins/alerts.rb | 8 ++++---- 10 files changed, 18 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index a064a58a..7164a3ba 100644 --- a/README.md +++ b/README.md @@ -556,7 +556,7 @@ 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 ). + (the alert will appear as ). 2. Paste the following text into the top of the file: @@ -564,8 +564,8 @@ coordination is usually conducted in #bitcoin-dev on Freenode. --- ## Title displayed on alert page title: "11/12 March 2013 Chain Fork" - ## Short URL for use in P2P network alerts: https://bitcoin.org/ - alias: "chainfork" + ## Short URL for use in P2P network alerts: https://bitcoin.org/ + 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 @@ -611,7 +611,7 @@ coordination is usually conducted in #bitcoin-dev on Freenode. displayed on the live site. The site build aborts and starts over when new commits are found. -- Give the `alias` URL (`bitcoin.org/`) to the P2P alert message +- Give the `shorturl` URL (`bitcoin.org/`) to the P2P alert message key holders to use in any alert messages they send. - Proceed to the next section to improve the alert. @@ -628,8 +628,8 @@ The following fields may be defined in the the alert YAML header: --- ## (Required; HTML text) Title displayed on alert page title: "11/12 March 2013 Chain Fork" -## (Optional; display ASCII only) Short URL for use in P2P network alerts: https://bitcoin.org/ -alias: "chainfork" +## (Optional; display ASCII only) Short URL for use in P2P network alerts: https://bitcoin.org/ +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 diff --git a/_alerts/2012-02-18-protocol-change.html b/_alerts/2012-02-18-protocol-change.html index 803ff2d8..cc95153d 100644 --- a/_alerts/2012-02-18-protocol-change.html +++ b/_alerts/2012-02-18-protocol-change.html @@ -1,6 +1,6 @@ --- title: "February 20, 2012 Protocol Changes" -alias: "feb20" +shorturl: "feb20" active: false banner: "" --- diff --git a/_alerts/2012-03-16-critical-vulnerability.html b/_alerts/2012-03-16-critical-vulnerability.html index 27da905a..8ef6b867 100644 --- a/_alerts/2012-03-16-critical-vulnerability.html +++ b/_alerts/2012-03-16-critical-vulnerability.html @@ -1,6 +1,6 @@ --- title: "Potentially Critical Security Vulnerability" -alias: "critfix" +shorturl: "critfix" active: false banner: "" --- diff --git a/_alerts/2012-05-14-dos.html b/_alerts/2012-05-14-dos.html index 1a4715af..88cb8855 100644 --- a/_alerts/2012-05-14-dos.html +++ b/_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: "" --- diff --git a/_alerts/2013-03-11-chain-fork.html b/_alerts/2013-03-11-chain-fork.html index c3ec6439..6ef31653 100644 --- a/_alerts/2013-03-11-chain-fork.html +++ b/_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: "" --- diff --git a/_alerts/2013-03-15-upgrade-deadline.html b/_alerts/2013-03-15-upgrade-deadline.html index 585a8c5e..06f98ff5 100644 --- a/_alerts/2013-03-15-upgrade-deadline.html +++ b/_alerts/2013-03-15-upgrade-deadline.html @@ -1,6 +1,6 @@ --- title: "15 May 2013 Upgrade Deadline" -alias: "may15" +shorturl: "may15" active: false banner: "" --- diff --git a/_alerts/2013-08-11-android.html b/_alerts/2013-08-11-android.html index 29d4b4a5..79175222 100644 --- a/_alerts/2013-08-11-android.html +++ b/_alerts/2013-08-11-android.html @@ -1,7 +1,7 @@ --- title: "Android Security Vulnerability" active: false -alias: "android" +shorturl: "android" banner: "" --- diff --git a/_alerts/2014-04-11-heartbleed.html b/_alerts/2014-04-11-heartbleed.html index b63d11a4..50b98e26 100644 --- a/_alerts/2014-04-11-heartbleed.html +++ b/_alerts/2014-04-11-heartbleed.html @@ -1,6 +1,6 @@ --- title: "OpenSSL Heartbleed vulnerability" -alias: "heartbleed" +shorturl: "heartbleed" active: false banner: "" --- diff --git a/_alerts/2015-07-04-spv-mining.md b/_alerts/2015-07-04-spv-mining.md index 5824734c..a806e0ee 100644 --- a/_alerts/2015-07-04-spv-mining.md +++ b/_alerts/2015-07-04-spv-mining.md @@ -1,6 +1,6 @@ --- 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" diff --git a/_plugins/alerts.rb b/_plugins/alerts.rb index 770fdd42..3a7f5ee5 100644 --- a/_plugins/alerts.rb +++ b/_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') - 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['alias']+'/index.'+extension, date) + if self.data.has_key?('shorturl') + 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['shorturl']+'/index.'+extension, date) end end end