Split document into sizable chunks - #220
Merged
Merged
Conversation
The README had grown to ~1070 lines covering Docker, dependency installs, building, running, protocol compatibility, configuration and security, so readers had to scroll past everything to find one topic. - Move each topic into its own file under `docs/`: `DOCKER.md`, `DEPENDENCIES.md`, `RUNNING.md`, `CONFIGURATION.md`, `MULTIPLEXING.md`, `COMPATIBILITY.md` and `SECURITY.md`. - Fold the build-related README sections into the existing `docs/BUILD.md` rather than adding a second build guide. - Reduce the README to an overview, a quick start and a table of the new files, and rewrite the cross-file `#anchor` links that the move broke.
The build guide had grown long-form prose explaining every field of `fc_deps.json` and the rationale behind each dependency-resolution mode, which buried the handful of commands a reader actually needs. - Replace the prose requirements section with a version table covering the compiler, CMake, and each dependency, marking which must come from the platform. - Drop the `fc_deps.json` field-by-field reference and the `auto` probe rationale; keep only the two non-obvious editing constraints (Boost's `-cmake` asset, `BOOST_UUID_LINK_LIBATOMIC`). - Condense offline, cross-compilation and tooling sections to their commands, and inline the `system`/`fetch`/`auto` table into one sentence. Docs: docs/BUILD.md 310 -> 153 lines; no content newly undocumented
Trimming the build guide dropped the subheadings above the two flag tables, leaving adjacent tables with no stated distinction. - Restore the headings, naming the axis each table varies: project options control what gets built, dependency resolution controls where Boost, Protobuf and Catch2 come from.
Static OpenSSL pins the proxy to the copy it was built against, so platform security updates only apply after a rebuild. - Pass the flag in the README quick start and in every `cmake` invocation in `docs/BUILD.md`; lead with the dynamic form in `docs/DEPENDENCIES.md`. - Mark it recommended in the flag table, still noting the default is ON.
Every binary published from `uat-and-release.yml` is built with `-DLINK_STATIC_OPENSSL=OFF`, so it needs OpenSSL, zlib and libstdc++ present on the host — neither the run guide nor the README said so. - Add a `Runtime dependencies` section to `docs/RUNNING.md`: install commands plus a minimum-version table, noting which minimums come from the released binaries' Ubuntu 22.04 build host. - Repeat the commands in the README quick start and link the section.
The template invited a bullet per detail plus `Tests:`/`Docs:` trailers, which produced long messages restating what the subject and diff already showed. - Drop the trailers and cap the usual body at two or three bullets. - Say to describe the final state and squash follow-up fixes while the branch is unpushed, rather than narrating the path taken.
rawalexe
force-pushed
the
dev/doc_update
branch
from
August 6, 2026 02:33
161a894 to
3a4bc41
Compare
gmtt
approved these changes
Aug 6, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Motivation
README.mdhad grown to ~1070 lines covering Docker, dependency installs,building, running, protocol compatibility, configuration and security in one
file, so finding any single topic meant scrolling past all the others. This
splits it into topic-based files under
docs/and trims the build guide, whichhad accumulated prose that buried the commands.
Modifications
Change summary
Documentation only — no source, CMake or CI changes.
contents). New files under
docs/:DOCKER.md,DEPENDENCIES.md,RUNNING.md,CONFIGURATION.md,MULTIPLEXING.md,COMPATIBILITY.md,SECURITY.md, plusdocs/README.mdas the index. Cross-file#anchorlinkswere rewritten to match.
docs/BUILD.md(310 → ~170 lines) to the process, a version tableand the commands; absorbed the README's build sections rather than creating a
second build guide, and labelled its two flag tables (project options vs.
dependency resolution).
-DLINK_STATIC_OPENSSL=OFFin every example, so platformOpenSSL updates apply without a rebuild. The CMake default is unchanged.
docs/RUNNING.md— install commandsplus a minimum-version table, noting these apply to the binaries published by
uat-and-release.yml, which are built dynamically.AGENTS.mdcommit-message guidance to drop theTests:/Docs:trailers and cap body length.
docker-build.sh/docker-run.shnotices atdocs/DOCKER.md.Revision diff summary
If there is more than one revision, please explain what has been changed since
the last revision.
Testing
Is your change tested? If not, please justify the reason.
Please list your testing steps and test results.
By submitting this pull request, I confirm that you can use, modify, copy, and
redistribute this contribution, under the terms of your choice.