From b21bf33bcc6e3a0aa4eebd2256438cce8ae3caa2 Mon Sep 17 00:00:00 2001 From: "David A. Harding" Date: Tue, 14 Jul 2015 10:53:40 -0400 Subject: [PATCH] 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