mirror of
https://github.com/bitcoin/bitcoin.git
synced 2026-01-31 10:41:08 +00:00
Merge bitcoin/bitcoin#32572: doc: Remove stale sections in dev notes
fac00d4ed361e5e8c8989b2bb5a4a22dd54e2c72 doc: Move CI-must-pass requirement into readme section (MarcoFalke)
fab79c1a250db252baa206f59d7e46986e21a57c doc: Clarify and move "hygienic commit" note (MarcoFalke)
fac8b051979911f036f9156b2d4e7afbe2853336 doc: Clarify strprintf size specifier note (MarcoFalke)
faaf34ad7253e3d347af986305e405e6ef35f459 doc: Remove section about RPC alias via function pointer (MarcoFalke)
2222d61e1ce5c9efd099f33b5dda934bc9d2d57f doc: Remove section about RPC arg names in table (MarcoFalke)
fa00b8c02c9de6dca833b83dc6447ba31d72ca57 doc: Remove section about include guards (MarcoFalke)
fad6cd739b638cf7e8c86cdccf98df070e64a0f9 doc: Remove dev note section on includes (MarcoFalke)
fa6623d85af192c8aa1d0380d4a5452e0779c64e doc: Remove file name section (MarcoFalke)
7777fb8bc749e18c178ef460b65219187e676128 doc: Remove shebang section (MarcoFalke)
faf65f05312be7647f485f088ba00fef97f47bf4 doc: Remove .gitignore section (MarcoFalke)
faf2094f2511a5322d68d2352f244b5bc89d5fee doc: Remove note about removed ParsePrechecks (MarcoFalke)
fa69c5b170f56d554fcb0d0887bd27f961fe3e74 doc: Remove -disablewallet from dev notes (MarcoFalke)
Pull request description:
This removes sections that I've been collecting as stale or overly redundant over the years. The rationale for each removal is in the commit message.
ACKs for top commit:
yuvicc:
ACK fac00d4ed361e5e8c8989b2bb5a4a22dd54e2c72
janb84:
LGTM ACK fac00d4ed361e5e8c8989b2bb5a4a22dd54e2c72
glozow:
ACK fac00d4ed361e5e8c8989b2bb5a4a22dd54e2c72, all lgtm
Tree-SHA512: 17a5b4277fb30d265959d1230a705b36d8501a64c0f4a7f272ea5d9c22031421f95c491144f6d6f714dc7927df667d96ece9ceb43e0a07317d76fdcc4769aaa7
This commit is contained in:
merge-script
commit
ebec7bf389
@ -115,6 +115,7 @@ fixes or code moves with actual code changes.
|
||||
|
||||
Make sure each individual commit is hygienic: that it builds successfully on its
|
||||
own without warnings, errors, regressions, or test failures.
|
||||
This means tests must be updated in the same commit that changes the behavior.
|
||||
|
||||
Commit messages should be verbose by default consisting of a short subject line
|
||||
(50 chars max), a blank line and detailed explanatory text as separate
|
||||
|
||||
@ -56,8 +56,8 @@ in Python.
|
||||
These tests can be run (if the [test dependencies](/test) are installed) with: `build/test/functional/test_runner.py`
|
||||
(assuming `build` is your build directory).
|
||||
|
||||
The CI (Continuous Integration) systems make sure that every pull request is built for Windows, Linux, and macOS,
|
||||
and that unit/sanity tests are run automatically.
|
||||
The CI (Continuous Integration) systems make sure that every pull request is tested on Windows, Linux, and macOS.
|
||||
The CI must pass on all commits before merge to avoid unrelated CI failures on new pull requests.
|
||||
|
||||
### Manual Quality Assurance (QA) Testing
|
||||
|
||||
|
||||
@ -784,38 +784,6 @@ Threads
|
||||
- [ThreadI2PAcceptIncoming (`b-i2paccept`)](https://doxygen.bitcoincore.org/class_c_connman.html#a57787b4f9ac847d24065fbb0dd6e70f8)
|
||||
: Listens for and accepts incoming I2P connections through the I2P SAM proxy.
|
||||
|
||||
Ignoring IDE/editor files
|
||||
--------------------------
|
||||
|
||||
In closed-source environments in which everyone uses the same IDE, it is common
|
||||
to add temporary files it produces to the project-wide `.gitignore` file.
|
||||
|
||||
However, in open source software such as Bitcoin Core, where everyone uses
|
||||
their own editors/IDE/tools, it is less common. Only you know what files your
|
||||
editor produces and this may change from version to version. The canonical way
|
||||
to do this is thus to create your local gitignore. Add this to `~/.gitconfig`:
|
||||
|
||||
```
|
||||
[core]
|
||||
excludesfile = /home/.../.gitignore_global
|
||||
```
|
||||
|
||||
(alternatively, type the command `git config --global core.excludesfile ~/.gitignore_global`
|
||||
on a terminal)
|
||||
|
||||
Then put your favourite tool's temporary filenames in that file, e.g.
|
||||
```
|
||||
# NetBeans
|
||||
nbproject/
|
||||
```
|
||||
|
||||
Another option is to create a per-repository excludes file `.git/info/exclude`.
|
||||
These are not committed but apply only to one repository.
|
||||
|
||||
If a set of tools is used by the build system or scripts the repository (for
|
||||
example, lcov) it is perfectly acceptable to add its files to `.gitignore`
|
||||
and commit them.
|
||||
|
||||
Development guidelines
|
||||
============================
|
||||
|
||||
@ -830,15 +798,6 @@ General Bitcoin Core
|
||||
- *Rationale*: RPC allows for better automatic testing. The test suite for
|
||||
the GUI is very limited.
|
||||
|
||||
- Make sure pull requests pass CI before merging.
|
||||
|
||||
- *Rationale*: Makes sure that they pass thorough testing, and that the tester will keep passing
|
||||
on the master branch. Otherwise, all new pull requests will start failing the tests, resulting in
|
||||
confusion and mayhem.
|
||||
|
||||
- *Explanation*: If the test suite is to be updated for a change, this has to
|
||||
be done first.
|
||||
|
||||
Logging
|
||||
-------
|
||||
|
||||
@ -878,11 +837,6 @@ Note that the format strings and parameters of `LogDebug` and `LogTrace`
|
||||
are only evaluated if the logging category is enabled, so you must be
|
||||
careful to avoid side-effects in those expressions.
|
||||
|
||||
Wallet
|
||||
-------
|
||||
|
||||
- Make sure that no crashes happen with run-time option `-disablewallet`.
|
||||
|
||||
General C++
|
||||
-------------
|
||||
|
||||
@ -1008,7 +962,7 @@ Strings and formatting
|
||||
buffer overflows, and surprises with `\0` characters. Also, some C string manipulations
|
||||
tend to act differently depending on platform, or even the user locale.
|
||||
|
||||
- For `strprintf`, `LogInfo`, `LogDebug`, etc formatting characters don't need size specifiers.
|
||||
- For `strprintf`, `LogInfo`, `LogDebug`, etc formatting characters don't need size specifiers (hh, h, l, ll, j, z, t, L) for arithmetic types.
|
||||
|
||||
- *Rationale*: Bitcoin Core uses tinyformat, which is type safe. Leave them out to avoid confusion.
|
||||
|
||||
@ -1032,7 +986,7 @@ Strings and formatting
|
||||
- In cases where you do call `.c_str()`, you might want to additionally check that the string does not contain embedded '\0' characters, because
|
||||
it will (necessarily) truncate the string. This might be used to hide parts of the string from logging or to circumvent
|
||||
checks. If a use of strings is sensitive to this, take care to check the string for embedded NULL characters first
|
||||
and reject it if there are any (see `ParsePrechecks` in `strencodings.cpp` for an example).
|
||||
and reject it if there are any.
|
||||
|
||||
Shadowing
|
||||
--------------
|
||||
@ -1159,27 +1113,7 @@ TRY_LOCK(cs_vNodes, lockNodes);
|
||||
Scripts
|
||||
--------------------------
|
||||
|
||||
Write scripts in Python rather than bash, when possible.
|
||||
|
||||
### Shebang
|
||||
|
||||
- Use `#!/usr/bin/env bash` instead of obsolete `#!/bin/bash`.
|
||||
|
||||
- [*Rationale*](https://github.com/dylanaraps/pure-bash-bible#shebang):
|
||||
|
||||
`#!/bin/bash` assumes it is always installed to /bin/ which can cause issues;
|
||||
|
||||
`#!/usr/bin/env bash` searches the user's PATH to find the bash binary.
|
||||
|
||||
OK:
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
```
|
||||
|
||||
Wrong:
|
||||
```bash
|
||||
#!/bin/bash
|
||||
```
|
||||
Write scripts in Python or Rust rather than bash, when possible.
|
||||
|
||||
Source code organization
|
||||
--------------------------
|
||||
@ -1189,12 +1123,6 @@ Source code organization
|
||||
|
||||
- *Rationale*: Shorter and simpler header files are easier to read and reduce compile time.
|
||||
|
||||
- Use only the lowercase alphanumerics (`a-z0-9`), underscore (`_`) and hyphen (`-`) in source code filenames.
|
||||
|
||||
- *Rationale*: `grep`:ing and auto-completing filenames is easier when using a consistent
|
||||
naming pattern. Potential problems when building on case-insensitive filesystems are
|
||||
avoided when using only lowercase characters in source code filenames.
|
||||
|
||||
- Every `.cpp` and `.h` file should `#include` every header file it directly uses classes, functions or other
|
||||
definitions from, even if those headers are already included indirectly through other headers.
|
||||
|
||||
@ -1222,24 +1150,6 @@ namespace {
|
||||
|
||||
- *Rationale*: Avoids confusion about the namespace context.
|
||||
|
||||
- Use `#include <primitives/transaction.h>` bracket syntax instead of
|
||||
`#include "primitives/transactions.h"` quote syntax.
|
||||
|
||||
- *Rationale*: Bracket syntax is less ambiguous because the preprocessor
|
||||
searches a fixed list of include directories without taking location of the
|
||||
source file into account. This allows quoted includes to stand out more when
|
||||
the location of the source file actually is relevant.
|
||||
|
||||
- Use include guards to avoid the problem of double inclusion. The header file
|
||||
`foo/bar.h` should use the include guard identifier `BITCOIN_FOO_BAR_H`, e.g.
|
||||
|
||||
```c++
|
||||
#ifndef BITCOIN_FOO_BAR_H
|
||||
#define BITCOIN_FOO_BAR_H
|
||||
...
|
||||
#endif // BITCOIN_FOO_BAR_H
|
||||
```
|
||||
|
||||
GUI
|
||||
-----
|
||||
|
||||
@ -1466,10 +1376,6 @@ A few guidelines for introducing and reviewing new RPC interfaces:
|
||||
- *Rationale*: Integer verbosity allows for multiple values. Undocumented boolean verbosity is deprecated
|
||||
and new RPC methods should prevent its use.
|
||||
|
||||
- Don't forget to fill in the argument names correctly in the RPC command table.
|
||||
|
||||
- *Rationale*: If not, the call cannot be used with name-based arguments.
|
||||
|
||||
- Add every non-string RPC argument `(method, idx, name)` to the table `vRPCConvertParams` in `rpc/client.cpp`.
|
||||
|
||||
- *Rationale*: `bitcoin-cli` and the GUI debug console use this table to determine how to
|
||||
@ -1501,17 +1407,6 @@ A few guidelines for introducing and reviewing new RPC interfaces:
|
||||
until the wallet is caught up to the chainstate as of the RPC call's entry.
|
||||
This also makes the API much easier for RPC clients to reason about.
|
||||
|
||||
- Be aware of RPC method aliases and generally avoid registering the same
|
||||
callback function pointer for different RPCs.
|
||||
|
||||
- *Rationale*: RPC methods registered with the same function pointer will be
|
||||
considered aliases and only the first method name will show up in the
|
||||
`help` RPC command list.
|
||||
|
||||
- *Exception*: Using RPC method aliases may be appropriate in cases where a
|
||||
new RPC is replacing a deprecated RPC, to avoid both RPCs confusingly
|
||||
showing up in the command list.
|
||||
|
||||
- Use *invalid* bech32 addresses (e.g. in the constant array `EXAMPLE_ADDRESS`) for
|
||||
`RPCExamples` help documentation.
|
||||
|
||||
|
||||
@ -26,6 +26,9 @@ ALLOWED_SOURCE_FILENAME_EXCEPTION_REGEXP = (
|
||||
ALLOWED_PERMISSION_NON_EXECUTABLES = 0o644
|
||||
ALLOWED_PERMISSION_EXECUTABLES = 0o755
|
||||
ALLOWED_EXECUTABLE_SHEBANG = {
|
||||
# https://github.com/dylanaraps/pure-bash-bible#shebang:
|
||||
# `#!/bin/bash` assumes it is always installed to /bin/ which can cause issues;
|
||||
# `#!/usr/bin/env bash` searches the user's PATH to find the bash binary.
|
||||
"py": [b"#!/usr/bin/env python3"],
|
||||
"sh": [b"#!/usr/bin/env bash", b"#!/bin/sh"],
|
||||
}
|
||||
|
||||
@ -83,7 +83,7 @@ def main():
|
||||
|
||||
if count != 3:
|
||||
print(f'{header_file} seems to be missing the expected '
|
||||
'include guard:')
|
||||
'include guard to prevent the double inclusion problem:')
|
||||
print(f' #ifndef {header_id}')
|
||||
print(f' #define {header_id}')
|
||||
print(' ...')
|
||||
|
||||
@ -166,6 +166,10 @@ def main():
|
||||
|
||||
# Enforce bracket syntax includes
|
||||
quote_syntax_inclusions = find_quote_syntax_inclusions()
|
||||
# *Rationale*: Bracket syntax is less ambiguous because the preprocessor
|
||||
# searches a fixed list of include directories without taking location of the
|
||||
# source file into account. This allows quoted includes to stand out more when
|
||||
# the location of the source file actually is relevant.
|
||||
|
||||
if quote_syntax_inclusions:
|
||||
print("Please use bracket syntax includes (\"#include <foo.h>\") instead of quote syntax includes:")
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user