Merge pull request #741 from el00ruobuob/POC-Guides-Versioned

Guides Pages versionning

README.md

@@ -98,6 +98,41 @@ Contributers should use [issue keywords](https://help.github.com/articles/closin
 
 Pull requests allow others to make comments or review your changes to the site. We ask that you remain available to comment or make changes to your PR. Pull requests with pending changes for more than 30 days will be closed and need to be resubmitted in the future. Sometimes someone else's changes might make your changes conflict with the current site. If that happens you may need to rebase your PR. (If you're unsure about how to do so, you can reach out to other contributers on IRC (freenode #monero) and someone should be able to walk you through it.
 
+### 3.2 Updates on User Guides
+
+User guides and developer guides may need regular updates, either to fix typos, to add explanations regarding new features, to update screenshots, and so on.
+As those guides are translated in several languages, it could be hard to keep all languages version up to date with the English version.
+To keep track of those changes, guides are versioned using a snippet at the top of each localized (\_i18n/en/ressources/\*-guides) file:
+```
+{% assign version = '1.1.0' | split: '.' %}
+```
+This snippet is responsible for keeping track of the language version.
+
+The based version (English version) is however also tracked in the `Front Matter` from the /resources/user-guides/ or /resources/developer-guides/ directory file:
+```
+mainVersion:
+  - "1"
+  - "1"
+  - "0"
+```
+
+- First number is the Major version number
+- Second number is the Minor version number
+- Third number is the build number.
+
+When you update a guide, you are responsible for updating this version tracking in every file involved in your update:
+
+- For an update on English files, you will update the version tracking number in the `Front Matter` of /ressources/\*-guides/ and in \_i18n/en/ressources/\*-guides
+- For an update on localized files, you will update the version tracking number in the \_i18n/<local>/ressources/\*-guides only, and
+  - You will not update to a higher Major or Minor version number than the reference English guide
+  - If you want to update to a higher Major or Minor version number, you should update the English version accordingly so that English is always the highest Major.Minor version.
+
+And you will increment the version number in the following way:
+
+- Cosmetic change only (typo, rephrasing, screenshot update with exact same field names and positions): Increment the third number (build number). We do not want to even warn the user about this update in another language.
+- Changes that add instructions or explanations (or screenshot updates with different field names and positions), without making the old version misleading for users: Increment the second number (Minor version number) and reset the third to 0. We want to let the user know the English version could be more accurate and helpful to read.
+- Changes that makes the old version false, or misleading to users: Increment the first number (Major version number) and reset the second and third to 1.0. We want to discourage users from reading this too outdated version that could lead them to do wrong things (for instance, buy the wrong algo of mining power on nicehash, after a pow change).
+
 ## 4.0 How to make a blog post
 
 ### 4.1 Quick Start
@@ -138,8 +173,9 @@ You're all done. Submit a PR and wait for it to be reviewed and merged. Be sure
 * File content as in 5.3
 * Create file in /_i18n/en/resources/user-guides with the exact same filename as above ending in .md
 * Write User Guide
+* Add versioning snippet
 * Copy User Guide file to ALL LANGUAGES in /_i18n/[ALL LANGUAGES]/resources/user-guides
-* Paste `{% include untranslated.html %}` into the top of each language version of your User Guide, except the original language
+* set translation to false in the snippet the top of each language version of your User Guide, except the original language
 * Add guide using markdown in the correct category, and in alphabetic order, in ALL LANGUAGES to /_i18n/[ALL LANGUAGES]/resources/user-guides/index.md being careful not to mess with any indentation
 * Test/Build
 * Submit PR
@@ -153,6 +189,10 @@ Navigate to the /resources/user-guides folder and make a new file. Be sure the f
 layout: user-guide
 title: TITLE OF YOUR USER GUIDE
 permalink: /resources/user-guides/NAME-OF-FILE-GOES-HERE.html
+mainVersion:
+  - "1"
+  - "1"
+  - "0"
 ---
 
 {% tf resources/user-guides/NAME-OF-FILE-GOES-HERE.md %}
@@ -168,11 +208,18 @@ Write your user guide. Be succinct but thorough. Remember, people will be using
 
 The title should be at the top of the User Guide using a single `#` for an H1 tag. Titles will not be automatically put on these pages as with other pages. There should be NO front matter on this file.
 
+Add the version snippet at the top of your guide (before your title):
+```
+{% assign version = '1.1.0' | split: '.' %}
+{% include disclaimer.html translated="true" version=page.version %}
+```
+Your version should start at `1.1.0` as it is the first Major, first Minor, and no cosmetic changes have occured.
+
 ### 5.6 Copy User Guide file into all languages
 Copy your file and navigate to each language file in the /i18n folder. In each language folder (INCLUDING template) go to the resources/user-guides folder and paste your user guide (don't worry, you don't have to translate it) there. This is very important, and the site will not build if the file with the same name is not in each language folder.
 
-As you paste into each folder, open up the file and paste the following snippet at the top of the file (before your title):
-`{% include untranslated.html %}`. This does not need to be done in the original language that the User Guide was written in.
+As you paste into each folder, open up the file and edit the snippet at the top of the file (before your title) to mark it untranslated:
+`{% include disclaimer.html translated="false" version=page.version %}`. This does not need to be done in the original language that the User Guide was written in.
 
 ### 5.7 Add Guide to the 'User Guide' landing page of EACH LANGUAGE
 In the /_i18n/[ORIGINAL LANGUAGE OF USER GUIDE]/resources/user-guides folder, find the file labeled index.md and open it.
@@ -519,8 +566,8 @@ Go to the /i18n folder and find the two letter code for the language you wish to
 ### 14.3 Translate the file
 Here you can do your translation. Depending on the page, you may have to maneuver around some HTML or markdown. In general, anything between two tags (such as `<p>TRANSLATE THIS</p>`) should be fine. Testing is VERY important, so do NOT skip step 13.4. If during testing, the page appears different from the original English page (besides the translated text of course), you did something wrong and may have to start again.
 
-### 14.4 Remove the 'untranslated' snippet
-Somewhere on the page (usually the top) should be a snippet that says `{% include untranslated.html %}`. Simply delete this completely from the file. This will remove the orange bar from the bottom saying the page is untranslated.
+### 14.4 set the 'translated' snippet to true
+Somewhere on the page (usually the top) should be a snippet that says `{% include disclaimer.html translated="false" version=page.version %}`. Simply change this to `{% include disclaimer.html translated="true" version=page.version %}`. This will remove the orange bar from the bottom saying the page is untranslated.
 
 ### 14.5 Build/Test
 Build your website using `jekyll serve` if it's not rebuilding automatically.

_i18n/en.yml

@@ -21,6 +21,9 @@ global:
   privacy: Privacy
   copyright: Copyright
   untranslated: This page is not yet translated. If you would like to help translate it, please see the
+  outdatedMax: This page is outdated. We do not recommend using it. Instead, please see the
+  outdatedVersion: english version
+  outdatedMin: This page has been updated since the translation. You can use this version, but it may be incomplete.
 
 titles:
   index: Home

_i18n/en/resources/developer-guides/daemon-rpc.md

+{% assign version = '2.1.0' | split: '.' %}
+{% include disclaimer.html translated="true" version=page.version %}
 ## Introduction
 
 This is a list of the monerod daemon RPC calls, their inputs and outputs, and examples of each.

_i18n/en/resources/developer-guides/wallet-rpc.md

+{% assign version = '1.2.0' | split: '.' %}
+{% include disclaimer.html translated="true" version=page.version %}
 ## Introduction
 
 This is a list of the monero-wallet-rpc calls, their inputs and outputs, and examples of each. The program monero-wallet-rpc replaced the rpc interface that was in simplewallet and then monero-wallet-cli.
@@ -1234,7 +1236,7 @@ $ curl -X POST http://localhost:18082/json_rpc -d '{"jsonrpc":"2.0","id":"0","me
   }
 }
 ```
-    
+
 
 ### **rescan_spent**
 

_i18n/en/resources/user-guides/How-to-mine-Monero-XMR-without-a-mining-equipment.md

+{% assign version = '1.1.0' | split: '.' %}
+{% include disclaimer.html translated="true" version=page.version %}
 ## How to mine Monero (XMR) without a mining equipment?
 
 If you don’t have a profitable mining equipment, nor time or

_i18n/en/resources/user-guides/Offline_Backup.md

+{% assign version = '1.1.0' | split: '.' %}
+{% include disclaimer.html translated="true" version=page.version %}
 ## Operating Systems:  Various versions of Linux and Windows 7, 8
- 
+
 ### Wallet Software:  Simplewallet
- 
+
 #### Resource for Creating Bootable Disks:  [Linux](http://www.pendrivelinux.com/),       [Windows](https://www.microsoft.com/en-us/download/windows-usb-dvd-download-tool)
- 
+
 #### Resource for Monero Binaries:  [Monero Binaries](https://getmonero.org/downloads/)
- 
+
 - Take any computer you have lying around, even your normal workstation. You may find it easier to use an older computer that has no wifi or bluetooth if you're particularly paranoid
- 
+
 - Create a Linux or Windows bootable disk, and make sure you have the Monero binaries on the same disk or on a second disk (for Linux make sure you have also downloaded copies of the dependencies you will need, libboost1.55 and miniupnpc for instance)
- 
+
 - Disconnect the network and/or Internet cables from your computer, physically remove the wifi card or switch the wifi/bluetooth off on a laptop if possible
- 
+
 - Boot into your bootable OS, install the dependencies if necessary
- 
+
 - Copy the Monero binaries to a RAM disk (/dev/shm in Linux, Windows bootable ISOs normally have a Z: drive or something)
- 
+
 - Don't run the Monero daemon. Instead, using the command line, use monero-wallet-cli to create a new Monero @account
- 
+
 - When prompted for a name, give it any name, it doesn't really matter
- 
+
 - When prompted for a password, type in like 50 - 100 random characters. Don't worry that you don't know the password, just make it LONG
- 
+
 - **CRITICAL STEP**: Write down (on paper) your 25 word @mnemonic-seed  
 **WARNING**:  If you forget to write down this information your funds may be lost forever
- 
+
 - Write down (on your phone, on paper, on another computer, wherever you want) your address and view key
- 
+
 - Switch off the computer, remove the battery if there is one, and leave it physically off for a few hours
- 
+
 The account you've created was created in RAM, and the digital files are now inaccessible. If some adversary manages to somehow obtain the data, they will lack the long password to open it. If you need to receive payments, you have your public address, and you have the view key if needed. If you need access to it, you have your 25 word @mnemonic-seed, and you can now write out several copies of it, including an offsite copy (e.g. a bank deposit box).
- 
+
 Credit:  Riccardo Spagni
- 
+
 Related:  [Offline Account Generator](http://moneroaddress.org/)

_i18n/en/resources/user-guides/cli_wallet_daemon_isolation_qubes_whonix.md

+{% assign version = '1.1.0' | split: '.' %}
+{% include disclaimer.html translated="true" version=page.version %}
 # CLI Wallet/Daemon Isolation with Qubes + Whonix
 
 With [Qubes](https://qubes-os.org) + [Whonix](https://whonix.org) you can have a Monero wallet that is without networking and running on a virtually isolated system from the Monero daemon which has all of its traffic forced over [Tor](https://torproject.org).
@@ -7,7 +9,7 @@ Qubes gives the flexibility to easily create separate VMs for different purposes
 This is safer than other approaches which route the wallets rpc over a Tor hidden service, or that use physical isolation but still have networking to connect to the daemon. In this way you don't need any network connection on the wallet, you preserve resources of the Tor network, and there is less latency.
 
 
-## 1. [Create Whonix AppVMs](https://www.whonix.org/wiki/Qubes/Install): 
+## 1. [Create Whonix AppVMs](https://www.whonix.org/wiki/Qubes/Install):
 
 + Using a Whonix workstation template, create two workstations as follows:
 
@@ -15,14 +17,14 @@ This is safer than other approaches which route the wallets rpc over a Tor hidde
 
   - The second workstation will be for the `monerod` daemon, it will be referred to as `monerod-ws`. You will have `NetVM` set to the Whonix gateway `sys-whonix`.
 
-## 2. In the AppVM `monerod-ws`: 
+## 2. In the AppVM `monerod-ws`:
 
 + Download, verify, and install Monero software.
 
 ```
 [email protected]:~$ curl -O "https://downloads.getmonero.org/cli/monero-linux-x64-v0.11.1.0.tar.bz2" -O "https://getmonero.org/downloads/hashes.txt"
 [email protected]:~$ gpg --recv-keys BDA6BD7042B721C467A9759D7455C5E3C0CDCEB9
-[email protected]:~$ gpg --verify hashes.txt 
+[email protected]:~$ gpg --verify hashes.txt
 gpg: Signature made Wed 01 Nov 2017 10:01:41 AM UTC
 gpg:                using RSA key 0x55432DF31CCD4FCD
 gpg: Good signature from "Riccardo Spagni <[email protected]>" [unknown]

_i18n/en/resources/user-guides/create_wallet.md

+{% assign version = '1.1.0' | split: '.' %}
+{% include disclaimer.html translated="true" version=page.version %}
 ### Operating Systems:  Ubuntu
 
 - Download the [official binaries](https://getmonero.org/downloads/) or compile the last source available on [Github](https://github.com/monero-project/bitmonero)
@@ -31,7 +33,7 @@
 ![image12](https://github.com/luuul/monero-site/blob/master/knowledge-base/user-guides/png/create_wallet/12.png)
 
 - Enter the name you want for your portfolio and follow the instructions from the terminal
- 
+
 ![image13](https://github.com/luuul/monero-site/blob/master/knowledge-base/user-guides/png/create_wallet/13.png)
 ![image14](https://github.com/luuul/monero-site/blob/master/knowledge-base/user-guides/png/create_wallet/14.png)
 ![image15](https://github.com/luuul/monero-site/blob/master/knowledge-base/user-guides/png/create_wallet/15.png)

_i18n/en/resources/user-guides/easiest_buy.md

+{% assign version = '1.1.0' | split: '.' %}
+{% include disclaimer.html translated="true" version=page.version %}
 ## How to obtain Monero
 
 This is a guide to obtain your own Monero as of 20150919. This is perhaps the easiest way to purchase and hold Monero.
@@ -8,7 +10,7 @@ There are many ways to buy Bitcoin. Perhaps the easiest way is through circle.co
 
 ####Step 2: Set up a mymonero.com account
 
-MyMonero.com is an online wallet for Monero, maintained by Monero Core Developer Ricardo Spagni (fluffpony). It is the easiest wallet to use. Simply go to MyMonero.com and click on the "Create an Account" button. 
+MyMonero.com is an online wallet for Monero, maintained by Monero Core Developer Ricardo Spagni (fluffpony). It is the easiest wallet to use. Simply go to MyMonero.com and click on the "Create an Account" button.
 
 ![image1](https://github.com/luuul/monero-site/blob/master/knowledge-base/user-guides/png/easiest_way/01.png)
 

_i18n/en/resources/user-guides/howto_fix_stuck_funds.md

+{% assign version = '1.1.0' | split: '.' %}
+{% include disclaimer.html translated="true" version=page.version %}
 Sometimes, your funds will become stuck - you will have some locked funds that never become unlocked. This is how you fix it.
 
 - Load your wallet in monero-wallet-cli.

_i18n/en/resources/user-guides/importing_blockchain.md

+{% assign version = '1.1.0' | split: '.' %}
+{% include disclaimer.html translated="true" version=page.version %}
 # Importing the Blockchain to Monero GUI wallet (Windows)
 
 ### Step 1
@@ -14,7 +16,7 @@ Your path may be different depending on where you decided to download your walle
 
 ### Step 3
 
-Find the path of your downloaded Blockchain for example mine was: 
+Find the path of your downloaded Blockchain for example mine was:
 
 `C:\Users\KeeJef\Downloads\blockchain.raw`
 
@@ -28,7 +30,7 @@ Open a Command Prompt window. You can do this by pressing the Windows key + R, a
 
 Now you need to navigate using the CMD window to the path of your Monero wallet. You can do this by typing:
 
-`cd C:\YOUR\MONERO\WALLET\FILE\PATH\HERE` 
+`cd C:\YOUR\MONERO\WALLET\FILE\PATH\HERE`
 
 It should look something like:
 
@@ -50,7 +52,7 @@ If you downloaded the Blockchain from a trusted, reputable source you may set `v
 
 ### Step 7
 
-After the the Blockchain has finished syncing up you can open your Monero wallet normally. Your downloaded blockchain.raw can be deleted. 
+After the the Blockchain has finished syncing up you can open your Monero wallet normally. Your downloaded blockchain.raw can be deleted.
 
 
 Author: Kee Jefferys

_i18n/en/resources/user-guides/mine-to-pool.md

+{% assign version = '1.1.0' | split: '.' %}
+{% include disclaimer.html translated="true" version=page.version %}
 # Selecting a pool
 
 There are many pools to choose from, a list is available at

_i18n/en/resources/user-guides/mining_with_xmrig_and_docker.md

+{% assign version = '1.1.0' | split: '.' %}
+{% include disclaimer.html translated="true" version=page.version %}
 ## Introduction
 
 This guide is two fold, ease of use for mining on Linux distributions and some extra security around mining as most of these miners have not had security auditing.
@@ -19,7 +21,7 @@ For distribution specific installation please refer to the [Docker Docs](https:/
 
 ### Why XMRig
 
-[XMRig](https://github.com/xmrig/xmrig) is just a really solid miner to me. Nice output and statistics, no flashy web-ui's or dependencies. The XMRig container is only ~4MB what makes it extremely portable. 
+[XMRig](https://github.com/xmrig/xmrig) is just a really solid miner to me. Nice output and statistics, no flashy web-ui's or dependencies. The XMRig container is only ~4MB what makes it extremely portable.
 
 #### Step 1: Mining with XMRig
 

_i18n/en/resources/user-guides/monero-wallet-cli.md

+{% assign version = '1.1.0' | split: '.' %}
+{% include disclaimer.html translated="true" version=page.version %}
 # monero-wallet-cli
 
 `monero-wallet-cli` is the wallet software that ships with the Monero tree. It is a console program,
@@ -21,7 +23,7 @@ balance without refreshing:
 
     balance
     Balance: 64.526198850000, unlocked balance: 44.526198850000, including unlocked dust: 0.006198850000
-    
+
 In this example, `Balance` is your total balance. The `unlocked balance` is the amount currently available to spend. Newly received transactions require 10 confirmations on the blockchain before being unlocked. `unlocked dust` refers to very small amounts of unspent outputs that may have accumulated in your account.
 
 ## Sending monero

_i18n/en/resources/user-guides/monero_tools.md

+{% assign version = '1.1.0' | split: '.' %}
+{% include disclaimer.html translated="true" version=page.version %}
 # Monero tools
 
-These tools can be used to gain information about the Monero network or your transaction data in the blockchain. 
+These tools can be used to gain information about the Monero network or your transaction data in the blockchain.
 
 ### [Check that a recipient has received your funds](http://xmrtests.llcoins.net/checktx.html)
 

_i18n/en/resources/user-guides/prove-payment.md

+{% assign version = '1.1.0' | split: '.' %}
+{% include disclaimer.html translated="true" version=page.version %}
 ### Prove payments
 
 When you send money to a party who then disputes the payment was made, you need to be able to prove the payment was made.

_i18n/en/resources/user-guides/remote_node_gui.md

+{% assign version = '1.1.0' | split: '.' %}
+{% include disclaimer.html translated="true" version=page.version %}
 ## Finding a node
 First things first, you need to find a node to connect to! [moneroworld.com](https://moneroworld.com/#nodes) has some great resources for finding nodes. One of the easiest methods
 would be to use a node run by moneroworld, but they have a tool for finding random nodes too.

_i18n/en/resources/user-guides/restore_account.md

+{% assign version = '1.1.0' | split: '.' %}
+{% include disclaimer.html translated="true" version=page.version %}
 ## Operating Systems:  Windows, Linux, Mac
 
 - Retrieve your 25 word @mnemonic-seed that you saved when creating your old Monero @wallet

_i18n/en/resources/user-guides/restore_from_keys.md

+{% assign version = '1.1.0' | split: '.' %}
+{% include disclaimer.html translated="true" version=page.version %}
 ### Restoring from keys
 
 Restoring a wallet from private keys is pretty simple. If you have the necessary information, with this guide you can completely restore your wallet. Note: you do NOT have to have your password to restore from keys.

_i18n/en/resources/user-guides/securely_purchase.md

+{% assign version = '1.1.0' | split: '.' %}
+{% include disclaimer.html translated="true" version=page.version %}
 ## How to purchase Monero and securely store it.
 
-This is a guide to purchase and securely store Monero as of June 2017. 
+This is a guide to purchase and securely store Monero as of June 2017.
 
 #### Step 1: Buy Bitcoin
 
@@ -8,9 +10,9 @@ There are many ways to buy Bitcoin. Two semi-reliable companies at this time are
 
 #### Step 2: Download and create a Paper Wallet on a secure and air-gapped computer.
 
-Download the paper wallet generator at: https://moneroaddress.org and copy it to a USB stick (Direct link: https://github.com/moneromooo-monero/monero-wallet-generator/archive/master.zip). 
+Download the paper wallet generator at: https://moneroaddress.org and copy it to a USB stick (Direct link: https://github.com/moneromooo-monero/monero-wallet-generator/archive/master.zip).
 
-Unzip and open the paper wallet generator (monero-wallet-generator.html) into a web browser on an air-gapped computer that hasn't been used before, or has had a clean installation of the OS. 
+Unzip and open the paper wallet generator (monero-wallet-generator.html) into a web browser on an air-gapped computer that hasn't been used before, or has had a clean installation of the OS.
 
 Your paper wallet will have four important items: