docs(dev): add Troubleshooting to DEVELOPMENT.md #9812
Conversation
- Add comprehensive troubleshooting section between Debugging and Building - Include solutions for case-sensitive volume issues with Turbo - Add Turbo daemon fixes and cache clearing procedures - Cover platform-specific issues and Node.js/pnpm problems - Provide links to toolchain-specific GitHub issues - Update Table of Contents with new section Addresses gitbutlerapp#5025
- Add comprehensive troubleshooting section between Debugging and Building - Include solutions for case-sensitive volume issues with Turbo - Add Turbo daemon fixes and cache clearing procedures - Cover platform-specific issues and Node.js/pnpm problems - Provide links to toolchain-specific GitHub issues - Update Table of Contents with new section Addresses gitbutlerapp#5025
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎
|
|
@ali90h is attempting to deploy a commit to the GitButler Team on Vercel. A member of the Team first needs to authorize it. |
DEVELOPMENT.md
Outdated
| $ pnpm dev:desktop | ||
| ``` | ||
|
|
||
| ### Cache Issues |
There was a problem hiding this comment.
Could you lower-case issues in all the headings?
There was a problem hiding this comment.
Done — normalized “issues” to lower-case across all headings.
DEVELOPMENT.md
Outdated
| #### Linux | ||
|
|
||
| - Double-check all system dependencies are installed (see Prerequisites) | ||
| - On some distributions, you may need additional development packages |
There was a problem hiding this comment.
I find this too vague to the point where it can be removed.
There was a problem hiding this comment.
Removed the generic Linux
DEVELOPMENT.md
Outdated
| #### Cargo build failures | ||
|
|
||
| ```bash | ||
| # Update Rust toolchain | ||
| $ rustup update | ||
|
|
||
| # Clean and rebuild | ||
| $ cargo clean | ||
| $ cargo build | ||
| ``` |
There was a problem hiding this comment.
rust-toolchain.toml assures the correct Rust compiler is used. So I think this is too general and is either removed or replaced by something more specific.
There was a problem hiding this comment.
Removed the generic Rust section.
DEVELOPMENT.md
Outdated
| #### Missing system dependencies | ||
|
|
||
| On Linux, if you're getting linking errors, ensure all required system libraries are installed. Revisit the Prerequisites section for your distribution. |
There was a problem hiding this comment.
Again, I think this is too general and should be removed.
Co-authored-by: Sebastian Thiel <[email protected]>
|
Thanks for the review! I’ve addressed all comments:
Ready for another pass. 🙏 |
|
Hi @ali90h, thank you so much for taking from your time to improve the documentation, it is really appreciated! 🙇♂️ |
Add comprehensive troubleshooting section to DEVELOPMENT.md
Description
Addresses issue #5025 by adding a dedicated Troubleshooting section to the developer documentation. This section provides solutions for common development environment issues that can cause significant developer friction.
Changes Made
Problem Solved
Developers encountering common setup issues (like the case-sensitive filesystem problem with Turbo) previously had to hunt through various toolchain documentation and GitHub issues. This change provides centralized, easily discoverable solutions that should reduce developer onboarding friction and debugging time.
Testing
Related Issues
Closes #5025
Checklist