docs: add "sections" info to example bitcoin.conf #15387

pull Csi18nAlistairMann wants to merge 1 commits into bitcoin:master from Csi18nAlistairMann:confSections changing 1 files +27 −0

Csi18nAlistairMann commented at 6:36 AM on February 12, 2019: contributor

Per #11862. Most bitcoin.conf options apply to all three networks, however some apply only to mainnet unless specified in a section. As stands, conf file has no indication that sections are now in use or are in some circumstances mandatory (eg, changing rpcport for testnet.)

Proposed change notifies the reader early which options are affected, specifically adds those options affected but not already in the example, adds brief explanation as to what's going on and provides a skeleton template for the sections themselves.
Per #11862. Most bitcoin.conf options apply to all three networks, however some apply only to mainnet unless specified in a section. As stands, conf file has no indication that sections are now in use or are in some circumstances mandatory (eg, changing rpcport for testnet.)
Proposed change notifies the reader early which options are affected, specifically adds those options affected but not already in the example, adds brief explanation as to what's going on and provides a skeleton template for the sections themselves.
76660fcb09
fanquake added the label Docs on Feb 12, 2019
laanwj commented at 6:55 AM on February 12, 2019: member

Nice addiction to the docs. utACK 76660fcb0992034bb15b00d5bfb8b498cc9673ee
jonasschnelli commented at 7:12 AM on February 12, 2019: contributor

utACK 76660fcb0992034bb15b00d5bfb8b498cc9673ee
fanquake commented at 7:13 AM on February 12, 2019: member

Thanks @Csi18nAlistairMann. In future, please try and re-use PRs for the same change (#15374).

utACK 76660fc

laanwj commented at 2:52 PM on February 12, 2019: member

Please do shorten the first (title line) of the commit message. It shows up like this now:

* 76660fcb0992034bb15b00d5bfb8b498cc9673ee Per [#11862](/bitcoin-bitcoin/11862/). Most bitcoin.conf options apply to all three networks, however some apply only to mainnet unless specified in a section. As stands, conf file has no indication that sections are now in use or are in some circumstances mandatory (eg, changing rpcport for testnet.) (Alistair Mann) (pull/15387/head)

The format of a commit message is supposed to be

<short title>
<empty line>
<description ...> (may be multiple lines)

in share/examples/bitcoin.conf:7 in 76660fcb09
```
   3 | @@ -4,6 +4,10 @@
   4 |   
   5 |  # Network-related settings:
   6 |  
   7 | +# Note that if you use testnet or regtest, particularly with the options
```
promag commented at 3:29 PM on February 12, 2019:

I think this is the best place to show sections (instead of pointing to the end of file) - after all, sections are for "Network related settings". This way you also avoid talking about "addnode, connect, port, bind, rpcport, rpcbind or wallet ..." twice.

Csi18nAlistairMann commented at 10:19 PM on February 12, 2019:

I'm onboard that the repetition is poor in English, but I think the alternatives are worse:

If the section explanation at the bottom is moved up, we move commentary away from its subject in the file.

If we fix that by moving the sections themselves with the commentary, it changes the meaning of the miscellaneous options such that uncommenting #keypool=100, which currently would affect all three networks, will afterwards only affect regtest.

If we fix that by copy/pasting the options from regtest to each section then we're much increasing the size of a file creating a maintenance burden.

If we instead move #keypool=100 onwards above the network-related settings then we've a configuration file that unhappily starts with 'Miscellaneous options'.

What might work is to move the section explanation up and follow it with a [general] section, but I don't believe that's supported, and I'm reluctant to fake it with a '# [general]' pseudo-section that attempts to ties the hands of future developers.

What might also work is to have multiple configuration examples rather than or as well as this one attempting to be all things to all people. That would be a direction for the future rather than for this PR.

bitcoin.conf is in a mess and my repetition doesn't help but it does feel like the least intrusive way to get reference to sections into the example.

Edit: it occurs to me that section terminators might also work: [/main] etc, however I don't believe they're supported either.

promag commented at 10:14 AM on February 13, 2019:

it occurs to me that section terminators might also work: [/main] etc, however I don't believe they're supported either.

Right, it's not implemented.
promag commented at 3:29 PM on February 12, 2019: member

Concept ACK.
luke-jr commented at 6:41 PM on February 12, 2019: member

ACK
fanquake commented at 9:36 AM on March 2, 2019: member

I've fixed up the commit message in #15513.
fanquake closed this on Mar 2, 2019
laanwj referenced this in commit 3800ca6068 on Mar 5, 2019
Munkybooty referenced this in commit 6763f03ef9 on Sep 16, 2021
Munkybooty referenced this in commit 54181d1816 on Sep 27, 2021
Munkybooty referenced this in commit 22c85b72fe on Sep 27, 2021
Munkybooty referenced this in commit ae7bb8cb1f on Sep 30, 2021
Munkybooty referenced this in commit b5c4423b58 on Oct 1, 2021
kittywhiskers referenced this in commit 9f703e1f79 on Oct 12, 2021
pravblockc referenced this in commit 06f05ca58d on Nov 18, 2021
MarcoFalke locked this on Dec 16, 2021

Contributors

Labels

Linked (view graph)

#11862 Network specific conf sections #15513 docs: add "sections" info to example bitcoin.conf