Skip to content

Add troubleshooting guide and editorconfig#1311

Open
splint-disk-8i wants to merge 3 commits intoapple:mainfrom
splint-disk-8i:fix/build-deps
Open

Add troubleshooting guide and editorconfig#1311
splint-disk-8i wants to merge 3 commits intoapple:mainfrom
splint-disk-8i:fix/build-deps

Conversation

@splint-disk-8i
Copy link

Adds a troubleshooting section to BUILDING.md covering the most common build issues I ran into while setting up the project. Also adds an .editorconfig so editors that support it automatically pick up the project's indentation style.

Changes:

  • BUILDING.md: new troubleshooting section with fixes for Xcode setup, Swift version mismatches, permission errors, network issues during integration tests, kernel install timeouts, and the known vmnet bug
  • .editorconfig: tabs for Makefiles, 4-space indent for Swift/Shell, 2-space for YAML/JSON/TOML


Run `make pre-commit` to install a pre-commit hook that ensures that your changes have correct formatting and license headers when you run `git commit`.

## Troubleshooting
Copy link
Contributor

Choose a reason for hiding this comment

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

This is super helpful and thank you for starting on it! Take a look at #773, as it relates to the changes you made here.

Feel free to work on any other points in that issue, but due to scope, I think this PR is good as is and should serve as the initial setup of the section itself, with a couple of solutions (like you have). This also might live better in its own file and can instead be linked to in this file.

Copy link
Author

Choose a reason for hiding this comment

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

Thanks! Just looked at #773 — makes sense to keep a dedicated troubleshooting doc. Want me to split it into a separate file and link it from BUILDING.md in this PR, or should I do that in a follow-up?

Copy link
Contributor

Choose a reason for hiding this comment

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

I think the changes should be done in this PR. The idea is to follow the first step from the issue, but start on a much smaller scale, since this will serve as the baseline to follow in the future. Also, there will be a lot more issues to add and we don't the Building.md file to become too large.

What do you think about the steps below for a first iteration?

  1. Create the new troubleshooting doc and add a link to it in Building.md.
  2. For any issues you've already identified, cross-check them with related open or closed issues and link those in the new doc.

Copy link
Author

Choose a reason for hiding this comment

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

Good idea — I moved the troubleshooting content into its own TROUBLESHOOTING.md and added a link from BUILDING.md. Also cross-referenced a few related issues, where I could find them. Let me know if this is what you had in mind.

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.

2 participants