Create developer-notes.md

Moves coding guidelines and development tips/tricks into a single file.
Also adds a section explaining pull request terminology.
This commit is contained in:
Michael Ford 2014-12-13 12:35:39 +08:00
parent 4444b879bc
commit 3bf5f52808
3 changed files with 50 additions and 37 deletions

View File

@ -40,7 +40,7 @@ submitter will be asked to start a discussion (if they haven't already) on the
The patch will be accepted if there is broad consensus that it is a good thing. The patch will be accepted if there is broad consensus that it is a good thing.
Developers should expect to rework and resubmit patches if the code doesn't Developers should expect to rework and resubmit patches if the code doesn't
match the project's coding conventions (see [doc/coding.md](doc/coding.md)) or are match the project's coding conventions (see [doc/developer-notes.md](doc/developer-notes.md)) or are
controversial. controversial.
The `master` branch is regularly built and tested, but is not guaranteed to be The `master` branch is regularly built and tested, but is not guaranteed to be
@ -85,38 +85,3 @@ Translations are periodically pulled from Transifex and merged into the git repo
pull from Transifex would automatically overwrite them again. pull from Transifex would automatically overwrite them again.
Translators should also subscribe to the [mailing list](https://groups.google.com/forum/#!forum/bitcoin-translators). Translators should also subscribe to the [mailing list](https://groups.google.com/forum/#!forum/bitcoin-translators).
Development tips and tricks
---------------------------
**compiling for debugging**
Run configure with the --enable-debug option, then make. Or run configure with
CXXFLAGS="-g -ggdb -O0" or whatever debug flags you need.
**debug.log**
If the code is behaving strangely, take a look in the debug.log file in the data directory;
error and debugging messages are written there.
The -debug=... command-line option controls debugging; running with just -debug will turn
on all categories (and give you a very large debug.log file).
The Qt code routes qDebug() output to debug.log under category "qt": run with -debug=qt
to see it.
**testnet and regtest modes**
Run with the -testnet option to run with "play bitcoins" on the test network, if you
are testing multi-machine code that needs to operate across the internet.
If you are testing something that can run on one machine, run with the -regtest option.
In regression test mode, blocks can be created on-demand; see qa/rpc-tests/ for tests
that run in -regtest mode.
**DEBUG_LOCKORDER**
Bitcoin Core is a multithreaded application, and deadlocks or other multithreading bugs
can be very difficult to track down. Compiling with -DDEBUG_LOCKORDER (configure
CXXFLAGS="-DDEBUG_LOCKORDER -g") inserts run-time checks to keep track of which locks
are held, and adds warnings to the debug.log file if inconsistencies are detected.

View File

@ -51,7 +51,7 @@ Development
--------------------- ---------------------
The Bitcoin repo's [root README](https://github.com/bitcoin/bitcoin/blob/master/README.md) contains relevant information on the development process and automated testing. The Bitcoin repo's [root README](https://github.com/bitcoin/bitcoin/blob/master/README.md) contains relevant information on the development process and automated testing.
- [Coding Guidelines](coding.md) - [Developer Notes](developer-notes.md)
- [Multiwallet Qt Development](multiwallet-qt.md) - [Multiwallet Qt Development](multiwallet-qt.md)
- [Release Notes](release-notes.md) - [Release Notes](release-notes.md)
- [Release Process](release-process.md) - [Release Process](release-process.md)

View File

@ -89,6 +89,41 @@ Not OK (used plenty in the current source, but not picked up):
A full list of comment syntaxes picked up by doxygen can be found at http://www.stack.nl/~dimitri/doxygen/manual/docblocks.html, A full list of comment syntaxes picked up by doxygen can be found at http://www.stack.nl/~dimitri/doxygen/manual/docblocks.html,
but if possible use one of the above styles. but if possible use one of the above styles.
Development tips and tricks
---------------------------
**compiling for debugging**
Run configure with the --enable-debug option, then make. Or run configure with
CXXFLAGS="-g -ggdb -O0" or whatever debug flags you need.
**debug.log**
If the code is behaving strangely, take a look in the debug.log file in the data directory;
error and debugging messages are written there.
The -debug=... command-line option controls debugging; running with just -debug will turn
on all categories (and give you a very large debug.log file).
The Qt code routes qDebug() output to debug.log under category "qt": run with -debug=qt
to see it.
**testnet and regtest modes**
Run with the -testnet option to run with "play bitcoins" on the test network, if you
are testing multi-machine code that needs to operate across the internet.
If you are testing something that can run on one machine, run with the -regtest option.
In regression test mode, blocks can be created on-demand; see qa/rpc-tests/ for tests
that run in -regtest mode.
**DEBUG_LOCKORDER**
Bitcoin Core is a multithreaded application, and deadlocks or other multithreading bugs
can be very difficult to track down. Compiling with -DDEBUG_LOCKORDER (configure
CXXFLAGS="-DDEBUG_LOCKORDER -g") inserts run-time checks to keep track of which locks
are held, and adds warnings to the debug.log file if inconsistencies are detected.
Locking/mutex usage notes Locking/mutex usage notes
------------------------- -------------------------
@ -136,3 +171,16 @@ Threads
- BitcoinMiner : Generates bitcoins (if wallet is enabled). - BitcoinMiner : Generates bitcoins (if wallet is enabled).
- Shutdown : Does an orderly shutdown of everything. - Shutdown : Does an orderly shutdown of everything.
Pull Request Terminology
------------------------
Concept ACK - Agree with the idea and overall direction, but haven't reviewed the code changes or tested them.
utACK (untested ACK) - Reviewed and agree with the code changes but haven't actually tested them.
Tested ACK - Reviewed the code changes and have verified the functionality or bug fix.
ACK - A loose ACK can be confusing. It's best to avoid them unless it's a documentation/comment only change in which case there is nothing to test/verify; therefore the tested/untested distinction is not there.
NACK - Disagree with the code changes/concept. Should be accompanied by an explanation.