Skip to content

docs(homeserver): Improve developer docs and readmes - #431

Merged
86667 merged 15 commits into
mainfrom
repo-rename-readme
Jul 16, 2026
Merged

docs(homeserver): Improve developer docs and readmes#431
86667 merged 15 commits into
mainfrom
repo-rename-readme

Conversation

@SeverinAlexB

@SeverinAlexB SeverinAlexB commented Jun 17, 2026

Copy link
Copy Markdown
Collaborator
  • Overhaul the root README to immediately describe what the repo is and point to other documentations.
  • Replaced GETTING_STARTED.md and DEV_TESTING_GUIDES.md with two guides: INSTALL.md for operators and TESTING.md for devs.
  • Improved other crate readmes

Ive attempted to keep things succinct whilst also ensuring to mention all available options and ways users may trip up. I think i found a good balance but please let me know your thoughts.

Not included:

  • Tutorial for setting up ICANN, reverse proxy for TLS, expose ports
  • Other platforms - kept to Debian-based systems for now. How to manage instructions for mac, non-debian and windows can be decided later once we have some feedback on these docs.#
  • Links to pubky.org

@86667
86667 force-pushed the repo-rename-readme branch 2 times, most recently from d69de87 to 8236048 Compare June 29, 2026 15:34
@86667
86667 force-pushed the repo-rename-readme branch from 8236048 to 6b838c2 Compare June 29, 2026 18:09
@86667 86667 changed the title [DRAFT] Repo rename readme docs(homeserver): Improve developer docs and readmes Jun 30, 2026
@86667
86667 marked this pull request as ready for review June 30, 2026 09:01
@86667
86667 force-pushed the repo-rename-readme branch from 6b838c2 to f2beec2 Compare June 30, 2026 12:35

@SeverinAlexB SeverinAlexB left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I only reviewed the main README so far. Looking at the overall structure, it feels incomplete/thin.

Here are some AI recommendations edited by me on how to extend the readme with:

  • No quick start command path. The README points to guides, but a first-time reader has no immediate “try it in 2 minutes” path. Even 3 lines linking to Docker Compose or local testnet would help.
  • The repo scope is undersold. The README does not say what pubky-core is about. It is an attempt create a new internet, free from wallet gardens (see Johns vision). At the moment, the README does not say anything about it. It feels technically dry.
  • No “who is this for?” split. There are at least three audiences: app developers using the SDK, contributors developing locally, and operators running a homeserver. The README would benefit from making those paths explicit.

Comment thread docs/INSTALL.md Outdated
Comment thread pubky-homeserver/README.md
Comment thread README.md Outdated
Comment thread README.md Outdated
Comment thread README.md Outdated
Comment thread README.md Outdated
Comment thread README.md Outdated
Comment thread README.md Outdated
Comment thread README.md Outdated
Comment thread README.md Outdated

@SeverinAlexB SeverinAlexB left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is the INSTALL.md review

Comment thread docs/INSTALL.md Outdated
Comment thread docs/INSTALL.md Outdated
Comment thread docs/INSTALL.md Outdated
Comment thread docs/INSTALL.md
Comment thread docs/INSTALL.md Outdated
Comment thread docs/INSTALL.md Outdated
Comment thread docs/INSTALL.md Outdated
Comment thread docs/INSTALL.md Outdated
Comment thread docs/INSTALL.md
Comment thread docs/INSTALL.md
@86667

86667 commented Jul 2, 2026

Copy link
Copy Markdown
Collaborator

@SeverinAlexB The thinking was that intro information on the system as a whole should live only in pubky.org and linked to in the repo, which I hadnt done yet. I do however see the value in there being a short intro here aswell for those who have stumbled upon the repo without context, so i've added a paragraph with pointers to pubky.org.

Im not sure about a quick start guide on the root repo. Quick start for what? development, running a HS, building an app? IMO better to link out to docs/guides immediately.

I liked the idea of "who is this for" section so used that as a base for linking to the new guides on this branch.

I also stripped down this core readme - its now just an intro with links to pubky.org and repo docs.

@86667
86667 force-pushed the repo-rename-readme branch 3 times, most recently from 4f0dc41 to 5ea010e Compare July 6, 2026 15:32
Comment thread docs/INSTALL.md Outdated
Comment thread docs/INSTALL.md
Comment thread docs/INSTALL.md Outdated
Comment thread docs/INSTALL.md Outdated
Comment thread docs/INSTALL.md
Comment thread docs/TESTING.md Outdated
Comment thread README.md Outdated
Comment thread README.md Outdated
Comment thread README.md Outdated
Comment thread README.md Outdated
@86667
86667 force-pushed the repo-rename-readme branch from 5ea010e to 04b671e Compare July 7, 2026 15:36
@86667
86667 force-pushed the repo-rename-readme branch from 04b671e to 7e582af Compare July 15, 2026 11:06
Comment thread pubky-testnet/README.md
@@ -9,36 +9,20 @@ Two testnet types are provided:
| [`EphemeralTestnet`] | Random | In-memory | Automated tests (`#[tokio::test]`) - parallel-safe, no port conflicts |
| [`StaticTestnet`] | Fixed, well-known | In-memory or persistent | Interactive / CLI use - browser tests, mobile apps, manual debugging |

@86667 86667 Jul 15, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This file i improved when i merged the recent StaticTestnet persistent data-dir changes. I made it match the guides by adding a ToC and troubleshooting section. Here I remove those in favour of keeping it as a developer-aimed crate explainer.

@SeverinAlexB SeverinAlexB left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The INSTALL.md is getting pretty good! I run everything on a new Ubuntu server and it worked flawlessly. I added some comments but the most feedback I got from an AI review. I tried to only add the AI comments that are necessary but feel free to just close them if you think they are trash.

Comment thread docs/INSTALL.md
Comment thread docs/INSTALL.md Outdated
Comment thread docs/INSTALL.md Outdated
Comment thread docs/INSTALL.md Outdated
Comment thread docs/INSTALL.md Outdated
Comment thread pubky-homeserver/README.md
Comment thread README.md Outdated
Comment thread docs/INSTALL.md Outdated
Comment thread docs/INSTALL.md Outdated
Comment thread README.md Outdated
@86667
86667 force-pushed the repo-rename-readme branch from 7e582af to db42219 Compare July 16, 2026 12:27
@SeverinAlexB

Copy link
Copy Markdown
Collaborator Author

The guides LGTM. Feel free to ask somebody else (outside of core?) for a review if you think it will be of benefit. Otherwise, we can merge

I can't approve my own PR so this is my explicit PR approval

@86667
86667 merged commit 9754ca6 into main Jul 16, 2026
15 checks passed
@86667
86667 deleted the repo-rename-readme branch July 16, 2026 12:43
@MCarlomagno MCarlomagno mentioned this pull request Aug 5, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants