f249adda03
start problem. modified: docs/manifesto/social_networking.md Discussion of gpg has been obsoleted by by git adding its own trust mechanism to deal with the trust problems of gpg. modified: docs/rootDocs/README.md modified: docs/setup/contributor_code_of_conduct.md
152 lines
5.7 KiB
Markdown
152 lines
5.7 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.
|
||
|
||
[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.
|