neondatabase
Propose documentation structure
Problem
README.md is quite untidy / unstructured. Especially building / running neon locally on Debian based Linux takes quite long due to unsightly arrangement.
Details
From arpad-m (Müller, Arpad) Currently we require protoc 3.15+. The requirement on the higher version was introduced by https://github.com/neondatabase/neon/pull/3883 It's already mentioned in README.
Dear Mr. Müller @arpad-m: You did not read the problem description in detail.
Ubuntu 22.04.4 (LTE)
I propose that Ubuntu 22.04.4 is in heavy use in the wild. The protobuf Debian package shipped with Ubuntu 22.04.4 mentioned in the current README.md is the WRONG version.
https://github.com/neondatabase/neon/blob/fef77b0cc981f71238e1117d392ea55ec867e61f/README.md#L30-L35
If you are a Ubuntu 22.0.4.4 user (like i am) if you install the build requirement apt packages the build (default debug) fails after > 30min build time. :bomb::rage::zap:
There is a docker file provided if you want to build Neon yourself, you can find it in Dockerfile.build-tools. Alternatively, you can try to use a docker container building on top of Ubuntu 24.04, it should have a recent enough protoc.
Also the docker file (building) provided: does not work! Now the current protobuf google package includes a bug in CMake. This took me 1 day in summary to get neon compiled. :bomb::rage::zap:
Fix
My documentation proposal FIXES the ORDER and will probably SAVE many people this TIME!
:two_hearts: :star2: :pray:
Summary of changes
Splitted topics into
- https://github.com/clauspruefer/neon/blob/doc-proposal/README.md
- https://github.com/clauspruefer/neon/blob/doc-proposal/docs/build/README.md
- https://github.com/clauspruefer/neon/blob/doc-proposal/docs/build/BUILD.md
- https://github.com/clauspruefer/neon/blob/doc-proposal/docs/build/RUN-LOCAL.md
- https://github.com/clauspruefer/neon/blob/doc-proposal/docs/build/TESTS.md
both of us are on vacation last week unfortunately :(
cc @danieltprice @clarkbw what's your take here? does it look like a good direction to smplify the readme file and put development-related instructions separately?
both of us are on vacation last week unfortunately :(
cc @danieltprice @clarkbw what's your take here? does it look like a good direction to smplify the readme file and put development-related instructions separately?
Uhh, sorry thought im getting ignored...
Also it could be a good idea to number all doc-sections (maybe automated in CI) so that sections / subsections can be referenced easily.