140 lines
5.1 KiB
Markdown
140 lines
5.1 KiB
Markdown
---
|
|
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.
|
|
|
|
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.
|