It is confusing to mix internal dev docs with end user documentation in the same folder.
Fix that by moving the dev docs to a new folder.
Obviously this breaks external links, but since this is internal dev documentation, not many external links should exist.
Concept ACK. Agree on bringing more organization and structure to docs.
nit: Can we use dev or developer as the directory name? devel seems a bit of a strange shortening to me. Happy to take over this PR if this ends up being bikeshedded to death :)
Happy to take over this PR if this ends up being bikeshedded to death :)
Jup, I'd be glad to have this PR taken over. Feel free to do so at any time.
Concept ACK.
almost-ACK. First change below is optional (dunno whether we want to revise release notes) but the second should be included.
diff --git a/doc/release-notes/release-notes-22.0.md b/doc/release-notes/release-notes-22.0.md
index 972c91aa6f..db6176b013 100644
--- a/doc/release-notes/release-notes-22.0.md
+++ b/doc/release-notes/release-notes-22.0.md
@@ -129,7 +129,7 @@ Build System
------------
- Release binaries are now produced using the new `guix`-based build system.
- The [/doc/release-process.md](/doc/release-process.md) document has been updated accordingly.
+ The [/doc/devel/release-process.md](/doc/release-process.md) document has been updated accordingly.
Files
-----
diff --git a/src/chain.h b/src/chain.h
index 15ca8f8750..f3e0764de2 100644
--- a/src/chain.h
+++ b/src/chain.h
@@ -132,7 +132,7 @@ enum BlockStatus: uint32_t {
* If set, this indicates that the block index entry is assumed-valid.
* Certain diagnostics will be skipped in e.g. CheckBlockIndex().
* It almost certainly means that the block's full validation is pending
- * on a background chainstate. See `doc/assumeutxo.md`.
+ * on a background chainstate. See `doc/devel/assumeutxo.md`.
*/
BLOCK_ASSUMED_VALID = 256,
};
Definitely makes sense to put these docs in a subdir.
Thanks for the diff, force pushed.
If this PR is getting review and people are happy with devel I'm certainly not going to NACK this PR. Feel free to direct discussion, nits and bikesheds to this issue though if it helps this PR advance.
Concept ACK on cleaning this up.
Can be reviewed with --color-moved=dimmed-zebra
Rebased. Hint:
git range-diff bitcoin-core/master --word-diff-regex=. fabdae175b 555599a861
doxygen is documentation for internal developers, so I moved that, too.
ACK fa4386d
ACK fa4386d8000bc898468b7664ed44319a635ec599
(think there are a few docs should probably be in the developer directory too but it is another nit and it is debatable)
Just IMO, but I think "doc/design" and "doc/contributing/" folders would be more helpful than a "doc/developer/" folder. "Design" folder would hold files like assumeutxo.md, fuzzing.md, multiprocess.md, translation_process.md that tell you about the design and implementation of cross-cutting features in existing code, and can go into the weeds of how things work technically. "Contributing" folder would hold files like translation_policy.md, developer-notes, release-process, which should be less technical and just tell you how to do whatever task you're trying to do.
Some of our current documents are a little jumbled and might need to be split up to fit this schema perfectly. But I think even just moving current documents to "doc/design" and "doc/contributing/" folders with no changes would be an improvement to at least give each document a clear purpose.
By comparison, I think adding "doc/developer/" folder could be a step backwards and ingrain bad habits of producing documentation without a clear focus. (I will also admit I have kind of a negative reaction to the word "developer". I feel like if I am looking at a github doc directory, than yes I am a developer. Stop asking me who I am and tell me where to find the information I need.)
But if other people like doc/developer/ it SGTM. Just wanted to suggest an alternative.
Added above @ryanofsky comments to #23529. The above isn't a NACK and there is definitely more room for additional doc structure improvements in future PRs. I think this PR is (still) ready for review (and potentially mergeable).
I wonder to what extent the current state causes confusion.
As one data point, this change would break more than a dozen links in the articles on my website, as well as another dozen links in https://github.com/jonatack/bitcoin-development.
These links would require not only updating but perhaps also adding explanatory notes in each file or post about which links are relevant before and after v23.