joshua/dash-docs
1
0
Fork 0
mirror of https://github.com/seigler/dash-docs synced 2025-07-28 02:06:13 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Deploy thephez/dash-docs to github.com/thephez/dash-docs.git:gh-pages

Browse source
This commit is contained in:
Deployment Bot (from Travis CI) 2018-01-25 14:49:26 +00:00
commit 391f4f5496
1080 changed files with 220436 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

30
docs/adding-blog-posts.md Normal file
View file

@ -0,0 +1,30 @@
## Blog Posts
Posts for the [Bitcoin.org Site Blog](https://bitcoin.org/en/blog) should be
added to the `_posts` directory with the naming convention:
`YEAR-MONTH-DAY-ARBITRARY_FILE_NAME` (with year, month, and day as
two-digit numbers). The YAML front matter should be similar to this:
---
type: posts
layout: post
lang: en
category: blog
title: "Quarterly Report March 2015"
permalink: /en/posts/quarterly-report-march-2015.html
date: 2015-03-05
author: >
David A. Harding (<a href="mailto:dave@dtrt.org">email</a>, <a
href="https://github.com/harding">GitHub</a>,
<a href="http://www.reddit.com/user/harda/">Reddit</a>)
---
The type, layout, and category should always be as specified above. The
other parameters should be set to values specific to that post, but the
permalink must end in '.html'.
Below the YAML front matter, enter the content of the post in Markdown
format. Images should be placed in `img/blog/free` if they are
MIT-licensed or `img/blog/nonfree` if they have a more restrictive
copyright license.

70
docs/assisting-with-translations.md Normal file
View file

@ -0,0 +1,70 @@
## Translations
### How To Translate
You can join a translation team on
[Transifex](https://www.transifex.com/projects/p/bitcoinorg/) and start
translating or improving existing translations.
* You must be a native speaker for the language you choose to translate.
* Please be careful to preserve the original meaning of each text.
* Sentences and popular expressions should sound native in your language.
* Translations need to be reviewed by a reviewer or coordinator before
publication.
* Once reviewed, translations can be [submitted](#import-translations) in a pull
request on GitHub.
* **In doubt, please contact coordinators on Transifex. That'll be much
appreciated.**
### Import Translations
**Update translations**: You can update the relevant language file in
\_translations/ and from the root of the git repository run
./\_contrib/updatetx.rb to update layouts and templates for this language. You
should also make sure that no url has been changed by translators. If any page
needs to be moved, please add [redirections](https://github.com/bitcoin-dot-org/bitcoin.org/blob/master/docs/miscellaneous.md#redirections).
**Add a new language**: You can put the language file from Transifex in
\_translations and add the language in \_config.yml in the right display order
for the language bar. Make sure to review all pages and check all links.
### Update English Strings
Any change in the English text can be done through a pull request on GitHub. If
your changes affect the HTML layout of a page, you should apply fallback HTML
code for other languages until they are updated.
{% case page.lang %}
{% when 'fr' %}
(outdated french content)
{% else %}
(up to date english content)
{% endcase %}
**When translation is needed**: If you want all changes you've made to be
re-translated, you can simply update the resource file (en.yml) on Transifex.
**When translation is not needed**: If you are only pushing typo fixes and that
you don't want translators to redo all their work again, you can use the
Transifex client to pull translations, update en.yml and push back all
translations at once:
# Init Transifex project
tx init
# Setup Transifex local client to use a project created on Transifex
tx set --auto-remote https://www.transifex.com/bitcoinorg/bitcoinorg/
# Download all translations
tx pull -a -s --skip
# Set the translations/bitcoinorg.bitcoinorg/en.yml file
# as a source that will be pushed back to the server after
# updating the translation
tx set --source -r bitcoinorg.bitcoinorg -l en translations/bitcoinorg.bitcoinorg/en.yml
# (update en.yml)
# Push changes back to Transifex
tx push -s -t -f --skip --no-interactive

37
docs/become-a-contributor.md Normal file
View file

@ -0,0 +1,37 @@
## Become a Contributor
Here are some ways you can help:
* "[Watch](https://github.com/bitcoin-dot-org/bitcoin.org/subscription)" this
repository to be notified of issues and Pull Requests (PRs) that could use
your attention.
Alternatively, email volunteer coordinator Will Binns
([will@bitcoin.org](mailto:will@bitcoin.org)) or Dave Harding ([dave@dtrt.org](dave@dtrt.org))
with a short list of your interests and skills, and they will email you when
there's an issue or PR that could use your attention.
* Help [write new documentation](https://github.com/bitcoin-dot-org/bitcoin.org/blob/master/docs/contributing-to-developer-documentation.md)
for the [developer documentation pages](https://bitcoin.org/en/developer-documentation)
or [full node page](https://bitcoin.org/en/full-node), or **[review PRs
adding new documentation](https://github.com/bitcoin-dot-org/bitcoin.org/pulls?q=is%3Apr+is%3Aopen+label%3A%22Dev+Docs%22).**
You don't need to be a Bitcoin expert to review a PR---these docs are written
for non-experts, so we need to know if non-experts find them confusing or
incomplete. If you review a PR and don't find any problems worth commenting
about, leave a "Looks Good To Me (LGTM)" comment.
* [Submit new wallets](https://github.com/bitcoin-dot-org/bitcoin.org/blob/master/docs/managing-wallets.md)
for the [Choose Your Wallet page](https://bitcoin.org/en/choose-your-wallet) or
help us [review wallet submissions](https://github.com/bitcoin-dot-org/bitcoin.org/pulls?q=is%3Aopen+label%3Awallet+is%3Apr).
* [Translate Bitcoin.org into another language](https://github.com/bitcoin-dot-org/bitcoin.org/blob/master/docs/assisting-with-translations.md)
using [Transifex](https://www.transifex.com/projects/p/bitcoinorg/) or help
review new and updated translations.
* Add Bitcoin events to the [events page](https://bitcoin.org/en/events)
either by editing `_events.yml` according to the [event instructions](https://github.com/bitcoin-dot-org/bitcoin.org/blob/master/docs/adding-events-release-notes-and-alerts.md)
or by filling in a [pre-made events issue](https://github.com/bitcoin-dot-org/bitcoin.org/issues/new?title=New%20event&body=%20%20%20%20-%20date%3A%20YYYY-MM-DD%0A%20%20%20%20%20%20title%3A%20%22%22%0A%20%20%20%20%20%20venue%3A%20%22%22%0A%20%20%20%20%20%20address%3A%20%22%22%0A%20%20%20%20%20%20city%3A%20%22%22%0A%20%20%20%20%20%20country%3A%20%22%22%0A%20%20%20%20%20%20link%3A%20%22%22).
* Help improve Bitcoin.org another way. Email volunteer coordinators Will Binns ([will@bitcoin.org](mailto:will@bitcoin.org))
or Dave Harding ([dave@dtrt.org](mailto:dave@dtrt.org)) to let us know how
what you're interested in and how you'd like to get involved.

41
docs/contributing-to-developer-documentation.md Normal file
View file

@ -0,0 +1,41 @@
## Developer Documentation
Most parts of the documentation can be found in the
[_includes](https://github.com/dash-docs/dash-docs/tree/master/_includes)
directory. Updates, fixes and improvements are welcome and can submitted using
[pull requests](#working-with-github) on GitHub.
<!--
**Mailing List**: General discussions can take place on the
[mailing list](https://groups.google.com/forum/#!forum/bitcoin-documentation).
**TODO List**: New content and suggestions for improvements can be submitted
to the [TODO
list](https://github.com/bitcoin-dot-org/bitcoin.org/wiki/Documentation-TODO).
You are also welcome if you want to assign yourself to any task.
-->
**Style Guide**: For better consistency, the [style
guide](https://github.com/bitcoin-dot-org/bitcoin.org/wiki/Documentation-Style-Guide)
can be used as a reference for terminology, style and formatting. Suggested
changes
can also be submitted to this guide to keep it up to date.
**Cross-Reference Links**: Cross-reference links can be defined in
_includes/references.md. Terms which should automatically link to these
references are defined in _autocrossref.yaml .
### New Glossary Entries
Add new English glossary entries in the `_data/glossary/en/` directory.
Copy a previous glossary entry to get the correct YAML variables
(suggest using block.yaml as a template).
Non-English glossary entries are not currently supported. You'll have
to update the glossary.rb plugin and templates to support them.
### New Developer Search terms
You can add new search terms or categories directly to the `devsearches`
array in `_config.yaml`. Comments in that file should provide full
documentation.

161
docs/managing-wallets.md Normal file
View file

@ -0,0 +1,161 @@
## Wallets
The wallet list is based on the personal evaluation of the maintainer(s) and
regular contributors of this site, according to the criteria detailed below.
These requirements are meant to be updated and strengthened over time.
Innovative wallets are exciting and encouraged, so if your wallet has a good
reason for not following some of the rules below, please submit it anyway and
we'll consider updating the rules.
Basic requirements:
- Sufficient users and/or developers feedback can be found without concerning
issues, or independent security audit(s) is available
- No indication that users have been harmed considerably by any issue in
relation to the wallet
- No indication that security issues have been concealed, ignored, or not
addressed correctly in order to prevent new or similar issues from happening
in the future
- No indication that the wallet uses unstable or unsecure libraries
- No indication that changes to the code are not properly tested
- Wallet was publicly announced and released since at least 3 months
- No concerning bug is found when testing the wallet
- Website supports HTTPS and 301 redirects HTTP requests
- SSL certificate passes [Qualys SSL Labs SSL
test](https://www.ssllabs.com/ssltest/)
- Website serving executable code or requiring authentication uses HSTS with a
max-age of at least 180 days
- The identity of CEOs and/or developers is public
- Avoid address reuse by displaying a new receiving address for each transaction
in the wallet UI
- Avoid address reuse by using a new change address for each transaction
- User has access to private keys
- If private keys or encryption keys are stored online:
- Refuses weak passwords (short passwords and/or common passwords) used to
secure access to any funds, or provides an aggressive account lock-out
feature in response to failed login attempts along with a strict account
recovery process.
- If user has exclusive access over its private keys:
- Allows backup of the wallet
- Restoring wallet from backup is working
- Source code is public and kept up to date under version control system
- If user has no access to some of the private keys in a multi-signature wallet:
- Provides 2FA authentication feature
- Reminds the user to enable 2FA by email or in the main UI of the wallet
- User session is not persistent, or requires authentication for spending
- Gives control to the user over moving their funds out of the multi-signature
wallet
- For hardware wallets:
- Uses the push model (computer malware cannot sign a transaction without user
input)
- Protects the seed against unsigned firmware upgrades
- Supports importing custom seeds
- Provides source code and/or detailed specification for blackbox testing if
using a closed-source Secure Element
Optional criteria (some could become requirements):
- Received independent security audit(s)
- Does not show "received from" Bitcoin addresses in the UI
- Uses deterministic ECDSA nonces (RFC 6979)
- Provides a bug reporting policy on the website
- Website serving executable code or requiring authentication is included in the
[HSTS preload list](https://hstspreload.appspot.com/)
- If user has exclusive access over its private keys:
- Supports HD wallets (BIP32)
- Provides users with step to print or write their wallet seed on setup
- Uses a strong KDF and key stretching for wallet storage and backups
- On desktop platform:
- Encrypt the wallet by default
- For hardware wallets:
- Prevents downgrading the firmware
### Adding a wallet
*Before adding a wallet,* please make sure your wallet meets all of the
Basic Requirements listed above, or open a [new issue](https://github.com/bitcoin-dot-org/bitcoin.org/issues/new)
to request an exemption or policy change. Feel free to email Will Binns
([will@bitcoin.org](mailto:will@bitcoin.org)) or Dave Harding ([dave@dtrt.org](mailto:dave@dtrt.org))
if you have any questions.
Wallets can be added by creating a Markdown file with a wallet name
in a `_wallets` folder, like this: `_wallets/[wallet_name].md`.
For examples refer to the existing wallet files or check
`quality-assurance/schemas/wallets.yaml` schema.
**Screenshot**: The png files must go in `/img/screenshots`, be 250 X 350 px and
optimized with `optipng -o7 file.png`.
**Icon**: The png file must go in `/img/wallet`, be 144 X 144 px and optimized
with `optipng -o7 file.png`. The icon must fit within 96 X 96 px inside the png,
or 85 X 85 px for square icons.
**Description**: The text must go in `_translations/en.yml` alongside other
wallets' descriptions.
**Level**: Each wallet must have a level property assigned. A value must be in a range
between 1 and 4. Level represents a category of a wallet:
* Level 1 - Full nodes
* Level 2 - SPV, Random servers
* Level 3 - Hybrid, Multisig wallets
* Level 4 - Web wallets
### Score
Each wallet is assigned a score for five criteria. For each of them, the
appropriate text in `_translations/en.yml` needs to be chosen (_see `choose-your-wallet` section_).
**Control** - What control the user has over his bitcoins?
To get a good score, the wallet must provide the user with full exclusive
control over their bitcoins.
To get a passing score, the wallet must provide the user with exclusive control
over their bitcoins. Encrypted online backups are accepted so long as only the
user can decrypt them. Multisig wallets are accepted so long as only the user
can spend without the other party's permission.
**Validation** - How secure and « zero trust » is payment processing?
To get a good score, the wallet must be a full node and need no trust on other
nodes.
To get a passing score, the wallet must rely on random nodes, either by using
the SPV model or a pre-populated list or servers.
**Transparency** - How transparent and « zero trust » is the source code?
To get a good score, the wallet must deserve a passing score and be built
deterministically.
To get a passing score, the wallet must be open-source, under version control
and releases must be clearly identified (e.g. by tags or commits). The codebase
and final releases must be public since at least 6 months and previous commits
must remain unchanged.
**Environment** - How secure is the environment of the wallet?
To get a good score, the wallet must run from an environment where no apps can
be installed.
To get a passing score, the wallet must run from an environment that provides
app isolation (e.g. Android, iOS), or require two-factor authentication for
spending.
**Privacy**: Does the wallet protect users' privacy?
To get a good score, the wallet must avoid address reuse by using a new change
address for each transaction, avoid disclosing information to peers or central
servers and be compatible with Tor.
To get a passing score, the wallet must avoid address reuse by using a new
change address for each transaction.
### Schema validation
Wallet entries are validated against the schema in
`quality-assurance/schemas/wallets.yaml` and you will find a
description of every available option in that file.

33
docs/miscellaneous.md Normal file
View file

@ -0,0 +1,33 @@
## Miscellaneous
### Redirections
Redirections can be defined in ```_config.yml```.
```
/news: /en/version-history
```
<!--
### Aliases For Contributors
Aliases for contributors are defined in ```_config.yml```.
```
aliases:
s_nakamoto: Satoshi Nakamoto
--author=Satoshi Nakamoto: Satoshi Nakamoto
```
### Developer PGP keys
The site hosts the PGP keys for several Bitcoin Core contributors. Here
are some notes about updating those keys based on previous experience:
1. If a key is revoked, update the key with the revocation immediately.
Anyone with commit access to the site repository may do this without
prior review, but they should post the commit ID to an open issue or
PR so other people can review it. After the revoked key is uploaded,
discussion about verifying/adding a replacement key may continue at a
slower pace.
-->

193
docs/setting-up-your-environment.md Normal file
View file

@ -0,0 +1,193 @@
## Setting Up Your Environment
#### Preview Small Text Changes
Simple text changes can be previewed live on dash-docs.github.io. You only need to click
anywhere on the page and hold your mouse button for one second. You'll then be
able to edit the page just like a document. Changes will be lost as soon as the
page is refreshed.
#### Build The Site Locally
For anything more than simple text previews, you will need to build the
site. If you can't do this yourself using the instructions below, please
[open a pull request](https://github.com/dash-docs/dash-docs/compare)
with your suggested change and one of the site developers will create a preview
for you.
To build the site, you need to go through a one-time installation
procedure that takes 15 to 30 minutes. After that you can build the
site an unlimited number of times with no extra work.
#### Source Code Documentation
The https://dash-docs.github.io site includes Doxygen generated documentation
for the [Dash Core](https://github.com/dashpay/dash/) source code. To
generate it, copy the files from `doxygen/` into the Dash Core `doc/` folder
and run `doxygen doc/Doxyfile-dashdocs`. Then copy the output (Dash Core's
`doc/doxygen/html/` folder) into the `en/doxygen/` folder of this project.
##### Install The Dependencies
Before building the site, you need to install the following
dependencies and tools, which are pretty easy on any modern Linux:
**Install binary libraries and tools**
On recent versions of Ubuntu and Debian, you can run the following
command to ensure you have the required libraries, headers, and tools:
sudo apt-get install build-essential git libicu-dev zlib1g-dev
**Install RVM**
Install RVM using either the [easy instructions](https://rvm.io/) or the
[more secure instructions](https://rvm.io/rvm/security).
Read the instructions printed to your console during setup to enable the
`rvm` command in your shell. After installation, you need to run the
following command:
source ~/.rvm/scripts/rvm
**Install Ruby 2.0.0**
To install Ruby 2.0.0, simply run this command:
rvm install ruby-2.0.0
Sometimes this will find a pre-compiled Ruby package for your Linux
distribution, but sometimes it will need to compile Ruby from scratch
(which takes about 15 minutes).
After Ruby 2.0.0 is installed, make it your default Ruby:
rvm alias create default ruby-2.0.0
And tell your system to use it:
rvm use default
(Note: you can use a different default Ruby, but if you ever change
your default Ruby, you must re-run the `gem install bundle` command
described below before you can build the site. If you ever receive a
"eval: bundle: not found" error, you failed to re-run `gem install
bundle`.)
**Install Bundle**
When you used RVM to install Ruby, it also installed the `gem` program.
Use that program to install bundle:
gem install bundle
**Install the Ruby dependencies**
Ensure you checked out the site repository as described in [Working with
GitHub](https://github.com/dash-docs/dash-docs/blob/master/docs/working-with-github.md).
Then change directory to the top-level of your local repository (replace
`dash.org` with the full path to your local repository clone):
cd dash.org
And install the necessary dependencies using Bundle:
bundle install
Note that some of the dependencies (particularly nokogiri) can take a
long time to install on some systems, so be patient.
Once Bundle completes successfully, you can preview or build the site.
##### Preview The Site
To preview the website in your local browser, make sure you're in the
`dash.org` directory and run the following command:
make preview
This will compile the site (takes 5 to 10 minutes; see [the speed-up
instructions](#fast-partial-previews-or-builds)) and then print a
message like this:
Server address: http://0.0.0.0:4000
Server running... press ctrl-c to stop.
Visit the indicated URL in your browser to view the site.
##### Build The Site
To build the site exactly like we do for the deployment server, make
sure you're in the `dash.org` directory and run:
make
The resulting HTML for the entire site will be placed in the `_site`
directory. The following alternative options are available:
## After you build the site, you can run all of the tests (may take awhile)
make test
## Or you can build the site and run some quick tests with one command:
make valid
## Or build the site and run all tests
make all
#### Fast Partial Previews Or Builds
In order to preview some changes faster, you can disable all plugins and
languages except those you need by prefixing the `ENABLED_LANGS` and
`ENABLED_PLUGINS` environment variables to your command line. For
example, do this to disable everything:
## Fast preview, takes less than 30 seconds
ENABLED_PLUGINS="" ENABLED_LANGS="" make preview
## Fast build and tests, takes less than 50 seconds
## Some tests may fail in fast mode; use -i to continue despite them
ENABLED_PLUGINS="" ENABLED_LANGS="" make -i valid
Then to enable some plugins or languages, you can add them back in.
For example:
## Slower (but still pretty fast) build and test
ENABLED_PLUGINS="events autocrossref" ENABLED_LANGS="en fr" make -i valid
Plugins include:
| Plugin | Seconds | Remote APIs | Used For
|--------------|---------|----------------|------------------------
| autocrossref | 90 | -- | Developer documentation
| glossary | 30 | -- | Developer glossary
| redirects | 20 | -- | Redirects from old URLs
| sitemap | 10 | -- | /sitemap.xml
Notes: some plugins interact with each other or with translations; for example
running
'autocrossref' and 'glossary' takes longer than running each other
separately. Also, plugins that use remote APIs may take a long time to
run if the API site is running slow.
For a list of languages, look in the `_translations` directory.
#### Publishing Previews
You can publish your previews online to any static hosting service.
[GitHub pages](https://pages.github.com/) is a free service available to
all GitHub users that works with dash-docs.github.io's site hierarchy.
Before building a preview site, it is recommended that you set the
environmental variable `BITCOINORG_BUILD_TYPE` to "preview". This will
enable some content that would otherwise be hidden and also create a
robots.txt file that will help prevent the site from being indexed by
search engines and mistaken for the actual dash-docs.github.io website.
In the bash shell, you can do this by running the following command line
before building you preview:
export BITCOINORG_BUILD_TYPE=preview
You can also add this line to your `~/.bashrc` file if you frequently
build site previews so that you don't have to remember to run it for
each shell.

84
docs/working-with-github.md Normal file
View file

@ -0,0 +1,84 @@
## Working With GitHub
GitHub allows you to make changes to a project using git, and later submit them
in a "pull request" so they can be reviewed and discussed. Many online how-tos
exist so you can learn git, [here's a good
one](https://www.atlassian.com/git/tutorial/git-basics).
In order to use GitHub, you need to [sign up](http://github.com/signup) and [set
up git](https://help.github.com/articles/set-up-git). You will also need to
click the **Fork** button on the dash.org [GitHub
page](https://github.com/dash-docs/dash-docs) and clone your GitHub
repository into a local directory with the following command lines:
```
git clone (url provided by GitHub on your fork's page) dash.org
cd dash.org
git remote add upstream https://github.com/dash-docs/dash-docs.git
```
**How to send a pull request**
1. Checkout to your master branch. `git checkout master`
2. Create a new branch from the master branch. `git checkout -b (any name)`
3. Edit files and [preview](#previewing) the result.
4. Track changes in files. `git add -A`
5. Commit your changes. `git commit -m '(short description for your change)'`
6. Push your branch on your GitHub repository. `git push origin (name of your
branch)`
7. Click on your branch on GitHub and click the **Compare / pull request**
button to send a pull request.
When submitting a pull request, please take required time to discuss your
changes and adapt your work. It is generally a good practice to split unrelated
changes into separate branches and pull requests.
<!--
**Travis Continuous Integration (CI)**
Shortly after your Pull Request (PR) is submitted, a Travis CI job will
be added to [our queue](https://travis-ci.org/bitcoin-dot-org/bitcoin.org). This
will build the site and run some basic checks. If the job fails, you
will be emailed a link to the build log and the PR will indicate a
failed job. Read the build report and try to correct the problem---but
if you feel confused or frustrated, please ask for help on the PR (we're
always happy to help).
If you don't want a particular commit to be tested, add `[ci skip]`
anywhere in its commit message.
If you'd like to setup Travis on your own repository so you can test
builds before opening a pull request, it's really simple:
1. Make sure the master branch of your repository is up to date with the
bitcoin-dot-org/bitcoin.org master branch.
2. Open [this guide](http://docs.travis-ci.com/user/getting-started/)
and perform steps one, two, and four. (The other steps are already
done in our master branch.)
3. After you push a branch to your repository, go to your branches page
(e.g. for user harding, github.com/harding/bitcoin.org/branches). A
yellow circle, green checkmark, or red X will appear near the branch
name when the build finishes, and clicking on the icon will take you
to the corresponding build report.
-->
**How to make additional changes in a pull request**
You simply need to push additional commits on the appropriate branch of your
GitHub repository. That's basically the same steps as above, except you don't
need to re-create the branch and the pull request.
**How to reset and update your master branch with latest upstream changes**
1. Fetch upstream changes. `git fetch upstream`
2. Checkout to your master branch. `git checkout master`
3. Replace your master branch by the upstream master branch. `git reset --hard
upstream/master`
4. Replace your master branch on GitHub. `git push origin master -f`
**Advanced GitHub Workflow**
If you continue to contribute to Dash.org beyond a single pull
request, you may want to use a more [advanced GitHub
workflow](https://gist.github.com/harding/1a99b0bad37f9498709f).