docs: improve developer onboarding with Flox-first approach #13829
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
webjunkie
force-pushed
the
docs/git-filter-blob-none
branch
from
16e032c to
cd2e6c7
Compare
Recommend using blobless clone for initial repository setup: - Reduces clone size from 3.66 GiB to ~217 MiB (94% reduction) - Makes initial clone 15-17x faster - Still provides full git history for log/diff commands - Only downloads current file contents, not historical versions Developers still get complete git functionality while saving bandwidth and time on the initial clone.
webjunkie
force-pushed
the
docs/git-filter-blob-none
branch
from
cd2e6c7 to
f6b3a8b
Compare
webjunkie
changed the title
pauldambra
left a comment
pauldambra
left a comment
There was a problem hiding this comment.
i'd even be tempted to warn a manual setup will break sometimes as we lean into flox but otherwise 🚢
Restructure to emphasize recommended setup approach: - Move 'Developing locally' to Option 1 (primary path) - Promote Flox as default setup method with concise instructions - Collapse detailed manual setup steps in <details> section - Move Codespaces to Option 2 - Update clone size figures: ~3 GB, few hundred MB (from 3.66 GiB, 217 MiB) All existing setup details and troubleshooting tips preserved in collapsible section. Developers see the modern, recommended path first while manual setup remains available.
webjunkie
force-pushed
the
docs/git-filter-blob-none
branch
from
26bd45e to
ccd3a14
Compare
| You can now change PostHog in any way you want. See [Project structure](/handbook/engineering/project-structure) for an intro to the repository's contents. To commit changes, create a new branch based on `master` for your intended change, and develop away. | ||
| ### Manual setup | ||
| ### Manual setup (advanced) |
There was a problem hiding this comment.
I'm in favor of not having this here at all :). If you wanna do it manually, then you should own it rather than be able to point to the handbook and say "but the handbook told me I could use it!"
There was a problem hiding this comment.
I'm actually also in favor of that... one less path to worry about. I was hesitant though because of these tips and tricks for any troubles.
There was a problem hiding this comment.
Okay replaced it with a Common gotchas section because I found some things valuable and not sure who runs into them (even with Flox).
There was a problem hiding this comment.
@pauldambra FYI because you approved it and now I've changed more 🙈
There was a problem hiding this comment.
yep, i think a tell posthog anything or all hands "hey, use flox it'll help us scale" is on the cards since some folk still aren't and it is gonna make automation harder over time (or rather - one setup makes automation easier)
- Reorganize guide: Flox setup as Option 1, Codespaces as Option 2 - Promote Flox as recommended/default development method - Collapse detailed manual setup in <details> section - Fix git clone filter=blob:none explanation and size figures - Simplify Flox description (remove incorrect npm analogy) - Remove unnecessary rustup/ruff from Flox install - Fix HTML details tag formatting for proper rendering
- Remove entire manual setup section (dependencies, environment setup) - Replace with concise 'Common gotchas' section (14 items, common to obscure) - All gotchas apply regardless of Flox or manual setup method - Includes: resource limits, port conflicts, build errors, migrations, ARM issues - Sorted from most common (Docker/memory) to most obscure (pyproject.toml warnings)
- Explain that external services run in Docker - PostHog apps (Django, frontend, plugin-server, Celery) run on host via hogli start - Clarify mprocs is a terminal UI for managing process logs - Emphasizes fast iteration while keeping infrastructure isolated
Summary
Reorganize developer onboarding guide to emphasize modern, recommended setup:
<details>section (all content preserved)git clone --filter=blob:noneChanges
Flox (Recommended):
Manual setup (Optional):
Codespaces:
Benefit
Developers see the modern, recommended path first while manual setup remains accessible. Reduces doc bloat without losing critical information.