doc: consolidate and simplify Gorums documentation
Maintainers usually reply within 1 day
Nobody has claimed this yet.
Assessment
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Newbie friendliness
- 22/100
- Issue type
- Documentation
- Clarity
- Mostly clear
- Activity status
- Active
- Tech stack
- go, markdown
- Domain
- api, documentation
Research direction
Start with doc/user-guide.md, doc/dev-guide.md, and the alias comment in cmd/protoc-gen-gorums/dev/aliases.go, which feeds generated gorums.pb.go files. Pick one checklist item and split it into a focused subissue; the issue asks for that before any large change. Done means the chosen docs or comments match the current APIs and generator, generator sources are fixed, and outputs are regenerated.
Written by the indexing model from the issue text.
Description
Problem
Documentation across the Gorums module repeats concepts in code comments, generated code, doc/user-guide.md, and doc/dev-guide.md.
Some descriptions may disagree, and others are unclear or too long.
The alias comment emitted in generated gorums.pb.go files from cmd/protoc-gen-gorums/dev/aliases.go is one example.
Scope
Use this checklist to organize the review.
Create focused subissues for independent parts when the work is larger than one reviewable change.
- Compare
doc/user-guide.mdwith current exported APIs and generated service clients. - Compare
doc/dev-guide.mdwith the current generator, runtime, and internal APIs. - Review exported library API comments for accurate, concise contracts and consistent names.
- Review internal API comments; remove generated-code-only warnings from
internalpackages where they add no value. - Review comments in generated code and their source templates, including the alias comment from
dev/aliases.go. - Remove duplication and resolve inconsistencies across code and guides while preserving the purpose of each document.
- Standardize generated-code usage wording where public declarations need it.
- Identify specific examples or further focused issues where they would help users.
Fix generator sources and regenerate outputs when generated comments change.
Keep the exported-versus-internal split visible in any subissues.
The focused empty-configuration contract correction is tracked by #425.
The migration guide is already tracked by #397 and is outside this issue.
- Dominant language
- Go
- Stars
- 149
- Forks
- 15
- Avg merge
- 1d 8h
- Merged PRs (30d)
- 43
Getting set up
This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from relab/gorums
-
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
Maintainers usually reply within 1 day
-
Difficulty 4/5 3-5 days Newbie friendliness 35/100
Maintainers usually reply within 1 day
-
Difficulty 5/5 Over a week Newbie friendliness 15/100
Maintainers usually reply within 1 day
-
doc
Difficulty 3/5 Half a day Newbie friendliness 45/100
Maintainers usually reply within 1 day
-
Difficulty 4/5 3-5 days Newbie friendliness 35/100
Maintainers usually reply within 1 day
Similar issues
-
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
apache/arrow-swift#209 ·
Maintainers usually reply within 1 day
-
orchestrator: NFS-cache "cache path is not set" WARN logged on every build/launch instead of oncePossibly taken A pull request linked to this issue is open or already merged. Open
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
Maintainers usually reply within 2 days
-
Difficulty 1/5 1-3 hours Newbie friendliness 65/100
influxdata/telegraf#20031 ·
Maintainers usually reply within 1 day
-
pkg/registry/file no longer builds for GOOS=windows: unguarded syscall.Stat_t in qualified_resource_migration.goPossibly taken @AnshulPatil2005 claimed this today. Open
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 74/100
OneBusAway/maglev#1914 ·
Maintainers usually reply within 2 days