doc: Update and improve files.md #20076

hebasto commented at 1:09 PM on October 4, 2020: member

This PR adds to the files.md:

the signet subdirectory
the ip_asn.map file
some small improvements

DrahtBot added the label Docs on Oct 4, 2020

DrahtBot commented at 4:01 PM on October 4, 2020: member

The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.

Conflicts

Reviewers, this pull request conflicts with the following ones:

#17428 (p2p: Try to preserve outbound block-relay-only connections during restart by hebasto)

If you consider this pull request important, please also help to review the conflicting pull requests. Ideally, start with the one that should be merged first.

practicalswift commented at 4:24 PM on October 4, 2020: contributor

ACK 00a3b45696fea7ad3a6c00b769ec6c2fc53c1b5c

Thanks for improving documentation!

in doc/files.md:29 in 00a3b45696 outdated

  25 | @@ -26,40 +26,42 @@ Linux    | `$HOME/.bitcoin/`
  26 |  macOS    | `$HOME/Library/Application Support/Bitcoin/`
  27 |  Windows  | `%APPDATA%\Bitcoin\` <sup>[\[1\]](#note1)</sup>
  28 |  
  29 | -2. The non-default data directory path can be specified by `-datadir` option.
  30 | +2. The data directory path can be specified with `-datadir` option.

jonatack commented at 5:03 PM on October 4, 2020:

s/with/with the/

s/option/configuration option/

hebasto commented at 6:19 PM on October 4, 2020:

Updated.

in doc/files.md:36 in 00a3b45696 outdated

  37 | -`-testnet`          | *path_to_datadir*`/testnet3/`
  38 | -`-regtest`          | *path_to_datadir*`/regtest/`
  39 | +Chain option                   | Data directory path
  40 | +-------------------------------|------------------------------
  41 | +`-chain=main` (by default)     | *path_to_datadir*`/`
  42 | +`-chain=signet` or `-signet`   | *path_to_datadir*`/signet/`

jonatack commented at 5:08 PM on October 4, 2020:

generally, the chain order in the codebase is main/test/signet/regtest

hebasto commented at 6:20 PM on October 4, 2020:

Thanks! Updated.

in doc/files.md:44 in 00a3b45696 outdated

  46 |  ## Data directory layout
  47 |  
  48 |  Subdirectory       | File(s)               | Description
  49 |  -------------------|-----------------------|------------
  50 | -`blocks/`          |                       | Blocks directory; can be specified by `-blocksdir` option (except for `blocks/index/`)
  51 | +`blocks/`          |                       | Blocks directory. Path can be specified with `-blocksdir` option (except for `blocks/index/`)

jonatack commented at 5:10 PM on October 4, 2020:

s/. Path/; path/ (to avoid full sentence structure and need for EOL full stop)

s/with/by/ or /with/with the/

hebasto commented at 6:20 PM on October 4, 2020:

Updated.

in doc/files.md:48 in 00a3b45696 outdated

  51 | +`blocks/`          |                       | Blocks directory. Path can be specified with `-blocksdir` option (except for `blocks/index/`)
  52 |  `blocks/index/`    | LevelDB database      | Block index; `-blocksdir` option does not affect this path
  53 |  `blocks/`          | `blkNNNNN.dat`<sup>[\[2\]](#note2)</sup> | Actual Bitcoin blocks (in network format, dumped in raw on disk, 128 MiB per file)
  54 |  `blocks/`          | `revNNNNN.dat`<sup>[\[2\]](#note2)</sup> | Block undo data (custom format)
  55 | -`chainstate/`      | LevelDB database      | Blockchain state (a compact representation of all currently unspent transaction outputs and some metadata about the transactions they are from)
  56 | +`chainstate/`      | LevelDB database      | Blockchain state (a compact representation of all currently unspent transaction outputs (UTXO) and some metadata about the transactions they are from)

jonatack commented at 5:12 PM on October 4, 2020:

s/UTXO/UTXOs/ and omit parasitic "some"

hebasto commented at 6:20 PM on October 4, 2020:

Thanks! Updated.

in doc/files.md:35 in 00a3b45696 outdated

  36 | -no option (mainnet) | *path_to_datadir*`/`
  37 | -`-testnet`          | *path_to_datadir*`/testnet3/`
  38 | -`-regtest`          | *path_to_datadir*`/regtest/`
  39 | +Chain option                   | Data directory path
  40 | +-------------------------------|------------------------------
  41 | +`-chain=main` (by default)     | *path_to_datadir*`/`

jonatack commented at 5:13 PM on October 4, 2020:

can omit "by "

hebasto commented at 6:20 PM on October 4, 2020:

Thanks! Updated.

jonatack commented at 5:19 PM on October 4, 2020: member

Concept ACK. Not a fan of many of the grammar changes that are both a bit noisy and which partially convert to full sentence structure and grammar without adding the articles ("the") and full stops the conversion implies. A few examples below, but I stopped after realising that many of the changes involve the same issues. Would prefer just the essential content changes without the grammar ones.

hebasto force-pushed on Oct 4, 2020

hebasto commented at 6:19 PM on October 4, 2020: member

Updated 00a3b45696fea7ad3a6c00b769ec6c2fc53c1b5c -> 756c9dcfa9e9b609ad7dd07c1e802c9f0a65c743 (pr20076.01 -> pr20076.02, diff):

addressed @jonatack's comments, dropped unneeded grammar changes

in doc/files.md:29 in 756c9dcfa9 outdated

  25 | @@ -26,15 +26,16 @@ Linux    | `$HOME/.bitcoin/`
  26 |  macOS    | `$HOME/Library/Application Support/Bitcoin/`
  27 |  Windows  | `%APPDATA%\Bitcoin\` <sup>[\[1\]](#note1)</sup>
  28 |  
  29 | -2. The non-default data directory path can be specified by `-datadir` option.
  30 | +2. The data directory path can be specified by `-datadir` option.

jonatack commented at 6:25 PM on October 4, 2020:

Since this is a full sentence, I guess it should have s/by/by the/.

Maybe

"A custom data directory path can be specified by the -datadir option."

or

"A non-default data directory path can be specified by the -datadir option."

hebasto commented at 6:36 PM on October 4, 2020:

Thanks! Updated.

jonatack commented at 6:31 PM on October 4, 2020: member

Oh much better, thanks @hebasto

ACK mod one comment

hebasto force-pushed on Oct 4, 2020

hebasto commented at 6:36 PM on October 4, 2020: member

Updated 756c9dcfa9e9b609ad7dd07c1e802c9f0a65c743 -> 8d1ab6c7330d79e4535c8fe0adbbc0df22c1e794 (pr20076.02 -> pr20076.03, diff):

addressed @jonatack's comment

jonatack commented at 6:44 PM on October 4, 2020: member

ACK

practicalswift commented at 7:07 PM on October 4, 2020: contributor

ACK 8d1ab6c7330d79e4535c8fe0adbbc0df22c1e794

promag commented at 5:43 PM on October 5, 2020: member

Concept ACK

hebasto commented at 6:30 PM on October 5, 2020: member

@naumenkogs Mind looking into this doc update as it is about ip_asn.map file?

naumenkogs commented at 6:48 AM on October 6, 2020: member

Everything looks good.

W.r.t asmap, maybe instead of (or in addition to) linking a wikipedia article we should link some asmap-related info? I couldn't find a good webpage to link, so maybe just add "Experimental feature: see asmap-CLI and asmap-utility"

doc: Update and improve files.md

Added the `signet` subdirectory and the `ip_asn.map` file.

2dc79c4264

hebasto force-pushed on Oct 6, 2020

hebasto commented at 8:10 AM on October 6, 2020: member

Updated 8d1ab6c7330d79e4535c8fe0adbbc0df22c1e794 -> 2dc79c4264d608ebe48c980f0ead54274ab3ee4f (pr20076.03 -> pr20076.04, diff). @naumenkogs

W.r.t asmap, maybe instead of (or in addition to) linking a wikipedia article we should link some asmap-related info? I couldn't find a good webpage to link, so maybe just add "Experimental feature: see asmap-CLI and asmap-utility"

Reworked. I don't think adding link to the feature description is the purpose of this file.

naumenkogs commented at 9:18 AM on October 6, 2020: member

ACK

decryp2kanon commented at 9:13 PM on October 7, 2020: contributor

Concept ACK

practicalswift commented at 8:42 AM on October 9, 2020: contributor

ACK 2dc79c4264d608ebe48c980f0ead54274ab3ee4f

MarcoFalke added this to the milestone 0.21.0 on Oct 9, 2020

MarcoFalke commented at 8:52 AM on October 9, 2020: member

ACK 2dc79c4264d608ebe48c980f0ead54274ab3ee4f

fanquake merged this on Oct 9, 2020

fanquake closed this on Oct 9, 2020

hebasto deleted the branch on Oct 9, 2020

sidhujag referenced this in commit 9c523d30c1 on Oct 9, 2020

DrahtBot locked this on Feb 15, 2022