diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/README.md | 1 | ||||
| -rw-r--r-- | doc/assets-attribution.md | 1 | ||||
| -rw-r--r-- | doc/bootstrap.md | 2 | ||||
| -rw-r--r-- | doc/build-osx.md | 27 | ||||
| -rw-r--r-- | doc/build-unix.md | 6 | ||||
| -rw-r--r-- | doc/coding.md | 76 | ||||
| -rw-r--r-- | doc/dnsseed-policy.md | 55 | ||||
| -rw-r--r-- | doc/release-process.md | 60 | ||||
| -rw-r--r-- | doc/translation_process.md | 10 | ||||
| -rw-r--r-- | doc/travis-ci.txt | 39 |
10 files changed, 188 insertions, 89 deletions
diff --git a/doc/README.md b/doc/README.md index 8368e4644b..d5d61738e8 100644 --- a/doc/README.md +++ b/doc/README.md @@ -46,7 +46,6 @@ The following are developer notes on how to build Bitcoin on your native platfor - [OSX Build Notes](build-osx.md) - [Unix Build Notes](build-unix.md) -- [Windows Build Notes](build-msw.md) Development --------------------- diff --git a/doc/assets-attribution.md b/doc/assets-attribution.md index 61b457a282..cd864f254d 100644 --- a/doc/assets-attribution.md +++ b/doc/assets-attribution.md @@ -100,5 +100,4 @@ Jonas Schnelli src/qt/res/icons/bitcoin.icns, src/qt/res/src/bitcoin.svg, src/qt/res/src/bitcoin.ico, src/qt/res/src/bitcoin.png, src/qt/res/src/bitcoin_testnet.png, docs/bitcoin_logo_doxygen.png, - src/qt/res/icons/toolbar.png, src/qt/res/icons/toolbar_testnet.png, src/qt/res/images/splash.png, src/qt/res/images/splash_testnet.png diff --git a/doc/bootstrap.md b/doc/bootstrap.md index 685b768f8b..7ce71abaad 100644 --- a/doc/bootstrap.md +++ b/doc/bootstrap.md @@ -4,7 +4,7 @@ Normally the Bitcoin client will download the transaction and network informatio ### Requirements -A fresh install of the Bitcoin client software. +- A fresh install of the Bitcoin client software. ### Download the blockchain via Bittorent diff --git a/doc/build-osx.md b/doc/build-osx.md index bc42723b12..ade9eb466b 100644 --- a/doc/build-osx.md +++ b/doc/build-osx.md @@ -69,21 +69,30 @@ Instructions: Homebrew #### Install dependencies using Homebrew - brew install autoconf automake libtool berkeley-db4 boost miniupnpc openssl pkg-config protobuf qt + brew install autoconf automake libtool boost miniupnpc openssl pkg-config protobuf qt -Note: After you have installed the dependencies, you should check that the Homebrew installed version of OpenSSL is the one available for compilation. You can check this by typing +#### Installing berkeley-db4 using Homebrew - openssl version +The homebrew package for berkeley-db4 has been broken for some time. It will install without Java though. -into Terminal. You should see OpenSSL 1.0.1h 5 Jun 2014. +Running this command takes you into brew's interactive mode, which allows you to configure, make, and install by hand: +``` +$ brew install https://raw.github.com/mxcl/homebrew/master/Library/Formula/berkeley-db4.rb -–without-java +``` -If not, you can ensure that the Homebrew OpenSSL is correctly linked by running +These rest of these commands are run inside brew interactive mode: +``` +/private/tmp/berkeley-db4-UGpd0O/db-4.8.30 $ cd .. +/private/tmp/berkeley-db4-UGpd0O $ db-4.8.30/dist/configure --prefix=/usr/local/Cellar/berkeley-db4/4.8.30 --mandir=/usr/local/Cellar/berkeley-db4/4.8.30/share/man --enable-cxx +/private/tmp/berkeley-db4-UGpd0O $ make +/private/tmp/berkeley-db4-UGpd0O $ make install +/private/tmp/berkeley-db4-UGpd0O $ exit +``` - brew link openssl --force +After exiting, you'll get a warning that the install is keg-only, which means it wasn't symlinked to `/usr/local`. You don't need it to link it to build bitcoin, but if you want to, here's how: + + $ brew --force link berkeley-db4 -Rerunning "openssl version" should now return the correct version. If it -doesn't, make sure `/usr/local/bin` comes before `/usr/bin` in your -PATH. ### Building `bitcoind` diff --git a/doc/build-unix.md b/doc/build-unix.md index 0f381d56c5..8a76a8b2cd 100644 --- a/doc/build-unix.md +++ b/doc/build-unix.md @@ -76,10 +76,6 @@ for Ubuntu 12.04 and later: Ubuntu 12.04 and later have packages for libdb5.1-dev and libdb5.1++-dev, but using these will break binary wallet compatibility, and is not recommended. -for Ubuntu 13.10: - libboost1.54 will not work, - remove libboost1.54-all-dev and install libboost1.53-all-dev instead. - for Debian 7 (Wheezy) and later: The oldstable repository contains db4.8 packages. Add the following line to /etc/apt/sources.list, @@ -113,7 +109,7 @@ To build with Qt 4 you need the following: For Qt 5 you need the following: - sudo apt-get install libqt5gui5 libqt5core5 libqt5dbus5 qttools5-dev qttools5-dev-tools libprotobuf-dev + sudo apt-get install libqt5gui5 libqt5core5 libqt5dbus5 qttools5-dev qttools5-dev-tools libprotobuf-dev protobuf-compiler libqrencode (optional) can be installed with: diff --git a/doc/coding.md b/doc/coding.md index 2f332e92f0..ceed8c18b4 100644 --- a/doc/coding.md +++ b/doc/coding.md @@ -1,29 +1,17 @@ Coding ==================== -Please be consistent with the existing coding style. - -Block style: -```c++ - bool Function(char* psz, int n) - { - // Comment summarising what this section of code does - for (int i = 0; i < n; i++) - { - // When something fails, return early - if (!Something()) - return false; - ... - } - - // Success return is usually at the end - return true; - } -``` -- ANSI/Allman block style -- 4 space indenting, no tabs -- No extra spaces inside parenthesis; please don't do ( this ) -- No space after function names, one space after if, for and while +Various coding styles have been used during the history of the codebase, +and the result is not very consistent. However, we're now trying to converge to +a single style, so please use it in new code. Old code will be converted +gradually. +- Basic rules specified in src/.clang-format. Use a recent clang-format-3.5 to format automatically. + - Braces on new lines for namespaces, classes, functions, methods. + - Braces on the same line for everything else. + - 4 space indentation (no tabs) for every block except namespaces. + - No indentation for public/protected/private or for namespaces. + - No extra spaces inside parenthesis; don't do ( this ) + - No space after function names; one space after if, for and while. - Includes need to be ordered alphabetically, separate own and foreign headers with a new-line (example key.cpp): ```c++ #include "key.h" @@ -38,31 +26,29 @@ Block style: class CAlpha; class CBeta; ``` -- When using namespace keyword use the following form: -```c++ -namespace Foo { -... +Block style example: +```c++ +namespace foo +{ +class Class +{ + bool Function(char* psz, int n) + { + // Comment summarising what this section of code does + for (int i = 0; i < n; i++) { + // When something fails, return early + if (!Something()) + return false; + ... + } -} // Foo + // Success return is usually at the end + return true; + } +} +} ``` -Variable names begin with the type in lowercase, like nSomeVariable. -Please don't put the first word of the variable name in lowercase like -someVariable. - -Common types: - - n integer number: short, unsigned short, int, unsigned int, int64, uint64, sometimes char if used as a number - d double, float - f flag - hash uint256 - p pointer or array, one p for each level of indirection - psz pointer to null terminated string - str string object - v vector or similar list objects - map map or multimap - set set or multiset - bn CBigNum Doxygen comments ----------------- diff --git a/doc/dnsseed-policy.md b/doc/dnsseed-policy.md new file mode 100644 index 0000000000..66a1757ac5 --- /dev/null +++ b/doc/dnsseed-policy.md @@ -0,0 +1,55 @@ +Expectations for DNS Seed operators +==================================== + +Bitcoin Core attempts to minimize the level of trust in DNS seeds, +but DNS seeds still pose a small amount of risk for the network. +As such, DNS seeds must be run by entities which have some minimum +level of trust within the Bitcoin community. + +Other implementations of Bitcoin software may also use the same +seeds and may be more exposed. In light of this exposure this +document establishes some basic expectations for the expectations +for the operation of dnsseeds. + +0. A DNS seed operating organization or person is expected +to follow good host security practices and maintain control of +their serving infrastructure and not sell or transfer control of their +DNS seed. Any hosting services contracted by the operator are +equally expected to uphold these expectations. + +1. The DNS seed results must consist exclusively of fairly selected and +functioning Bitcoin nodes from the public network to the best of the +operators understanding and capability. + +2. For the avoidance of doubt, the results may be randomized but must not +single-out any group of hosts to receive different results unless due to an +urgent technical necessity and disclosed. + +3. The results may not be served with a DNS TTL of less than one minute. + +4. Any logging of DNS queries should be only that which is necessary +for the operation of the service or urgent health of the Bitcoin +network and must not be retained longer than necessary or disclosed +to any third party. + +5. Information gathered as a result of the operators node-spidering +(not from DNS queries) may be freely published or retained, but only +if this data was not made more complete by biasing node connectivity +(a violation of expectation (1)). + +6. Operators are encouraged, but not required, to publicly document the +details of their operating practices. + +7. A reachable email contact address must be published for inquiries +related to the DNS seed operation. + +If these expectations cannot be satisfied the operator should +discontinue providing services and contact the active Bitcoin +Core development team as well as posting on bitcoin-development. + +Behavior outside of these expectations may be reasonable in some +situations but should be discussed in public in advance. + +See also +---------- +- [bitcoin-seeder](https://github.com/sipa/bitcoin-seeder) is a reference implementation of a DNS seed. diff --git a/doc/release-process.md b/doc/release-process.md index c588381411..c5ead4199b 100644 --- a/doc/release-process.md +++ b/doc/release-process.md @@ -156,24 +156,6 @@ repackage gitian builds for release as stand-alone zip/tar/installer exe ###Next steps: -* Code-sign Windows -setup.exe (in a Windows virtual machine using signtool) - Note: only Gavin has the code-signing keys currently. - -* upload builds to SourceForge - -* create SHA256SUMS for builds, and PGP-sign it - -* update bitcoin.org version - make sure all OS download links go to the right versions - -* update download sizes on bitcoin.org/_templates/download.html - -* update forum version - -* update wiki download links - -* update wiki changelog: [https://en.bitcoin.it/wiki/Changelog](https://en.bitcoin.it/wiki/Changelog) - Commit your signature to gitian.sigs: pushd gitian.sigs @@ -186,18 +168,50 @@ Commit your signature to gitian.sigs: ------------------------------------------------------------------------- -### After 3 or more people have gitian-built, repackage gitian-signed zips: +### After 3 or more people have gitian-built and their results match: -- Upload gitian zips to SourceForge +- Perform code-signing. -- Announce the release: + - Code-sign Windows -setup.exe (in a Windows virtual machine using signtool) + + - Code-sign MacOSX .dmg + + Note: only Gavin has the code-signing keys currently. - - Add the release to bitcoin.org: https://github.com/bitcoin/bitcoin.org/tree/master/_releases +- Create `SHA256SUMS.asc` for builds, and PGP-sign it. This is done manually. + Include all the files to be uploaded. The file has `sha256sum` format with a + simple header at the top: + +``` +Hash: SHA256 + +0060f7d38b98113ab912d4c184000291d7f026eaf77ca5830deec15059678f54 bitcoin-x.y.z-linux.tar.gz +... +``` + +- Upload zips and installers, as well as `SHA256SUMS.asc` from last step, to the bitcoin.org server + +- Update bitcoin.org version + + - Make a pull request to add a file named `YYYY-MM-DD-vX.Y.Z.md` with the release notes + to https://github.com/bitcoin/bitcoin.org/tree/master/_releases + ([Example for 0.9.2.1](https://raw.githubusercontent.com/bitcoin/bitcoin.org/master/_releases/2014-06-19-v0.9.2.1.md)). + + - After the pull request is merged, the website will automatically show the newest version, as well + as update the OS download links. Ping Saivann in case anything goes wrong + +- Announce the release: - Release sticky on bitcointalk: https://bitcointalk.org/index.php?board=1.0 - Bitcoin-development mailing list - - Optionally reddit /r/Bitcoin, ... + - Update title of #bitcoin on Freenode IRC + + - Optionally reddit /r/Bitcoin, ... but this will usually sort out itself + +- Notify BlueMatt so that he can start building [https://launchpad.net/~bitcoin/+archive/ubuntu/bitcoin](the PPAs) + +- Add release notes for the new version to the directory `doc/release-notes` in git master - Celebrate diff --git a/doc/translation_process.md b/doc/translation_process.md index 61a0a0ffed..9475b1dc72 100644 --- a/doc/translation_process.md +++ b/doc/translation_process.md @@ -17,10 +17,12 @@ automated. This file must be updated whenever a new translation is added. Please note that files must end with `.qm`, not `.ts`. - <qresource prefix="/translations"> - <file alias="en">locale/bitcoin_en.qm</file> - ... - </qresource> +```xml +<qresource prefix="/translations"> + <file alias="en">locale/bitcoin_en.qm</file> + ... +</qresource> +``` ### src/qt/locale/ diff --git a/doc/travis-ci.txt b/doc/travis-ci.txt new file mode 100644 index 0000000000..01f7d02a86 --- /dev/null +++ b/doc/travis-ci.txt @@ -0,0 +1,39 @@ +Support for using travis-ci has been added in order to automate pull-testing. +See https://travis-ci.org/ for more info + +This procedure is different than the pull-tester that came before it in a few +ways. + +There is nothing to administer. This is a major feature as it means +that builds have no local state. Because there is no ability to login to the +builders to install packages (tools, dependencies, etc), the entire build +procedure must instead be controlled by a declarative script (.travis.yml). +This script declares each build configuration, creates virtual machines as +necessary, builds, then discards the virtual machines. + +A build matrix is constructed to test a wide range of configurations, rather +than a single pass/fail. This helps to catch build failures and logic errors +that present on platforms other than the ones the author has tested. This +matrix is defined in the build script and can be changed at any time. + +All builders use the dependency-generator in the depends dir, rather than +using apt-get to install build dependencies. This guarantees that the tester +is using the same versions as Gitian, so the build results are nearly identical +to what would be found in a final release. However, this also means that builds +will fail if new dependencies are introduced without being added to the +dependency generator. + +In order to avoid rebuilding all dependencies for each build, the binaries are +cached and re-used when possible. Changes in the dependency-generator will +trigger cache-invalidation and rebuilds as necessary. + +These caches can be manually removed if necessary. This is one of the the very few +manual operations that is possible with Travis, and it can be done by the +Bitcoin Core committer via the Travis web interface. + +In some cases, secure strings may be needed for hiding sensitive info such as +private keys or URLs. The travis client may be used to create these strings: +http://docs.travis-ci.com/user/encryption-keys/ + +For the details of the build descriptor, see the official docs: +http://docs.travis-ci.com/user/build-configuration/ |