diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/Doxyfile.in | 2 | ||||
| -rw-r--r-- | doc/README.md | 1 | ||||
| -rw-r--r-- | doc/bips.md | 4 | ||||
| -rw-r--r-- | doc/build-osx.md | 263 | ||||
| -rw-r--r-- | doc/build-windows.md | 24 | ||||
| -rw-r--r-- | doc/dependencies.md | 16 | ||||
| -rw-r--r-- | doc/developer-notes.md | 13 | ||||
| -rw-r--r-- | doc/fuzzing.md | 4 | ||||
| -rw-r--r-- | doc/man/bitcoin-qt.1 | 3 | ||||
| -rw-r--r-- | doc/man/bitcoind.1 | 4 | ||||
| -rw-r--r-- | doc/productivity.md | 16 | ||||
| -rw-r--r-- | doc/psbt.md | 7 | ||||
| -rw-r--r-- | doc/reduce-memory.md | 49 | ||||
| -rw-r--r-- | doc/reduce-traffic.md | 13 | ||||
| -rw-r--r-- | doc/release-notes-0.18.1-16257.md | 6 | ||||
| -rw-r--r-- | doc/release-notes-13756.md | 41 | ||||
| -rw-r--r-- | doc/release-notes-14802.md | 3 | ||||
| -rw-r--r-- | doc/release-notes-14954.md | 3 | ||||
| -rw-r--r-- | doc/release-notes-15006.md | 4 | ||||
| -rw-r--r-- | doc/release-notes-15427.md | 9 | ||||
| -rw-r--r-- | doc/release-notes.md | 80 | ||||
| -rw-r--r-- | doc/release-notes/release-notes-0.12.0.md | 2 | ||||
| -rw-r--r-- | doc/release-notes/release-notes-16152.md | 7 | ||||
| -rw-r--r-- | doc/release-process.md | 74 |
24 files changed, 420 insertions, 228 deletions
diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in index 58c65fb7e2..399d54eb85 100644 --- a/doc/Doxyfile.in +++ b/doc/Doxyfile.in @@ -453,7 +453,7 @@ EXTRACT_PACKAGE = NO # included in the documentation. # The default value is: NO. -EXTRACT_STATIC = NO +EXTRACT_STATIC = YES # If the EXTRACT_LOCAL_CLASSES tag is set to YES, classes (and structs) defined # locally in source files will be included in the documentation. If set to NO, diff --git a/doc/README.md b/doc/README.md index b4fa933c8e..d3017de2ab 100644 --- a/doc/README.md +++ b/doc/README.md @@ -74,6 +74,7 @@ The Bitcoin repo's [root README](/README.md) contains relevant information on th - [bitcoin.conf Configuration File](bitcoin-conf.md) - [Files](files.md) - [Fuzz-testing](fuzzing.md) +- [Reduce Memory](reduce-memory.md) - [Reduce Traffic](reduce-traffic.md) - [Tor Support](tor.md) - [Init Scripts (systemd/upstart/openrc)](init.md) diff --git a/doc/bips.md b/doc/bips.md index eb24ce6f66..3085fa424b 100644 --- a/doc/bips.md +++ b/doc/bips.md @@ -12,8 +12,8 @@ BIPs that are implemented by Bitcoin Core (up-to-date up to **v0.18.0**): * [`BIP 31`](https://github.com/bitcoin/bips/blob/master/bip-0031.mediawiki): The 'pong' protocol message (and the protocol version bump to 60001) has been implemented since **v0.6.1** ([PR #1081](https://github.com/bitcoin/bitcoin/pull/1081)). * [`BIP 32`](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki): Hierarchical Deterministic Wallets has been implemented since **v0.13.0** ([PR #8035](https://github.com/bitcoin/bitcoin/pull/8035)). * [`BIP 34`](https://github.com/bitcoin/bips/blob/master/bip-0034.mediawiki): The rule that requires blocks to contain their height (number) in the coinbase input, and the introduction of version 2 blocks has been implemented since **v0.7.0**. The rule took effect for version 2 blocks as of *block 224413* (March 5th 2013), and version 1 blocks are no longer allowed since *block 227931* (March 25th 2013) ([PR #1526](https://github.com/bitcoin/bitcoin/pull/1526)). -* [`BIP 35`](https://github.com/bitcoin/bips/blob/master/bip-0035.mediawiki): The 'mempool' protocol message (and the protocol version bump to 60002) has been implemented since **v0.7.0** ([PR #1641](https://github.com/bitcoin/bitcoin/pull/1641)). -* [`BIP 37`](https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki): The bloom filtering for transaction relaying, partial Merkle trees for blocks, and the protocol version bump to 70001 (enabling low-bandwidth SPV clients) has been implemented since **v0.8.0** ([PR #1795](https://github.com/bitcoin/bitcoin/pull/1795)). +* [`BIP 35`](https://github.com/bitcoin/bips/blob/master/bip-0035.mediawiki): The 'mempool' protocol message (and the protocol version bump to 60002) has been implemented since **v0.7.0** ([PR #1641](https://github.com/bitcoin/bitcoin/pull/1641)). As of **v0.13.0**, this is only available for `NODE_BLOOM` (BIP 111) peers. +* [`BIP 37`](https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki): The bloom filtering for transaction relaying, partial Merkle trees for blocks, and the protocol version bump to 70001 (enabling low-bandwidth SPV clients) has been implemented since **v0.8.0** ([PR #1795](https://github.com/bitcoin/bitcoin/pull/1795)). Disabled by default since **v0.19.0**, can be enabled by the `-peerbloomfilters` option. * [`BIP 42`](https://github.com/bitcoin/bips/blob/master/bip-0042.mediawiki): The bug that would have caused the subsidy schedule to resume after block 13440000 was fixed in **v0.9.2** ([PR #3842](https://github.com/bitcoin/bitcoin/pull/3842)). * [`BIP 61`](https://github.com/bitcoin/bips/blob/master/bip-0061.mediawiki): The 'reject' protocol message (and the protocol version bump to 70002) was added in **v0.9.0** ([PR #3185](https://github.com/bitcoin/bitcoin/pull/3185)). Starting **v0.17.0**, whether to send reject messages can be configured with the `-enablebip61` option, and support is deprecated as of **v0.18.0**. * [`BIP 65`](https://github.com/bitcoin/bips/blob/master/bip-0065.mediawiki): The CHECKLOCKTIMEVERIFY softfork was merged in **v0.12.0** ([PR #6351](https://github.com/bitcoin/bitcoin/pull/6351)), and backported to **v0.11.2** and **v0.10.4**. Mempool-only CLTV was added in [PR #6124](https://github.com/bitcoin/bitcoin/pull/6124). diff --git a/doc/build-osx.md b/doc/build-osx.md index d28a3d97aa..65cfce6b15 100644 --- a/doc/build-osx.md +++ b/doc/build-osx.md @@ -1,33 +1,37 @@ -macOS Build Instructions and Notes -==================================== +# macOS Build Instructions and Notes + The commands in this guide should be executed in a Terminal application. -The built-in one is located in `/Applications/Utilities/Terminal.app`. +The built-in one is located in +``` +/Applications/Utilities/Terminal.app +``` -Preparation ------------ +## Preparation Install the macOS command line tools: -`xcode-select --install` +```shell +xcode-select --install +``` When the popup appears, click `Install`. Then install [Homebrew](https://brew.sh). -Dependencies ----------------------- - - brew install automake berkeley-db4 libtool boost miniupnpc openssl pkg-config protobuf python qt libevent qrencode +## Dependencies +```shell +brew install automake berkeley-db4 libtool boost miniupnpc openssl pkg-config protobuf python qt libevent qrencode +``` See [dependencies.md](dependencies.md) for a complete overview. If you want to build the disk image with `make deploy` (.dmg / optional), you need RSVG: +```shell +brew install librsvg +``` - brew install librsvg - -Berkeley DB ------------ +## Berkeley DB It is recommended to use Berkeley DB 4.8. If you have to build it yourself, -you can use [the installation script included in contrib/](/contrib/install_db4.sh) +you can use [this](/contrib/install_db4.sh) script to install it like so: ```shell @@ -38,172 +42,167 @@ from the root of the repository. **Note**: You only need Berkeley DB if the wallet is enabled (see [*Disable-wallet mode*](/doc/build-osx.md#disable-wallet-mode)). -Build Bitcoin Core ------------------------- +## Build Bitcoin Core 1. Clone the Bitcoin Core source code: - - git clone https://github.com/bitcoin/bitcoin - cd bitcoin + ```shell + git clone https://github.com/bitcoin/bitcoin + cd bitcoin + ``` 2. Build Bitcoin Core: Configure and build the headless Bitcoin Core binaries as well as the GUI (if Qt is found). You can disable the GUI build by passing `--without-gui` to configure. - - ./autogen.sh - ./configure - make + ```shell + ./autogen.sh + ./configure + make + ``` 3. It is recommended to build and run the unit tests: - - make check - -4. You can also create a .dmg that contains the .app bundle (optional): - - make deploy - -Disable-wallet mode --------------------- -When the intention is to run only a P2P node without a wallet, Bitcoin Core may be compiled in -disable-wallet mode with: - - ./configure --disable-wallet + ```shell + make check + ``` + +4. You can also create a `.dmg` that contains the `.app` bundle (optional): + ```shell + make deploy + ``` + +## `disable-wallet` mode +When the intention is to run only a P2P node without a wallet, Bitcoin Core may be +compiled in `disable-wallet` mode with: +```shell +./configure --disable-wallet +``` In this case there is no dependency on Berkeley DB 4.8. Mining is also possible in disable-wallet mode using the `getblocktemplate` RPC call. -Running -------- - +## Running Bitcoin Core is now available at `./src/bitcoind` Before running, you may create an empty configuration file: +```shell +mkdir -p "/Users/${USER}/Library/Application Support/Bitcoin" - mkdir -p "/Users/${USER}/Library/Application Support/Bitcoin" - - touch "/Users/${USER}/Library/Application Support/Bitcoin/bitcoin.conf" +touch "/Users/${USER}/Library/Application Support/Bitcoin/bitcoin.conf" - chmod 600 "/Users/${USER}/Library/Application Support/Bitcoin/bitcoin.conf" +chmod 600 "/Users/${USER}/Library/Application Support/Bitcoin/bitcoin.conf" +``` -The first time you run bitcoind, it will start downloading the blockchain. This process could take many hours, or even days on slower than average systems. +The first time you run bitcoind, it will start downloading the blockchain. This process could +take many hours, or even days on slower than average systems. You can monitor the download process by looking at the debug.log file: +```shell +tail -f $HOME/Library/Application\ Support/Bitcoin/debug.log +``` - tail -f $HOME/Library/Application\ Support/Bitcoin/debug.log - -Other commands: -------- - - ./src/bitcoind -daemon # Starts the bitcoin daemon. - ./src/bitcoin-cli --help # Outputs a list of command-line options. - ./src/bitcoin-cli help # Outputs a list of RPC commands when the daemon is running. - -Notes ------ - -* Tested on OS X 10.10 Yosemite through macOS 10.13 High Sierra on 64-bit Intel processors only. - -* Building with downloaded Qt binaries is not officially supported. See the notes in [#7714](https://github.com/bitcoin/bitcoin/issues/7714) +## Other commands: +```shell +./src/bitcoind -daemon # Starts the bitcoin daemon. +./src/bitcoin-cli --help # Outputs a list of command-line options. +./src/bitcoin-cli help # Outputs a list of RPC commands when the daemon is running. +``` -Deterministic macOS DMG Notes ------------------------------ +## Notes +* Tested on OS X 10.10 Yosemite through macOS 10.14 Mojave on 64-bit Intel +processors only. +* Building with downloaded Qt binaries is not officially supported. See the notes in [#7714](https://github.com/bitcoin/bitcoin/issues/7714). -Working macOS DMGs are created in Linux by combining a recent clang, -the Apple binutils (ld, ar, etc) and DMG authoring tools. +## Deterministic macOS DMG Notes +Working macOS DMGs are created in Linux by combining a recent `clang`, the Apple +`binutils` (`ld`, `ar`, etc) and DMG authoring tools. -Apple uses clang extensively for development and has upstreamed the necessary -functionality so that a vanilla clang can take advantage. It supports the use -of -F, -target, -mmacosx-version-min, and --sysroot, which are all necessary -when building for macOS. +Apple uses `clang` extensively for development and has upstreamed the necessary +functionality so that a vanilla clang can take advantage. It supports the use of `-F`, +`-target`, `-mmacosx-version-min`, and `--sysroot`, which are all necessary when +building for macOS. -Apple's version of binutils (called cctools) contains lots of functionality -missing in the FSF's binutils. In addition to extra linker options for -frameworks and sysroots, several other tools are needed as well such as -install_name_tool, lipo, and nmedit. These do not build under linux, so they -have been patched to do so. The work here was used as a starting point: -[mingwandroid/toolchain4](https://github.com/mingwandroid/toolchain4). +Apple's version of `binutils` (called `cctools`) contains lots of functionality missing in the +FSF's `binutils`. In addition to extra linker options for frameworks and sysroots, several +other tools are needed as well such as `install_name_tool`, `lipo`, and `nmedit`. These +do not build under Linux, so they have been patched to do so. The work here was used as +a starting point: [mingwandroid/toolchain4](https://github.com/mingwandroid/toolchain4). -In order to build a working toolchain, the following source packages are needed -from Apple: cctools, dyld, and ld64. +In order to build a working toolchain, the following source packages are needed from +Apple: `cctools`, `dyld`, and `ld64`. -These tools inject timestamps by default, which produce non-deterministic -binaries. The ZERO_AR_DATE environment variable is used to disable that. +These tools inject timestamps by default, which produce non-deterministic binaries. The +`ZERO_AR_DATE` environment variable is used to disable that. -This version of cctools has been patched to use the current version of clang's -headers and its libLTO.so rather than those from llvmgcc, as it was -originally done in toolchain4. +This version of `cctools` has been patched to use the current version of `clang`'s headers +and its `libLTO.so` rather than those from `llvmgcc`, as it was originally done in `toolchain4`. -To complicate things further, all builds must target an Apple SDK. These SDKs -are free to download, but not redistributable. -To obtain it, register for a developer account, then download the [Xcode 7.3.1 dmg](https://developer.apple.com/devcenter/download.action?path=/Developer_Tools/Xcode_7.3.1/Xcode_7.3.1.dmg). +To complicate things further, all builds must target an Apple SDK. These SDKs are free to +download, but not redistributable. To obtain it, register for an Apple Developer Account, +then download the [Xcode 7.3.1 dmg](https://developer.apple.com/devcenter/download.action?path=/Developer_Tools/Xcode_7.3.1/Xcode_7.3.1.dmg). -This file is several gigabytes in size, but only a single directory inside is -needed: +This file is several gigabytes in size, but only a single directory inside is needed: ``` Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.11.sdk ``` -Unfortunately, the usual linux tools (7zip, hpmount, loopback mount) are incapable of opening this file. -To create a tarball suitable for Gitian input, there are two options: +Unfortunately, the usual Linux tools (7zip, hpmount, loopback mount) are incapable of +opening this file. To create a tarball suitable for Gitian input, there are two options: -Using macOS, you can mount the dmg, and then create it with: -``` - $ hdiutil attach Xcode_7.3.1.dmg - $ tar -C /Volumes/Xcode/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/ -czf MacOSX10.11.sdk.tar.gz MacOSX10.11.sdk +Using macOS, you can mount the DMG, and then create it with: +```shell +hdiutil attach Xcode_7.3.1.dmg +tar -C /Volumes/Xcode/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/ -czf MacOSX10.11.sdk.tar.gz MacOSX10.11.sdk ``` -Alternatively, you can use 7zip and SleuthKit to extract the files one by one. -The script contrib/macdeploy/extract-osx-sdk.sh automates this. First ensure -the dmg file is in the current directory, and then run the script. You may wish -to delete the intermediate 5.hfs file and MacOSX10.11.sdk (the directory) when -you've confirmed the extraction succeeded. +Alternatively, you can use 7zip and SleuthKit to extract the files one by one. The script +[`extract-osx-sdk.sh`](./../contrib/macdeploy/extract-osx-sdk.sh) automates this. First +ensure the DMG file is in the current directory, and then run the script. You may wish to +delete the `intermediate 5.hfs` file and `MacOSX10.11.sdk` (the directory) when you've +confirmed the extraction succeeded. -```bash +```shell apt-get install p7zip-full sleuthkit contrib/macdeploy/extract-osx-sdk.sh rm -rf 5.hfs MacOSX10.11.sdk ``` -The Gitian descriptors build 2 sets of files: Linux tools, then Apple binaries -which are created using these tools. The build process has been designed to -avoid including the SDK's files in Gitian's outputs. All interim tarballs are -fully deterministic and may be freely redistributed. +The Gitian descriptors build 2 sets of files: Linux tools, then Apple binaries which are +created using these tools. The build process has been designed to avoid including the +SDK's files in Gitian's outputs. All interim tarballs are fully deterministic and may be freely +redistributed. -genisoimage is used to create the initial DMG. It is not deterministic as-is, -so it has been patched. A system genisoimage will work fine, but it will not -be deterministic because the file-order will change between invocations. -The patch can be seen here: [theuni/osx-cross-depends](https://raw.githubusercontent.com/theuni/osx-cross-depends/master/patches/cdrtools/genisoimage.diff). -No effort was made to fix this cleanly, so it likely leaks memory badly. But -it's only used for a single invocation, so that's no real concern. +`genisoimage` is used to create the initial DMG. It is not deterministic as-is, so it has been +patched. A system `genisoimage` will work fine, but it will not be deterministic because +the file-order will change between invocations. The patch can be seen here: [theuni/osx-cross-depends](https://raw.githubusercontent.com/theuni/osx-cross-depends/master/patches/cdrtools/genisoimage.diff). +No effort was made to fix this cleanly, so it likely leaks memory badly. But it's only used for +a single invocation, so that's no real concern. -genisoimage cannot compress DMGs, so afterwards, the 'dmg' tool from the -libdmg-hfsplus project is used to compress it. There are several bugs in this -tool and its maintainer has seemingly abandoned the project. It has been forked -and is available (with fixes) here: [theuni/libdmg-hfsplus](https://github.com/theuni/libdmg-hfsplus). +`genisoimage` cannot compress DMGs, so afterwards, the DMG tool from the +`libdmg-hfsplus` project is used to compress it. There are several bugs in this tool and its +maintainer has seemingly abandoned the project. It has been forked and is available +(with fixes) here: [theuni/libdmg-hfsplus](https://github.com/theuni/libdmg-hfsplus). -The 'dmg' tool has the ability to create DMGs from scratch as well, but this -functionality is broken. Only the compression feature is currently used. -Ideally, the creation could be fixed and genisoimage would no longer be necessary. +The DMG tool has the ability to create DMGs from scratch as well, but this functionality is +broken. Only the compression feature is currently used. Ideally, the creation could be fixed +and `genisoimage` would no longer be necessary. Background images and other features can be added to DMG files by inserting a -.DS_Store before creation. This is generated by the script -contrib/macdeploy/custom_dsstore.py. - -As of OS X 10.9 Mavericks, using an Apple-blessed key to sign binaries is a -requirement in order to satisfy the new Gatekeeper requirements. Because this -private key cannot be shared, we'll have to be a bit creative in order for the -build process to remain somewhat deterministic. Here's how it works: - -- Builders use Gitian to create an unsigned release. This outputs an unsigned - dmg which users may choose to bless and run. It also outputs an unsigned app - structure in the form of a tarball, which also contains all of the tools - that have been previously (deterministically) built in order to create a - final dmg. -- The Apple keyholder uses this unsigned app to create a detached signature, - using the script that is also included there. Detached signatures are available from this [repository](https://github.com/bitcoin-core/bitcoin-detached-sigs). -- Builders feed the unsigned app + detached signature back into Gitian. It - uses the pre-built tools to recombine the pieces into a deterministic dmg. +`.DS_Store` before creation. This is generated by the script +`contrib/macdeploy/custom_dsstore.py`. + +As of OS X 10.9 Mavericks, using an Apple-blessed key to sign binaries is a requirement in +order to satisfy the new Gatekeeper requirements. Because this private key cannot be +shared, we'll have to be a bit creative in order for the build process to remain somewhat +deterministic. Here's how it works: + +- Builders use Gitian to create an unsigned release. This outputs an unsigned DMG which + users may choose to bless and run. It also outputs an unsigned app structure in the form + of a tarball, which also contains all of the tools that have been previously (deterministically) + built in order to create a final DMG. +- The Apple keyholder uses this unsigned app to create a detached signature, using the + script that is also included there. Detached signatures are available from this [repository](https://github.com/bitcoin-core/bitcoin-detached-sigs). +- Builders feed the unsigned app + detached signature back into Gitian. It uses the + pre-built tools to recombine the pieces into a deterministic DMG. diff --git a/doc/build-windows.md b/doc/build-windows.md index 036c585b44..5ca9f98475 100644 --- a/doc/build-windows.md +++ b/doc/build-windows.md @@ -102,30 +102,6 @@ Build using: CONFIG_SITE=$PWD/depends/x86_64-w64-mingw32/share/config.site ./configure --prefix=/ make -## Building for 32-bit Windows - -To build executables for Windows 32-bit, install the following dependencies: - - sudo apt install g++-mingw-w64-i686 mingw-w64-i686-dev - -For Ubuntu Bionic 18.04 and Windows Subsystem for Linux <sup>[1](#footnote1)</sup>: - - sudo update-alternatives --config i686-w64-mingw32-g++ # Set the default mingw32 g++ compiler option to posix. - -Note that for WSL the Bitcoin Core source path MUST be somewhere in the default mount file system, for -example /usr/src/bitcoin, AND not under /mnt/d/. If this is not the case the dependency autoconf scripts will fail. -This means you cannot use a directory that located directly on the host Windows file system to perform the build. - -Build using: - - PATH=$(echo "$PATH" | sed -e 's/:\/mnt.*//g') # strip out problematic Windows %PATH% imported var - cd depends - make HOST=i686-w64-mingw32 - cd .. - ./autogen.sh # not required when building from tarball - CONFIG_SITE=$PWD/depends/i686-w64-mingw32/share/config.site ./configure --prefix=/ - make - ## Depends system For further documentation on the depends system see [README.md](../depends/README.md) in the depends directory. diff --git a/doc/dependencies.md b/doc/dependencies.md index 1b3df62867..0b23ca0a2d 100644 --- a/doc/dependencies.md +++ b/doc/dependencies.md @@ -6,27 +6,25 @@ These are the dependencies currently used by Bitcoin Core. You can find instruct | Dependency | Version used | Minimum required | CVEs | Shared | [Bundled Qt library](https://doc.qt.io/qt-5/configure-options.html#third-party-libraries) | | --- | --- | --- | --- | --- | --- | | Berkeley DB | [4.8.30](https://www.oracle.com/technetwork/database/database-technologies/berkeleydb/downloads/index.html) | 4.8.x | No | | | -| Boost | [1.64.0](https://www.boost.org/users/download/) | [1.47.0](https://github.com/bitcoin/bitcoin/pull/8920) | No | | | -| Clang | | [3.3+](https://llvm.org/releases/download.html) (C++11 support) | | | | -| D-Bus | [1.10.18](https://cgit.freedesktop.org/dbus/dbus/tree/NEWS?h=dbus-1.10) | | No | Yes | | -| Expat | [2.2.6](https://libexpat.github.io/) | | No | Yes | | +| Boost | [1.70.0](https://www.boost.org/users/download/) | [1.47.0](https://github.com/bitcoin/bitcoin/pull/8920) | No | | | +| Clang | | [3.3+](https://releases.llvm.org/download.html) (C++11 support) | | | | +| Expat | [2.2.7](https://libexpat.github.io/) | | No | Yes | | | fontconfig | [2.12.1](https://www.freedesktop.org/software/fontconfig/release/) | | No | Yes | | | FreeType | [2.7.1](https://download.savannah.gnu.org/releases/freetype) | | No | | | | GCC | | [4.8+](https://gcc.gnu.org/) (C++11 support) | | | | | HarfBuzz-NG | | | | | | | libevent | [2.1.8-stable](https://github.com/libevent/libevent/releases) | 2.0.22 | No | | | -| libjpeg | | | | | [Yes](https://github.com/bitcoin/bitcoin/blob/master/depends/packages/qt.mk#L65) | -| libpng | | | | | [Yes](https://github.com/bitcoin/bitcoin/blob/master/depends/packages/qt.mk#L64) | +| libpng | | | | | [Yes](https://github.com/bitcoin/bitcoin/blob/master/depends/packages/qt.mk) | | librsvg | | | | | | | MiniUPnPc | [2.0.20180203](http://miniupnp.free.fr/files) | | No | | | | OpenSSL | [1.0.1k](https://www.openssl.org/source) | | Yes | | | -| PCRE | | | | | [Yes](https://github.com/bitcoin/bitcoin/blob/master/depends/packages/qt.mk#L66) | +| PCRE | | | | | [Yes](https://github.com/bitcoin/bitcoin/blob/master/depends/packages/qt.mk) | | protobuf | [2.6.1](https://github.com/google/protobuf/releases) | | No | | | | Python (tests) | | [3.5](https://www.python.org/downloads) | | | | | qrencode | [3.4.4](https://fukuchi.org/works/qrencode) | | No | | | | Qt | [5.9.7](https://download.qt.io/official_releases/qt/) | [5.5.1](https://github.com/bitcoin/bitcoin/issues/13478) | No | | | -| XCB | | | | | [Yes](https://github.com/bitcoin/bitcoin/blob/master/depends/packages/qt.mk#L87) (Linux only) | -| xkbcommon | | | | | [Yes](https://github.com/bitcoin/bitcoin/blob/master/depends/packages/qt.mk#L86) (Linux only) | +| XCB | | | | | [Yes](https://github.com/bitcoin/bitcoin/blob/master/depends/packages/qt.mk) (Linux only) | +| xkbcommon | | | | | [Yes](https://github.com/bitcoin/bitcoin/blob/master/depends/packages/qt.mk) (Linux only) | | ZeroMQ | [4.3.1](https://github.com/zeromq/libzmq/releases) | 4.0.0 | No | | | | zlib | [1.2.11](https://zlib.net/) | | | | No | diff --git a/doc/developer-notes.md b/doc/developer-notes.md index cf071167c4..39463dc6f8 100644 --- a/doc/developer-notes.md +++ b/doc/developer-notes.md @@ -34,7 +34,6 @@ Developer Notes - [Source code organization](#source-code-organization) - [GUI](#gui) - [Subtrees](#subtrees) - - [Git and GitHub tips](#git-and-github-tips) - [Scripted diffs](#scripted-diffs) - [Release notes](#release-notes) - [RPC interface guidelines](#rpc-interface-guidelines) @@ -280,7 +279,7 @@ thread](https://askubuntu.com/questions/50145/how-to-install-perf-monitoring-too for specific instructions. Certain kernel parameters may need to be set for perf to be able to inspect the -running process' stack. +running process's stack. ```sh $ sudo sysctl -w kernel.perf_event_paranoid=-1 @@ -376,7 +375,7 @@ reported in the debug.log file. Re-architecting the core code so there are better-defined interfaces between the various components is a goal, with any necessary locking -done by the components (e.g. see the self-contained `CBasicKeyStore` class +done by the components (e.g. see the self-contained `FillableSigningProvider` class and its `cs_KeyStore` lock for example). Threads @@ -478,6 +477,14 @@ Wallet General C++ ------------- +For general C++ guidelines, you may refer to the [C++ Core +Guidelines](https://isocpp.github.io/CppCoreGuidelines/). + +Common misconceptions are clarified in those sections: + +- Passing (non-)fundamental types in the [C++ Core + Guideline](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rf-conventional) + - Assertions should not have side-effects - *Rationale*: Even though the source code is set to refuse to compile diff --git a/doc/fuzzing.md b/doc/fuzzing.md index f9221dde5b..3dc6be8b86 100644 --- a/doc/fuzzing.md +++ b/doc/fuzzing.md @@ -46,7 +46,7 @@ export AFLPATH=$PWD To build Bitcoin Core using AFL instrumentation (this assumes that the `AFLPATH` was set as above): ``` -./configure --disable-ccache --disable-shared --enable-tests --enable-fuzz --disable-wallet --disable-bench --with-utils=no --with-daemon=no --with-libs=no --with-gui=no CC=${AFLPATH}/afl-gcc CXX=${AFLPATH}/afl-g++ +./configure --disable-ccache --disable-shared --enable-tests --enable-fuzz CC=${AFLPATH}/afl-gcc CXX=${AFLPATH}/afl-g++ export AFL_HARDEN=1 cd src/ make @@ -83,7 +83,7 @@ found in the `compiler-rt` runtime libraries package). To build all fuzz targets with libFuzzer, run ``` -./configure --disable-ccache --disable-wallet --disable-bench --with-utils=no --with-daemon=no --with-libs=no --with-gui=no --enable-fuzz --with-sanitizers=fuzzer,address CC=clang CXX=clang++ +./configure --disable-ccache --enable-fuzz --with-sanitizers=fuzzer,address CC=clang CXX=clang++ make ``` diff --git a/doc/man/bitcoin-qt.1 b/doc/man/bitcoin-qt.1 index 052d420608..1e8443b1d3 100644 --- a/doc/man/bitcoin-qt.1 +++ b/doc/man/bitcoin-qt.1 @@ -488,9 +488,6 @@ Relay and mine data carrier transactions (default: 1) Maximum size of data in data carrier transactions we relay and mine (default: 83) .HP -\fB\-mempoolreplacement\fR -.IP -Enable transaction replacement in the memory pool (default: 1) .HP \fB\-minrelaytxfee=\fR<amt> .IP diff --git a/doc/man/bitcoind.1 b/doc/man/bitcoind.1 index 5e057d923f..2a79b6cb46 100644 --- a/doc/man/bitcoind.1 +++ b/doc/man/bitcoind.1 @@ -488,10 +488,6 @@ Relay and mine data carrier transactions (default: 1) Maximum size of data in data carrier transactions we relay and mine (default: 83) .HP -\fB\-mempoolreplacement\fR -.IP -Enable transaction replacement in the memory pool (default: 1) -.HP \fB\-minrelaytxfee=\fR<amt> .IP Fees (in BTC/kB) smaller than this are considered zero fee for relaying, diff --git a/doc/productivity.md b/doc/productivity.md index a93228ebdb..b25ddc94e5 100644 --- a/doc/productivity.md +++ b/doc/productivity.md @@ -10,6 +10,7 @@ Table of Contents * [Make use of your threads with `make -j`](#make-use-of-your-threads-with-make--j) * [Only build what you need](#only-build-what-you-need) * [Multiple working directories with `git worktrees`](#multiple-working-directories-with-git-worktrees) + * [Interactive "dummy rebases" for fixups and execs with `git merge-base`](#interactive-dummy-rebases-for-fixups-and-execs-with-git-merge-base) * [Writing code](#writing-code) * [Format C/C++/Protobuf diffs with `clang-format-diff.py`](#format-ccprotobuf-diffs-with-clang-format-diffpy) * [Format Python diffs with `yapf-diff.py`](#format-python-diffs-with-yapf-diffpy) @@ -93,6 +94,21 @@ To simply check out a commit-ish under a new working directory without disruptin git worktree add --checkout ../where-my-checkout-commit-ish-will-live my-checkout-commit-ish ``` +### Interactive "dummy rebases" for fixups and execs with `git merge-base` + +When rebasing, we often want to do a "dummy rebase," whereby we are not rebasing over an updated master but rather over the last common commit with master. This might be useful for rearranging commits, `rebase --autosquash`ing, or `rebase --exec`ing without introducing conflicts that arise from an updated master. In these situations, we can use `git merge-base` to identify the last common commit with master, and rebase off of that. + +To squash in `git commit --fixup` commits without rebasing over an updated master, we can do the following: + +```sh +git rebase -i --autosquash "$(git merge-base master HEAD)" +``` + +To execute `make check` on every commit since last diverged from master, but without rebasing over an updated master, we can do the following: +```sh +git rebase -i --exec "make check" "$(git merge-base master HEAD)" +``` + ----- This synergizes well with [`ccache`](#cache-compilations-with-ccache) as objects resulting from unchanged code will most likely hit the cache and won't need to be recompiled. diff --git a/doc/psbt.md b/doc/psbt.md index 9d85af0348..c411b31d5d 100644 --- a/doc/psbt.md +++ b/doc/psbt.md @@ -82,9 +82,10 @@ hardware implementations will typically implement multiple roles simultaneously. transactions. - **`decodepsbt`** is a diagnostic utility RPC which will show all information in a PSBT in human-readable form, as well as compute its eventual fee if known. -- **`analyzepsbt`** is a utility RPC that examines an RPC and reports the - next steps in the workflow if known, computes the fee of the resulting - transaction, and estimates the weight and feerate if possible. +- **`analyzepsbt`** is a utility RPC that examines a PSBT and reports the + current status of its inputs, the next step in the workflow if known, and if + possible, computes the fee of the resulting transaction and estimates the + final weight and feerate. ### Workflows diff --git a/doc/reduce-memory.md b/doc/reduce-memory.md new file mode 100644 index 0000000000..8d8ccdfedc --- /dev/null +++ b/doc/reduce-memory.md @@ -0,0 +1,49 @@ +# Reduce Memory + +There are a few parameters that can be dialed down to reduce the memory usage of `bitcoind`. This can be useful on embedded systems or small VPSes. + +## In-memory caches + +The size of some in-memory caches can be reduced. As caches trade off memory usage for performance, reducing these will usually have a negative effect on performance. + +- `-dbcache=<n>` - the UTXO database cache size, this defaults to `450`. The unit is MiB (1024). + - The minimum value for `-dbcache` is 4. + - A lower `-dbcache` makes initial sync time much longer. After the initial sync, the effect is less pronounced for most use-cases, unless fast validation of blocks is important, such as for mining. + +## Memory pool + +- In Bitcoin Core there is a memory pool limiter which can be configured with `-maxmempool=<n>`, where `<n>` is the size in MB (1000). The default value is `300`. + - The minimum value for `-maxmempool` is 5. + - A lower maximum mempool size means that transactions will be evicted sooner. This will affect any uses of `bitcoind` that process unconfirmed transactions. + +- To completely disable mempool functionality there is the option `-blocksonly`. This will make the client opt out of receiving (and thus relaying) transactions completely, except as part of blocks. + + - Do not use this when using the client to broadcast transactions as any transaction sent will stick out like a sore thumb, affecting privacy. When used with the wallet it should be combined with `-walletbroadcast=0` and `-spendzeroconfchange=0`. Another mechanism for broadcasting outgoing transactions (if any) should be used. + +- Since `0.14.0`, unused memory allocated to the mempool (default: 300MB) is shared with the UTXO cache, so when trying to reduce memory usage you should limit the mempool, with the `-maxmempool` command line argument. + +## Number of peers + +- `-maxconnections=<n>` - the maximum number of connections, this defaults to `125`. Each active connection takes up some memory. Only significant if incoming + connections are enabled, otherwise the number of connections will never be more than `8`. + +## Thread configuration + +For each thread a thread stack needs to be allocated. By default on Linux, +threads take up 8MiB for the thread stack on a 64-bit system, and 4MiB in a +32-bit system. + +- `-par=<n>` - the number of script verification threads, defaults to the number of cores in the system minus one. +- `-rpcthreads=<n>` - the number of threads used for processing RPC requests, defaults to `4`. + +## Linux specific + +By default, since glibc `2.10`, the C library will create up to two heap arenas per core. This is known to cause excessive memory usage in some scenarios. To avoid this make a script that sets `MALLOC_ARENA_MAX` before starting bitcoind: + +```bash +#!/bin/bash +export MALLOC_ARENA_MAX=1 +bitcoind +``` + +The behavior was introduced to increase CPU locality of allocated memory and performance with concurrent allocation, so this setting could in theory reduce performance. However, in Bitcoin Core very little parallel allocation happens, so the impact is expected to be small or absent. diff --git a/doc/reduce-traffic.md b/doc/reduce-traffic.md index dd1469f563..5a71f62e0f 100644 --- a/doc/reduce-traffic.md +++ b/doc/reduce-traffic.md @@ -35,3 +35,16 @@ blocks and transactions to fewer nodes. Reducing the maximum connected nodes to a minimum could be desirable if traffic limits are tiny. Keep in mind that bitcoin's trustless model works best if you are connected to a handful of nodes. + +## 4. Turn off transaction relay (`-blocksonly`) + +Forwarding transactions to peers increases the P2P traffic. To only sync blocks +with other peers, you can disable transaction relay. + +Be reminded of the effects of this setting. + +- Fee estimation will no longer work. +- Not relaying other's transactions could hurt your privacy if used while a + wallet is loaded or if you use the node to broadcast transactions. +- It makes block propagation slower because compact block relay can only be + used when transaction relay is enabled. diff --git a/doc/release-notes-0.18.1-16257.md b/doc/release-notes-0.18.1-16257.md new file mode 100644 index 0000000000..21867b7fb2 --- /dev/null +++ b/doc/release-notes-0.18.1-16257.md @@ -0,0 +1,6 @@ +Wallet changes +-------------- +When creating a transaction with a fee above `-maxtxfee` (default 0.1 BTC), +the RPC commands `walletcreatefundedpsbt` and `fundrawtransaction` will now fail +instead of rounding down the fee. Beware that the `feeRate` argument is specified +in BTC per kilobyte, not satoshi per byte. diff --git a/doc/release-notes-13756.md b/doc/release-notes-13756.md new file mode 100644 index 0000000000..a500aceb0f --- /dev/null +++ b/doc/release-notes-13756.md @@ -0,0 +1,41 @@ +Coin selection +-------------- + +### Reuse Avoidance + +A new wallet flag `avoid_reuse` has been added (default off). When enabled, +a wallet will distinguish between used and unused addresses, and default to not +use the former in coin selection. + +Rescanning the blockchain is required, to correctly mark previously +used destinations. + +Together with "avoid partial spends" (present as of Bitcoin v0.17), this +addresses a serious privacy issue where a malicious user can track spends by +peppering a previously paid to address with near-dust outputs, which would then +be inadvertently included in future payments. + +New RPCs +-------- + +- A new `setwalletflag` RPC sets/unsets flags for an existing wallet. + + +Updated RPCs +------------ + +Several RPCs have been updated to include an "avoid_reuse" flag, used to control +whether already used addresses should be left out or included in the operation. +These include: + +- createwallet +- getbalance +- getbalances +- sendtoaddress + +In addition, `sendtoaddress` has been changed to avoid partial spends when `avoid_reuse` +is enabled (if not already enabled via the `-avoidpartialspends` command line flag), +as it would otherwise risk using up the "wrong" UTXO for an address reuse case. + +The listunspent RPC has also been updated to now include a "reused" bool, for nodes +with "avoid_reuse" enabled. diff --git a/doc/release-notes-14802.md b/doc/release-notes-14802.md new file mode 100644 index 0000000000..1fcc38866a --- /dev/null +++ b/doc/release-notes-14802.md @@ -0,0 +1,3 @@ +RPC changes +----------- +The `getblockstats` RPC is faster for fee calculation by using BlockUndo data. Also, `-txindex` is no longer required and `getblockstats` works for all non-pruned blocks. diff --git a/doc/release-notes-14954.md b/doc/release-notes-14954.md new file mode 100644 index 0000000000..4bb0fcca74 --- /dev/null +++ b/doc/release-notes-14954.md @@ -0,0 +1,3 @@ +Build system changes +-------------------- +Python >=3.5 is now required by all aspects of the project. This includes the build systems, test framework and linters. The previously supported minimum (3.4), was EOL in March 2019. See #14954 for more details.
\ No newline at end of file diff --git a/doc/release-notes-15006.md b/doc/release-notes-15006.md new file mode 100644 index 0000000000..76ed3247a6 --- /dev/null +++ b/doc/release-notes-15006.md @@ -0,0 +1,4 @@ +Miscellaneous RPC changes +------------ + +- `createwallet` can now create encrypted wallets if a non-empty passphrase is specified. diff --git a/doc/release-notes-15427.md b/doc/release-notes-15427.md new file mode 100644 index 0000000000..25edfd4402 --- /dev/null +++ b/doc/release-notes-15427.md @@ -0,0 +1,9 @@ +Updated RPCs +------------ + +The `utxoupdatepsbt` RPC method has been updated to take a `descriptors` +argument. When provided, input and output scripts and keys will be filled in +when known, and P2SH-witness inputs will be filled in from the UTXO set when a +descriptor is provided that shows they're spending segwit outputs. + +See the RPC help text for full details. diff --git a/doc/release-notes.md b/doc/release-notes.md index 834c9b36dc..afb0469291 100644 --- a/doc/release-notes.md +++ b/doc/release-notes.md @@ -1,12 +1,26 @@ -(note: this is a temporary file, to be added-to by anybody, and moved to -release-notes at release time) +*After branching off for a major version release of Bitcoin Core, use this +template to create the initial release notes draft.* + +*The release notes draft is a temporary file that can be added to by anyone. See +[/doc/developer-notes.md#release-notes](/doc/developer-notes.md#release-notes) +for the process.* + +*Create the draft, named* "*version* Release Notes Draft" +*(e.g. "0.20.0 Release Notes Draft"), as a collaborative wiki in:* + +https://github.com/bitcoin-core/bitcoin-devwiki/wiki/ + +*Before the final release, move the notes back to this git repository.* + +*version* Release Notes Draft +=============================== Bitcoin Core version *version* is now available from: <https://bitcoincore.org/bin/bitcoin-core-*version*/> -This is a new major version release, including new features, various bugfixes -and performance improvements, as well as updated translations. +This release includes new features, various bug fixes and performance +improvements, as well as updated translations. Please report bugs using the issue tracker at GitHub: @@ -28,30 +42,19 @@ Upgrading directly from a version of Bitcoin Core that has reached its EOL is possible, but might take some time if the datadir needs to be migrated. Old wallet versions of Bitcoin Core are generally supported. -Downgrading warning -------------------- - -The chainstate database for this release is not compatible with previous -releases, so if you run 0.15 and then decide to switch back to any -older version, you will need to run the old release with the `-reindex-chainstate` -option to rebuild the chainstate data structures in the old format. - -If your node has pruning enabled, this will entail re-downloading and -processing the entire blockchain. - Compatibility ============== Bitcoin Core is supported and extensively tested on operating systems using -the Linux kernel, macOS 10.10+, and Windows 7 and newer. It is not recommended +the Linux kernel, macOS 10.10+, and Windows 7 and newer. It is not recommended to use Bitcoin Core on unsupported systems. Bitcoin Core should also work on most other Unix-like systems but is not -frequently tested on them. +as frequently tested on them. -From 0.17.0 onwards, macOS <10.10 is no longer supported. 0.17.0 is +From 0.17.0 onwards, macOS <10.10 is no longer supported. 0.17.0 is built using Qt 5.9.x, which doesn't support versions of macOS older than -10.10. Additionally, Bitcoin Core does not yet change appearance when +10.10. Additionally, Bitcoin Core does not yet change appearance when macOS "dark mode" is activated. In addition to previously-supported CPU platforms, this release's @@ -76,7 +79,7 @@ Updated RPCs Note: some low-level RPC changes mainly useful for testing are described in the Low-level Changes section below. -* The `sendmany` RPC had an argument `minconf` that was not well specified and +- The `sendmany` RPC had an argument `minconf` that was not well specified and would lead to RPC errors even when the wallet's coin selection would succeed. The `sendtoaddress` RPC never had this check, so to normalize the behavior, `minconf` is now ignored in `sendmany`. If the coin selection does not @@ -89,14 +92,49 @@ Low-level Changes section below. Low-level changes ================= +RPC +--- + + +Tests +----- + +- The regression test chain, that can be enabled by the `-regtest` command line + flag, now requires transactions to not violate standard policy by default. + Making the default the same as for mainnet, makes it easier to test mainnet + behavior on regtest. Be reminded that the testnet still allows non-standard + txs by default and that the policy can be locally adjusted with the + `-acceptnonstdtxn` command line flag for both test chains. + Configuration ------------ -* An error is issued where previously a warning was issued when a setting in +- An error is issued where previously a warning was issued when a setting in the config file was specified in the default section, but not overridden for the selected network. This change takes only effect if the selected network is not mainnet. +Network +------- + +- When fetching a transaction announced by multiple peers, previous versions of + Bitcoin Core would sequentially attempt to download the transaction from each + announcing peer until the transaction is received, in the order that those + peers' announcements were received. In this release, the download logic has + changed to randomize the fetch order across peers and to prefer sending + download requests to outbound peers over inbound peers. This fixes an issue + where inbound peers can prevent a node from getting a transaction. + +Wallet +------ + +- When in pruned mode, a rescan that was triggered by an `importwallet`, + `importpubkey`, `importaddress`, or `importprivkey` RPC will only fail when + blocks have been pruned. Previously it would fail when `-prune` has been set. + This change allows to set `-prune` to a high value (e.g. the disk size) and + the calls to any of the import RPCs would fail when the first block is + pruned. + Credits ======= diff --git a/doc/release-notes/release-notes-0.12.0.md b/doc/release-notes/release-notes-0.12.0.md index cf74a17975..bc0d5ea3b0 100644 --- a/doc/release-notes/release-notes-0.12.0.md +++ b/doc/release-notes/release-notes-0.12.0.md @@ -127,7 +127,7 @@ minimum relay feerate. The initial minimum relay feerate is set to Bitcoin Core 0.12 also introduces new default policy limits on the length and size of unconfirmed transaction chains that are allowed in the mempool (generally limiting the length of unconfirmed chains to 25 transactions, with a -total size of 101 KB). These limits can be overriden using command line +total size of 101 KB). These limits can be overridden using command line arguments; see the extended help (`--help -help-debug`) for more information. Opt-in Replace-by-fee transactions diff --git a/doc/release-notes/release-notes-16152.md b/doc/release-notes/release-notes-16152.md new file mode 100644 index 0000000000..9c77cb9ae5 --- /dev/null +++ b/doc/release-notes/release-notes-16152.md @@ -0,0 +1,7 @@ +P2P Changes +----------- +- The default value for the -peerbloomfilters configuration option (and, thus, NODE_BLOOM support) has been changed to false. + This resolves well-known DoS vectors in Bitcoin Core, especially for nodes with spinning disks. It is not anticipated that + this will result in a significant lack of availability of NODE_BLOOM-enabled nodes in the coming years, however, clients + which rely on the availability of NODE_BLOOM-supporting nodes on the P2P network should consider the process of migrating + to a more modern (and less trustful and privacy-violating) alternative over the coming years. diff --git a/doc/release-process.md b/doc/release-process.md index 7522310ce2..480b09ee11 100644 --- a/doc/release-process.md +++ b/doc/release-process.md @@ -1,17 +1,19 @@ Release Process ==================== -Before every release candidate: +## Branch updates + +### Before every release candidate * Update translations (ping wumpus on IRC) see [translation_process.md](https://github.com/bitcoin/bitcoin/blob/master/doc/translation_process.md#synchronising-translations). * Update manpages, see [gen-manpages.sh](https://github.com/bitcoin/bitcoin/blob/master/contrib/devtools/README.md#gen-manpagessh). * Update release candidate version in `configure.ac` (`CLIENT_VERSION_RC`). -Before every minor and major release: +### Before every major and minor release * Update [bips.md](bips.md) to account for changes since the last release. * Update version in `configure.ac` (don't forget to set `CLIENT_VERSION_RC` to `0`). -* Write release notes (see below). +* Write release notes (see "Write the release notes" below). * Update `src/chainparams.cpp` nMinimumChainWork with information from the getblockchaininfo rpc. * Update `src/chainparams.cpp` defaultAssumeValid with information from the getblockhash rpc. - The selected value must not be orphaned so it may be useful to set the value two blocks back from the tip. @@ -19,20 +21,39 @@ Before every minor and major release: - This update should be reviewed with a reindex-chainstate with assumevalid=0 to catch any defect that causes rejection of blocks in the past history. -Before every major release: +### Before every major release * Update hardcoded [seeds](/contrib/seeds/README.md), see [this pull request](https://github.com/bitcoin/bitcoin/pull/7415) for an example. * Update [`src/chainparams.cpp`](/src/chainparams.cpp) m_assumed_blockchain_size and m_assumed_chain_state_size with the current size plus some overhead. * Update `src/chainparams.cpp` chainTxData with statistics about the transaction count and rate. Use the output of the RPC `getchaintxstats`, see [this pull request](https://github.com/bitcoin/bitcoin/pull/12270) for an example. Reviewers can verify the results by running `getchaintxstats <window_block_count> <window_last_block_hash>` with the `window_block_count` and `window_last_block_hash` from your output. -* Update version of `contrib/gitian-descriptors/*.yml`: usually one'd want to do this on master after branching off the release - but be sure to at least do it before a new major release. -* In `configure.ac` and `build_msvc/bitcoin_config.h` on _the master branch_: - - update `CLIENT_VERSION_MINOR` version -* In `configure.ac` and `build_msvc/bitcoin_config.h` on _a new release branch_ (see [this commit](https://github.com/bitcoin/bitcoin/commit/742f7dd972fca3dd4a33cfff90bf901b71a687e7)): - - update `CLIENT_VERSION_MINOR` version +* On both the master branch and the new release branch: + - update `CLIENT_VERSION_MINOR` in [`configure.ac`](../configure.ac) + - update `CLIENT_VERSION_MINOR`, `PACKAGE_VERSION`, and `PACKAGE_STRING` in [`build_msvc/bitcoin_config.h`](/build_msvc/bitcoin_config.h) +* On the new release branch in [`configure.ac`](../configure.ac) and [`build_msvc/bitcoin_config.h`](/build_msvc/bitcoin_config.h) (see [this commit](https://github.com/bitcoin/bitcoin/commit/742f7dd)): - set `CLIENT_VERSION_REVISION` to `0` - set `CLIENT_VERSION_IS_RELEASE` to `true` +#### Before branch-off + +- Clear the release notes and move them to the wiki (see "Write the release notes" below). + +#### After branch-off (on master) + +- Update the version of `contrib/gitian-descriptors/*.yml`. + +#### After branch-off (on the major release branch) + +- Update the versions and the link to the release notes draft in `doc/release-notes.md`. + +#### Before final release + +- Merge the release notes from the wiki into the branch. +- Ensure the "Needs release note" label is removed from all relevant pull requests and issues. + + +## Building + ### First time / New builders If you're using the automated script (found in [contrib/gitian-build.py](/contrib/gitian-build.py)), then at this point you should run it with the "--setup" command. Otherwise ignore this. @@ -45,22 +66,26 @@ Check out the source code in the following directory hierarchy. git clone https://github.com/devrandom/gitian-builder.git git clone https://github.com/bitcoin/bitcoin.git -### Bitcoin maintainers/release engineers, suggestion for writing release notes +### Write the release notes + +Open a draft of the release notes for collaborative editing at https://github.com/bitcoin-core/bitcoin-devwiki/wiki. -Write release notes. git shortlog helps a lot, for example: +For the period during which the notes are being edited on the wiki, the version on the branch should be wiped and replaced with a link to the wiki which should be used for all announcements until `-final`. - git shortlog --no-merges v(current version, e.g. 0.7.2)..v(new version, e.g. 0.8.0) +Write the release notes. `git shortlog` helps a lot, for example: + + git shortlog --no-merges v(current version, e.g. 0.19.2)..v(new version, e.g. 0.20.0) (or ping @wumpus on IRC, he has specific tooling to generate the list of merged pulls -and sort them into categories based on labels) +and sort them into categories based on labels). Generate list of authors: - git log --format='- %aN' v(current version, e.g. 0.16.0)..v(new version, e.g. 0.16.1) | sort -fiu + git log --format='- %aN' v(current version, e.g. 0.20.0)..v(new version, e.g. 0.20.1) | sort -fiu -Tag version (or release candidate) in git +Tag the version (or release candidate) in git: - git tag -s v(new version, e.g. 0.8.0) + git tag -s v(new version, e.g. 0.20.0) ### Setup and perform Gitian builds @@ -70,7 +95,7 @@ Setup Gitian descriptors: pushd ./bitcoin export SIGNER="(your Gitian key, ie bluematt, sipa, etc)" - export VERSION=(new version, e.g. 0.8.0) + export VERSION=(new version, e.g. 0.20.0) git fetch git checkout v${VERSION} popd @@ -221,7 +246,6 @@ Create (and optionally verify) the signed Windows binaries: ./bin/gsign --signer "$SIGNER" --release ${VERSION}-win-signed --destination ../gitian.sigs/ ../bitcoin/contrib/gitian-descriptors/gitian-win-signer.yml ./bin/gverify -v -d ../gitian.sigs/ -r ${VERSION}-win-signed ../bitcoin/contrib/gitian-descriptors/gitian-win-signer.yml mv build/out/bitcoin-*win64-setup.exe ../bitcoin-${VERSION}-win64-setup.exe - mv build/out/bitcoin-*win32-setup.exe ../bitcoin-${VERSION}-win32-setup.exe popd Commit your signature for the signed macOS/Windows binaries: @@ -229,7 +253,7 @@ Commit your signature for the signed macOS/Windows binaries: pushd gitian.sigs git add ${VERSION}-osx-signed/"${SIGNER}" git add ${VERSION}-win-signed/"${SIGNER}" - git commit -a + git commit -m "Add ${SIGNER} ${VERSION} signed binaries signatures" git push # Assuming you can push to the gitian.sigs tree popd @@ -246,12 +270,11 @@ The list of files should be: bitcoin-${VERSION}-aarch64-linux-gnu.tar.gz bitcoin-${VERSION}-arm-linux-gnueabihf.tar.gz bitcoin-${VERSION}-i686-pc-linux-gnu.tar.gz +bitcoin-${VERSION}-riscv64-linux-gnu.tar.gz bitcoin-${VERSION}-x86_64-linux-gnu.tar.gz bitcoin-${VERSION}-osx64.tar.gz bitcoin-${VERSION}-osx.dmg bitcoin-${VERSION}.tar.gz -bitcoin-${VERSION}-win32-setup.exe -bitcoin-${VERSION}-win32.zip bitcoin-${VERSION}-win64-setup.exe bitcoin-${VERSION}-win64.zip ``` @@ -300,6 +323,9 @@ bitcoin.org (see below for bitcoin.org update instructions). - bitcoincore.org blog post + - bitcoincore.org maintained versions update: + [table](https://github.com/bitcoin-core/bitcoincore.org/commits/master/_includes/posts/maintenance-table.md) + - bitcoincore.org RPC documentation update - Update packaging repo @@ -326,9 +352,11 @@ bitcoin.org (see below for bitcoin.org update instructions). - This repo - - Archive release notes for the new version to `doc/release-notes/` (branch `master` and branch of the release) + - Archive the release notes for the new version to `doc/release-notes/` (branch `master` and branch of the release) + + - Create a [new GitHub release](https://github.com/bitcoin/bitcoin/releases/new) with a link to the archived release notes - - Create a [new GitHub release](https://github.com/bitcoin/bitcoin/releases/new) with a link to the archived release notes. + - Create a pinned meta-issue for testing the release candidate (see [this issue](https://github.com/bitcoin/bitcoin/issues/15555) for an example) and provide a link to it in the release announcements where useful - Announce the release: |