Improve style consistency in root directory docs files (Chia-Network#…

…4493)

* Improve style consistency

* black python required blank

Co-authored-by: Nikolaj Kuntner <>

BUILD_TIMELORD.md

@@ -12,14 +12,14 @@ the virtual environment.
 sh install-timelord.sh
 ```
 
-If the compile fails, it's likely due to a missing dependency.
+If the compile fails, it's likely due to a missing dependency. The script
 [install-timelord.sh](https://github.com/Chia-Network/chia-blockchain/blob/main/install-timelord.sh)
 attempts to install required build dependencies for Linux and MacOS before
 invoking pip to build from the source python distribution of chiavdf.
 
 The `install-timelord.sh` install script leverages two environmental variables
-that the chiavdf wheels can use to specify how to build. `vdf_client` is the
-service that the Timelord uses to run the VDF and prove the Proof of Time.
+that the chiavdf wheels can use to specify how to build. The service that the
+Timelord uses to run the VDF and prove the Proof of Time is `vdf_client` and
 `vdf_bench` is a utility to get a sense of a given CPU's iterations per second.
 
 - To build vdf_client set the environment variable BUILD_VDF_CLIENT to "Y".

CONTRIBUTING.md

@@ -1,12 +1,11 @@
 # Introduction
 
-
 Welcome to the chia-blockchain project!
 We are happy that you are taking a look at the code for Chia, a proof of space and time cryptocurrency.
 
 A lot of fascinating new cryptography and blockchain concepts are used and implemented here.
 This repo includes the code for the Chia full node, farmer, and timelord (in chia folder), which are all written in python.
-It also includes a verifiable delay function implementation that it imports from the [chiavdf repo](https://github.com/Chia-Network/chiavdf) (in c/c++), and a proof of space implementation that it imports from the [chiapos repo](https://github.com/Chia-Network/chiapos). BLS signatures are imported from the [bls-signatures repo](https://github.com/Chia-Network/bls-signatures) as blspy. There is an additional dependency on the [chiabip158 repo](https://github.com/Chia-Network/chiabip158). For major platforms, binary and source wheels are shipped to PyPI from each dependent repo and then chia-blockchain can pip install those from PyPI or they can be prepackaged as is done for the Windows installer. On unsupported platforms, pip will fall back to the source distributions to be compiled locally.
+It also includes a verifiable delay function implementation that it imports from the [chiavdf repo](https://github.com/Chia-Network/chiavdf) (in c/c++), and a proof of space implementation that it imports from the [chiapos repo](https://github.com/Chia-Network/chiapos). BLS signatures are imported from the [bls-signatures repo](https://github.com/Chia-Network/bls-signatures) as blspy. There is an additional dependency on the [chiabip158 repo](https://github.com/Chia-Network/chiabip158). For major platforms, binary and source wheels are shipped to PyPI from each dependent repo. Then chia-blockchain can pip install those from PyPI or they can be prepackaged as is done for the Windows installer. On unsupported platforms, pip will fall back to the source distributions, to be compiled locally.
 
 If you want to learn more about this project, read the [wiki](https://github.com/Chia-Network/chia-blockchain/wiki), or check out the [green paper](https://www.chia.net/assets/ChiaGreenPaper.pdf).
 
@@ -17,16 +16,16 @@ Please review this [diagram](https://drive.google.com/file/d/1r7AXTrj7gtD0Xy-9Bt
 We would be pleased to accept code contributions to this project.
 As we have now released, the main priority is improving the mainnet blockchain.
 You can visit our [Trello project board](https://trello.com/b/ZuNx7sET) to get a sense of what is in the backlog.
-Generally things to the left are in progress or done. Some things go through "Coming up soon" but some will come directly out of other columns.
-Usually the things closer to the top of each column are the ones that will be worked on soonest.
+Generally, things to the left are in progress or done. Some things go through "Coming up soon", but some will come directly out of other columns.
+Usually, the things closer to the top of each column are the ones that will be worked on soonest.
 If you are interested in cryptography, math, or just like hacking in python, there are many interesting problems to work on.
-Contact any of the team members on [Keybase](https://keybase.io/team/chia_network.public), which we use as the main communication method and you can comment on any Trello card.
+Contact any of the team members on [Keybase](https://keybase.io/team/chia_network.public), which we use as the main communication method. You can also comment on any Trello card.
 
 We ask that external contributors create a fork of the `main` branch for any feature work they wish to take on.
 
 Members of the Chia organization may create feature branches from the `main` branch.
 
-In the event an emergency fix is required for the release version of Chia, members of the chia organization will create a feature branch from the current release branch `1.0.0`
+In the event an emergency fix is required for the release version of Chia, members of the Chia organization will create a feature branch from the current release branch `1.0.0`.
 
 ## Branching Strategy
 
@@ -35,19 +34,19 @@ In the event an emergency fix is required for the release version of Chia, membe
 1. All changes go into the main branch.
 2. Main is stable at all times, all tests pass.
 3. Features (with tests) are developed and fully tested on feature branches, and reviewed before landing in main.
-4. Chia Network's nodes on the public testnet are running latest version x.y.z
+4. Chia Network's nodes on the public testnet are running the latest version `x.y.z`.
 5. The `main` branch will have a long running `beta testnet` to allow previewing of changes.
-6. Pull Request events may require a `beta testnet` review environment, at the moment this is at the discretion of the reviewer.
-7. Hotfixes land in the release branch they fix, and all later versions. (this will be achieved by regularly merging from 1.0.x -> main).
-8. Hotfixes that are emergency fixes for a specific version will be merged into, and removed from down-stream branches. This allows future merges without issues.
+6. Pull Request events may require a `beta testnet` review environment. At the moment this is at the discretion of the reviewer.
+7. Hotfixes land in the release branch they fix, and all later versions. (This will be achieved by regularly merging from `1.0.x` to main).
+8. Hotfixes that are emergency fixes for a specific version will be merged into (???), and removed from down-stream branches. This allows future merges without issues.
 9. Whoever develops a hotfix is also responsible for merging it into all later branches.
-10. A release branch (e.g. 1.1.x) will be cut prior to a release, in order to separate work that should go into the release from work going into the next major release (main branch). (this pre-release branch will also have a `beta testnet` spun up for preview)
-11. All Merge events will be squashed and merged.
+10. A release branch (e.g. `1.1.x`) will be cut prior to a release, in order to separate work that should go into the release from work going into the next major release (main branch). (This pre-release branch will also have a `beta testnet` spun up for preview).
+11. All Merge events will be squash merged.
 
 ## Run tests and linting
 
 The first time the tests are run, BlockTools will create and persist many plots. These are used for creating
-proofs of space during testing. The next time tests are run, this won't be necessary.
+proofs of space during testing. The next time tests are run, this will not be necessary.
 
 ```bash
 . ./activate
@@ -56,20 +55,21 @@ black chia tests && mypy chia tests && flake8 chia tests
 py.test tests -v --durations 0
 ```
 
-Black is used as an automatic style formatter to make things easier, and flake8 helps ensure consistent style.
-Mypy is very useful for ensuring objects are of the correct type, so try to always add the type of the return value, and the type of local variables.
+The [black library](https://black.readthedocs.io/en/stable/) is used as an automatic style formatter to make things easier.
+The [flake8 library](https://readthedocs.org/projects/flake8/) helps ensure consistent style.
+The [Mypy library](https://mypy.readthedocs.io/en/stable/) is very useful for ensuring objects are of the correct type, so try to always add the type of the return value, and the type of local variables.
 
-If you want verbose logging for tests, edit the tests/pytest.ini file.
+If you want verbose logging for tests, edit the `tests/pytest.ini` file.
 
 ## Configure VS code
 
-1. Install Python extension
-2. Set the environment to ./venv/bin/python
+1. Install python extension
+2. Set the environment to `./venv/bin/python`
 3. Install mypy plugin
 4. Preferences > Settings > Python > Linting > flake8 enabled
 5. Preferences > Settings > Python > Linting > mypy enabled
 6. Preferences > Settings > Formatting > Python > Provider > black
-7. Preferences > Settings > mypy > Targets: set to ./chia and ./tests
+7. Preferences > Settings > mypy > Targets: set to `./chia` and `./tests`
 
 ## Configure Pycharm
 
@@ -93,13 +93,13 @@ Following the release of `1.1.0`, the official `testnet` will include all change
 Prior to proposing changes to `main`, proposers should consider if running a `beta testnet` review environment will make the reviewer more effective when evaluating a change.
 Changes that impact the blockchain could require a review environment before acceptance into `main`. This is at the discretion of the reviewer.
 Chia organization members have been granted CI access to deploy `beta testnets`.
-If you are not a Chia organization member, you can enquire about deploying a `beta testnet` in the public dev keybase channel.
+If you are not a Chia organization member, you can enquire about deploying a `beta testnet` in the public dev Keybase channel.
 
 ## Submit changes
 
-To propose changes, please make a pull request to the `main` branch.
+To propose changes, please make a pull request to the `main` branch. See Branching Strategy above.
 
-To propose changes, for production releases of chia please make a pull request to the latest release branch.
+To propose changes for the production releases of Chia, please make a pull request to the latest release branch.
 
 ## Copyright
 

INSTALL.md

@@ -1,6 +1,6 @@
 # Installation
 
-Install instructions have been moved to the [INSTALL](https://github.com/Chia-Network/chia-blockchain/wiki/INSTALL) section of the repository [Wiki](https://github.com/Chia-Network/chia-blockchain/wiki)
+Install instructions have been moved to the [INSTALL](https://github.com/Chia-Network/chia-blockchain/wiki/INSTALL) section of the repository [Wiki](https://github.com/Chia-Network/chia-blockchain/wiki).
 
 After installing, follow the remaining instructions in the
 [Quick Start Guide](https://github.com/Chia-Network/chia-blockchain/wiki/Quick-Start-Guide)

README.md

@@ -1,4 +1,5 @@
 # chia-blockchain
+
 ![Alt text](https://www.chia.net/img/chia_logo.svg)
 
 | Current Release/main | Development Branch/dev |
@@ -7,16 +8,15 @@
 
 ![GitHub contributors](https://img.shields.io/github/contributors/Chia-Network/chia-blockchain?logo=GitHub)
 
-Chia is a modern cryptocurrency built from scratch, designed to be efficient, decentralized, and secure. Here are some of
-the features and benefits:
+Chia is a modern cryptocurrency built from scratch, designed to be efficient, decentralized, and secure. Here are some of the features and benefits:
 * [Proof of space and time](https://docs.google.com/document/d/1tmRIb7lgi4QfKkNaxuKOBHRmwbVlGL4f7EsBDr_5xZE/edit) based consensus which allows anyone to farm with commodity hardware
 * Very easy to use full node and farmer GUI and cli (thousands of nodes active on mainnet)
 * Simplified UTXO based transaction model, with small on chain state
 * Lisp-style turing complete functional [programming language](https://chialisp.com/) for money related use cases
 * BLS keys and aggregate signatures (only one signature per block)
 * [Pooling protocol](https://www.chia.net/2020/11/10/pools-in-chia.html) (in development) that allows farmers to have control of making blocks
 * Support for light clients with fast, objective syncing
-* Growing community of farmers and developers around the world
+* A growing community of farmers and developers around the world
 
 Please check out the [wiki](https://github.com/Chia-Network/chia-blockchain/wiki)
 and [FAQ](https://github.com/Chia-Network/chia-blockchain/wiki/FAQ) for
@@ -32,18 +32,20 @@ on your router or add a NAT (for IPv4 but not IPv6) and firewall rules to allow
 TCP port 8444 access to your peer.
 These methods tend to be router make/model specific.
 
-Most should only install harvesters, farmers, plotter, full nodes, and wallets.
-Building Timelords and VDFs is for sophisticated users in most environments.
+Most users should only install harvesters, farmers, plotter, full nodes, and wallets.
+Building Timelords and VDFs is for sophisticated users, in most environments.
 Chia Network and additional volunteers are running sufficient Timelords
 for consensus.
 
 ## Installing
+
 Install instructions are available in the
 [INSTALL](https://github.com/Chia-Network/chia-blockchain/wiki/INSTALL)
 section of the
 [chia-blockchain repository wiki](https://github.com/Chia-Network/chia-blockchain/wiki).
 
 ## Running
+
 Once installed, a
 [Quick Start Guide](https://github.com/Chia-Network/chia-blockchain/wiki/Quick-Start-Guide)
 is available from the repository

build_scripts/build_macos.sh

@@ -1,8 +1,8 @@
 #!/bin/bash
 pip install setuptools_scm
-# The environment variable CHIA_INSTALLER_VERSION needs to be defined
+# The environment variable CHIA_INSTALLER_VERSION needs to be defined.
 # If the env variable NOTARIZE and the username and password variables are
-# set, this will attempt to Notarize the signed DMG
+# set, this will attempt to Notarize the signed DMG.
 CHIA_INSTALLER_VERSION=$(python installer-version.py)
 
 if [ ! "$CHIA_INSTALLER_VERSION" ]; then
@@ -91,17 +91,17 @@ fi
 
 # Notes on how to manually notarize
 #
-# Ask for username and password - password should be an app specific password
+# Ask for username and password. password should be an app specific password.
 # Generate app specific password https://support.apple.com/en-us/HT204397
 # xcrun altool --notarize-app -f Chia-0.1.X.dmg --primary-bundle-id net.chia.blockchain -u username -p password
 # xcrun altool --notarize-app; -should return REQUEST-ID, use it in next command
 #
-# Wait until following command return a success message"
-# watch -n 20 'xcrun altool --notarization-info  {REQUEST-ID} -u username -p password'
-# It can take a while, run it every few minutes
+# Wait until following command return a success message".
+# watch -n 20 'xcrun altool --notarization-info  {REQUEST-ID} -u username -p password'.
+# It can take a while, run it every few minutes.
 #
-# Once that is successful, execute the following command"
+# Once that is successful, execute the following command":
 # xcrun stapler staple Chia-0.1.X.dmg
 #
-# Validate DMG
+# Validate DMG:
 # xcrun stapler validate Chia-0.1.X.dmg

build_scripts/build_windows.ps1

@@ -21,7 +21,6 @@ else
     Write-Output "miniupnpc download successful."
 }
 
-
 Write-Output "   ---"
 Write-Output "Create venv - python3.7 or 3.8 is required in PATH"
 Write-Output "   ---"

build_scripts/installer-version.py

@@ -1,26 +1,23 @@
-from setuptools_scm import get_version
-import sys
 import os
+import sys
+
+from setuptools_scm import get_version
 
 
 # example: 1.0b5.dev225
 def main():
-
-    if len(sys.argv) > 1 and "win" in sys.argv[1]:  # Special case windows to 0.1.6225
-        windows = True
-    else:
-        windows = False
+    windows = len(sys.argv) > 1 and "win" in sys.argv[1]  # Special case windows to 0.1.6225
 
     scm_full_version = get_version(root="..", relative_to=__file__)
-    #    scm_full_version = "1.0.5.dev22"
+    # scm_full_version = "1.0.5.dev22"
     os.environ["SCM_VERSION"] = scm_full_version
-    left_full_version = scm_full_version.split("+")
 
+    left_full_version = scm_full_version.split("+")
     version = left_full_version[0].split(".")
-
     scm_major_version = version[0]
     scm_minor_version = version[1]
-    if len(version) == 3:  # if the length of the version array is more than 2
+
+    if len(version) == 3:  # If the length of the version array is more than 2
         patch_release_number = version[2]
         smc_patch_version = patch_release_number
         dev_release_number = ""
@@ -34,7 +31,7 @@ def main():
     major_release_number = scm_major_version
     minor_release_number = scm_minor_version
 
-    # If this is a beta dev release - get which beta it is
+    # If this is a beta dev release, get which beta it is
     if "0b" in scm_minor_version:
         orignial_minor_ver_list = scm_minor_version.split("0b")
         major_release_number = str(1 - int(scm_major_version))  # decrement the major release for beta

install-gui.sh

@@ -20,12 +20,12 @@ if [ "$(uname)" = "Linux" ]; then
 		sudo apt-get install -y npm nodejs libxss1
 	elif type yum &&  [ ! -f "/etc/redhat-release" ] && [ ! -f "/etc/centos-release" ] && [ ! -f /etc/rocky-release ]; then
 		# AMZN 2
-		echo "Installing on Amazon Linux 2"
+		echo "Installing on Amazon Linux 2."
 		curl -sL https://rpm.nodesource.com/setup_12.x | sudo bash -
 		sudo yum install -y nodejs
 	elif type yum && [ ! -f /etc/rocky-release ] && [ -f /etc/redhat-release ] || [ -f /etc/centos-release ]; then
 		# CentOS or Redhat
-		echo "Installing on CentOS/Redhat"
+		echo "Installing on CentOS/Redhat."
 		curl -sL https://rpm.nodesource.com/setup_12.x | sudo bash -
 		sudo yum install -y nodejs
 	elif type yum && [ -f /etc/rocky-release ]; then
@@ -52,20 +52,20 @@ if $UBUNTU; then
 fi
 
 if [ "$UBUNTU_PRE_2004" = "True" ]; then
-	echo "Installing on Ubuntu older than 20.04 LTS: Ugrading node.js to stable"
+	echo "Installing on Ubuntu older than 20.04 LTS: Ugrading node.js to stable."
 	UBUNTU_PRE_2004=true # Unfortunately Python returns True when shell expects true
 	sudo npm install -g n
 	sudo n stable
 	export PATH="$PATH"
 fi
 
 if [ "$UBUNTU" = "true" ] && [ "$UBUNTU_PRE_2004" = "False" ]; then
-	echo "Installing on Ubuntu 20.04 LTS or newer: Using installed node.js version"
+	echo "Installing on Ubuntu 20.04 LTS or newer: Using installed node.js version."
 fi
 
-# We will set up node.js on GitHub Actions and Azure Pipelines directly
-# for Mac and Windows so skip unless completing a source/developer install
-# Ubuntu special cases above
+# For Mac and Windows, we will set up node.js on GitHub Actions and Azure
+# Pipelines directly, so skip unless you are completing a source/developer install.
+# Ubuntu special cases above.
 if [ ! "$CI" ]; then
 	echo "Running git submodule update --init --recursive."
 	echo ""
@@ -89,10 +89,10 @@ if [ ! "$CI" ]; then
 	npm audit fix || true
 	npm run build
 else
-	echo "Skipping node.js in install.sh on MacOS ci"
+	echo "Skipping node.js in install.sh on MacOS ci."
 fi
 
 echo ""
-echo "Chia blockchain install-gui.sh complete."
+echo "Chia blockchain install-gui.sh completed."
 echo ""
-echo "Type 'cd chia-blockchain-gui' and then 'npm run electron &' to start the GUI"
+echo "Type 'cd chia-blockchain-gui' and then 'npm run electron &' to start the GUI."