wallet/docs/rootDocs/README.md

title
README

pre alpha documentation (mostly a wish list)

copyright © and license

pre-requisite, Pandoc to build the html documentation from the markdown files.

Windows pre-requisites: Visual Studio and git-bash

To obtain the source code from which the project can be built, including this README, from the bash command line (git-bash in windows).

git clone --recurse-submodules missing url

To configure and build the required third party libraries in windows, then build the program and run unit test for the first time, launch the Visual Studio X64 native tools command prompt in the cloned directory, then:

winConfigure.bat

Should the libraries change in a subsequent pull you will need

git pull
rem you get a status message indicating libraries have been updated.
git pull -force --recurse-submodules
winConfigure.bat

in order to rebuild the libraries.

The --force is necessary, because winConfigure.bat changes many of the library files, and therefore git will abort the pull.

{target="_blank"}

The winConfigure script builds everything, including the documents, but takes a while. Normally when you make changes to the source code you should rebuild just the program, using wallet.sln on windows. To rebuild the documents after editing them, docs/mkdocs

winConfigure.bat also configures the repository you just created to use .gitconfig in the repository, causing git to to implement GPG signed commits -- because cryptographic software is under attack from NSA entryists and shills, who seek to introduce backdoors.

This may be inconvenient if you do not have gpg installed and set up.

It also means that subsequent pulls and merges will require you to have gpg trust the key public_key.gpg, and if you submit a pull request, the puller will need to trust your gpg public key.

.gitconfig adds several git aliases:

1. git lg to display the gpg trust information for the last four commits. For this to be useful you need to import the repository public key public_key.gpg into gpg, and locally sign that key.
2. git graph to graph the commit tree with signing status
3. git alias to display the git aliases.

# To verify that the signature on future pulls is
# unchanged.
gpg --import  public_key.gpg
gpg --lsign 096EAE16FB8D62E75D243199BC4482E49673711C

We ignore the Gpg Web of Trust model and instead use the Zooko identity model.

We use Gpg signatures to verify that remote repository code is coming from an unchanging entity, not for Gpg Web of Trust. Web of Trust is too complicated and too user hostile to be workable or safe.

Never --sign any Gpg key related to this project. --lsign it.

Never check any Gpg key related to this project against a public gpg key repository. It should not be there.

gitconfig disallows merges unless you have told gpg to trust the public key corresponding to the private key that signed the tip of the root. So part of the pull request process is getting the puller to trust your public key, and you will not be able to pull updates unless you tell gpg to trust the key that is in the root directory as public_key.gpg.

Never use any email address on a gpg key related to this project unless it is only used for project purposes, or a fake email, or the email of an enemy. We don't want Gpg used to link different email addresses as owned by the same entity, and we don't want email addresses used to link people to the project, because those identities would then come under state and quasi state pressure.

To build the documentation in its intended html form from the markdown files, execute the bash script file docs/mkdocs.sh, in an environment where pandoc is available. On Windows, if Git Bash and Pandoc has been installed, you should be able to run this shell file in bash by double clicking on it.

Pre alpha release, which means it does not yet work even well enough for it to be apparent what it would do if it did work.