Add troubleshooting section

Author: ubruhin

antora.yml

@@ -15,4 +15,5 @@ nav:
   - modules/user-manual/nav.adoc
   - modules/cli/nav.adoc
   - modules/library-conventions/nav.adoc
+  - modules/troubleshooting/nav.adoc
   - modules/development/nav.adoc

modules/ROOT/pages/index.adoc

@@ -29,6 +29,7 @@ bottom left of the page.
 * xref:user-manual:index.adoc[User Manual]
 * xref:cli:index.adoc[CLI Reference]
 * xref:library-conventions:index.adoc[Library Conventions]
+* xref:troubleshooting:index.adoc[Troubleshooting]
 * xref:development:index.adoc[Development]
 
 Didn't find what you're looking for?

modules/troubleshooting/nav.adoc

@@ -0,0 +1,3 @@
+* xref:index.adoc[]
+** xref:logging.adoc[]
+** xref:reporting.adoc[]

modules/troubleshooting/pages/index.adoc

@@ -0,0 +1,49 @@
+= Troubleshooting
+
+In case you encounter any problems with LibrePCB, this chapter gives you some
+tips to get them solved or to get help from the community.
+
+== Workspace Sync (Dropbox, Cloud, Git, ...)
+
+If you sync your LibrePCB workspace with a cloud or similar, it's important to
+follow some rules to avoid problems:
+
+* Exclude all files with pattern `cache_*` from the synchronization. These
+  files are stored in the workspace subdirectory `data/libraries/`. If
+  LibrePCB does not work correctly and you had these files synced, delete
+  those files manually (while LibrePCB is closed) and try again. These files
+  are automatically recreated after deletion.
+* Consider excluding files named `.lock` from the synchronization too if you
+  experience problems with file locks. However, never open a project or
+  library at the same time from multiple computers!
+* Hidden files ("dotfiles") must be synchronized. If hidden files are
+  ignored by the sync, LibrePCB will not work correctly.
+
+Note that even when following these rules, it's still not guaranteed that
+everything works correctly. Especially with clouds the problem is that they
+are not operating "atomically", which can cause very serious troubles.
+Therefore we do not recommend to store any LibrePCB files in a cloud.
+
+Working with a version control system like Git however is fine, since it works
+atomically and even allows to roll back a change in the very unlikely case
+something is messed up. We just recommend to use version control per-project
+and per-library, not for the whole workspace.
+
+== Wayland
+
+There are some known issues when using LibrePCB natively on Wayland. If you
+experience any problems, please try XWayland or X11 (both should work fine).
+
+== Slow/Laggy UI
+
+On some systems, especially with large projects, the UI could get a bit
+laggy. We are aware of this and try to improve it. In the mean time, try the
+following things:
+
+* Reduce grid density or disable grid completely
+* Avoid huge schematics -- split them into multiple sheets (e.g. DIN A4 format)
+* In the schematic editor, hide pin numbers (toggle menu:View[Show Pin Numbers])
+* In the board editor, reduce the number of visible layers
+* Enable or disable OpenGL in workspace settings (test both modes)
+* If using a high-resolution display, try to reduce resolution
+* On a laptop, plug in the charger :-)

modules/troubleshooting/pages/logging.adoc

@@ -0,0 +1,64 @@
+= Logging Output
+
+For various kinds of problems, it helps to see what LibrePCB internally does
+and what low-level errors occurred but aren't displayed (in every detail)
+in the graphical user interface.
+
+Those messages are always written to `stderr` -- To see them, just run LibrePCB
+from a terminal. Note that on Windows you have to redirect `stderr` to a file
+and open the file in Notepad afterwards.
+
+.Windows cmd.exe (PowerShell doesn't work!)
+
+[source,bash]
+----
+"C:\Program Files\LibrePCB\bin\librepcb.exe" > log.txt 2>&1
+----
+
+After closing LibrePCB, open `C:\Users\%USERNAME%\log.txt` in Notepad.
+
+.MacOS Terminal
+
+[source,bash]
+----
+/Applications/LibrePCB.app/Contents/MacOS/librepcb
+----
+
+.Linux/UNIX Shell
+
+[source,bash]
+----
+/path/to/librepcb
+----
+
+Currently this is the only way to get logging messages. Logging to a file
+is not implemented yet, and the verbosity cannot be configured.
+
+.Example Output
+[source,bash]
+----
+./librepcb-1.1.0-linux-x86_64-qt6.AppImage
+[  INFO   ] LibrePCB 1.1.0 (18a3d4589)
+[  INFO   ] Qt version: 6.6.2 (compiled against 6.6.2)
+[  INFO   ] Resources directory: "/tmp/.mount_librepHOglKc/opt/share/librepcb"
+[  INFO   ] Application settings: "/home/user/.config/LibrePCB/LibrePCB.ini"
+[  INFO   ] Cache directory: "/home/user/.cache/LibrePCB/LibrePCB"
+[DEBUG-MSG] Network access manager thread started.
+[DEBUG-MSG] Recently used workspace: "/home/user/LibrePCB-Workspace"
+[DEBUG-MSG] Detected light theme based on window background color #efefef.
+[DEBUG-MSG] Open workspace data directory "/home/user/LibrePCB-Workspace/data"...
+[DEBUG-MSG] Load workspace settings...
+[DEBUG-MSG] Successfully loaded workspace settings.
+[DEBUG-MSG] Load workspace library database...
+[DEBUG-MSG] Successfully loaded workspace library database.
+[DEBUG-MSG] Successfully opened workspace.
+[DEBUG-MSG] Workspace library scanner thread started.
+[  INFO   ] Loaded parts information cache from "/home/user/.cache/LibrePCB/LibrePCB/parts.lp".
+[DEBUG-MSG] Cleaned outdated live information about 0 parts.
+[DEBUG-MSG] Start workspace library scan in worker thread...
+[DEBUG-MSG] Workspace libraries indexed: 47 libraries in 25 ms.
+[DEBUG-MSG] Workspace library scan succeeded: 5515 elements in 12876 ms.
+[DEBUG-MSG] Network access manager thread stopped.
+[DEBUG-MSG] Workspace library scanner thread stopped.
+[DEBUG-MSG] Exit application with code 0.
+----

modules/troubleshooting/pages/reporting.adoc

@@ -0,0 +1,43 @@
+= Reporting Problems
+
+If you like to report a problem or you want to ask for help, choose one of
+the ways listed https://librepcb.org/help/[here].
+
+Generally the discussion forum is always a good place to ask. A GitHub issue
+is preferred for bug reports, but only if it's clearly a bug -- otherwise
+ask in the forum first.
+
+[IMPORTANT]
+====
+For any problem report, please include as much details as possible! Many
+problems are platform-specific, deployment-specific, usecase-specific etc.
+and we're all not clairvoyants so please let us know these details.
+
+System Information::
+  If you are able to run LibrePCB, open the _About LibrePCB_ dialog and **copy
+  the whole text** from the _Details_ tab into your report. This is very
+  important information.
++
+If you are not able to run LibrePCB, please let us know the following
+information:
++
+* Operating system & version
+* CPU Architecture (x86, x86_64, ARM, Apple Silicon, ...)
+* LibrePCB version (MAJOR.MINOR.PATCH)
+* On Linux: X11 or Wayland?
+
+Installation Method::
+  How did you install LibrePCB? Installer, Portable, Snap, Self-built, ...?
+
+Steps to Reproduce::
+  What did you do before the problem occurred? Describe **exactly**,
+  step-by-step, what you did before the problem occurred.
+
+Problem Description::
+  Describe **exactly** what happened. Which error messages occurred? How did
+  LibrePCB behave?
+
+Logging Messages::
+  For technical problems, it can be helpful to also include all
+  xref:logging.adoc[logging messages].
+====