wallet/docs/rootDocs/README.md

---
title: >-
    README
---

[pre alpha documentation (mostly a wish list)](docs/index.htm)

[copyright © and license](./license.txt)

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.html, from the bash command line (git-bash in windows).

```bash
git clone --recurse-submodules missing url
```

To build the docs, you need pandoc on the path.

```bash2
cd wallet/docs
./mkdocs.sh
```

To configure and build the required third party libraries in windows, then
build the program and run unit test for the first time, you need to have
Visual studio build tools at  their default location)

```bash2
cd wallet
./winConfigure.bat
```

Or, if you are in the command shell or power shell,

```bat
.\winConfigure.bat
```

After a pull from remote in which the submodules have changed, the pull
fails to automatically update the submodules by default, and when you
switch or checkout branches, the switch fails to automatically switch
and checkout the brances.

After a pull that gives you a status of modified submodules.

```bash
git submodule update --init --recursive --remote
```

After a checkout or branch switch that gives you a status of modified submodules.

```bash
git submodule update --recursive
```

The documentation is in pandoc flavored markdown, which is
 conveniently edited in vscode with the `markdown lint` and `Pandoc`
 extensions included and, if you have launched `code` in the docs directory,
 with  `file/preferences/Extensions/Markdown/Styles` set to
 `pandoc_templates\\style.css`, that being the style used by the `mkdocs.sh` documentation build script.

 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.

if you add the recommended repository configuration defaults to your local repository configuration

```bash
git config --local include.path ../.gitconfig
```

this will substantially mitigate the problem of submodules failing to
update in pushes, pulls, checkouts, and switches.

[cryptographic software is under attack]:./docs/setup/contributor_code_of_conduct.html#code-will-be-cryptographically-signed
"Contributor Code of Conduct"
{target="_blank"}

It will, however, also implement  signed commits, insist that you have `gpg` on your path, and that you have cohfigured a signing key in your local config, and will refuse to pull updates that are signed by a gpg key that you have not locally trusted.
because [cryptographic software is under attack] from NSA
entryists and shills, who seek to introduce backdoors.

[has its own trust model based on *ssh* and gpg keys]:https://git-scm.com/docs/git-config
{target="_blank"}

〔Note that this has been obsoleted and needs to be rewritten
since git now [has its own trust model based on *ssh* and gpg keys]
and the file `gpg.ssh.allowedSignersFile`, 
which should be in a repository that only allows signed commits.

Git now has a bunch of hooks that are accessed through config entries
starting with `gpg.` that potentially allow us to supply zooko names
for git signed commits.〕You can sign a file or a commit, and
`https://github.com/USERNAME.keys` is a central name authority.

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 few commits.
   For this to be useful you need to import the repository public key
   `public_key.gpg` into gpg, and locally sign that key.
1. `git graph` to graph the commit tree with signing status
1. `git alias` to display the git aliases.

```bash
# 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.

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

[Pre alpha release](./RELEASE_NOTES.html), which means it does not yet work even well
enough for it to be apparent what it would do if it did work.