From d11c7c882877e4d4cb7d152d8275e79943570e8a Mon Sep 17 00:00:00 2001
From: Sherjeel Shabih <shabihsherjeel@gmail.com>
Date: Thu, 7 Dec 2023 12:08:30 +0100
Subject: [PATCH] Adds a troubleshooting guide and a Github Issue template for
 bugs

---
 .github/ISSUE_TEMPLATE/bug.md | 33 ++++++++++++++++++++++++++++++
 README.md                     |  5 +++++
 TROUBLESHOOTING.md            | 38 +++++++++++++++++++++++++++++++++++
 3 files changed, 76 insertions(+)
 create mode 100644 .github/ISSUE_TEMPLATE/bug.md
 create mode 100644 TROUBLESHOOTING.md

diff --git a/.github/ISSUE_TEMPLATE/bug.md b/.github/ISSUE_TEMPLATE/bug.md
new file mode 100644
index 000000000..7da2cf8c7
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/bug.md
@@ -0,0 +1,33 @@
+name: Bug Report
+description: File a bug report
+title: "[Bug]: "
+labels: ["bug"]
+projects: ["FAIRmat-NFDI/pynxtools"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to fill out this bug report!
+  - type: input
+    id: contact
+    attributes:
+      label: Contact Details
+      description: How can we get in touch with you if we need more info?
+      placeholder: ex. email@example.com
+    validations:
+      required: false
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: Also tell us, what did you expect to happen?
+      placeholder: Tell us what you see!
+      value: "A bug happened!"
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: Relevant log output
+      description: Please copy and paste any relevant log output. This will be automatically formatted into code, so no need for backticks.
+      render: shell
diff --git a/README.md b/README.md
index 2786e03d0..bf6e035a1 100644
--- a/README.md
+++ b/README.md
@@ -95,3 +95,8 @@ on how to build on this work, or to get your parser included into NOMAD, you can
 ### Does this software require NOMAD or NOMAD OASIS ?
 
 No. The data files produced here can be uploaded to Nomad. Therefore, this acts like the framework to design schemas and instances of data within the NeXus universe.
+
+# Troubleshooting
+
+Please check this [guide](TROUBLESHOOTING.md) for any issues you face with the tool. If you don't find a solution there, please make a new [Github Issue](https://github.com/FAIRmat-NFDI/pynxtools/issues/new?template=bug.md).
+
diff --git a/TROUBLESHOOTING.md b/TROUBLESHOOTING.md
new file mode 100644
index 000000000..67bd9dfe5
--- /dev/null
+++ b/TROUBLESHOOTING.md
@@ -0,0 +1,38 @@
+# Troubleshooting Guide
+
+### If you don't find a solution here, please make a new [Github Issue](https://github.com/FAIRmat-NFDI/pynxtools/issues/new?template=bug.md).
+
+<br/>
+
+## Module import error
+
+```python
+ImportError: cannot import name 'get_nexus_version' from 'pynxtools' (unknown location)
+```
+
+This is, unfortunately, expected behavior.  The Python import mechanism will first look for a folder with the package name in the current working directory. If it finds a folder named `pynxtools`, it will try to import from there. In this case we have the cloned repo folder with the same name, `pynxtools`. Python tries to import from this folder but the code resides in `pynxtools/pynxtools`.
+
+### Solution
+
+If you are working in a directory containing the repo folder, `pynxtools`, rename this repo folder to `pynxtools2` so your current directory looks like this:
+
+```
+.
+├── pynxtools2                    # Renamed repo folder
+│   ├── pynxtools          # Actual module code is in here
+│   ├── tests
+│   └── ...
+└── my_code_imports_pynxtools.py
+```
+
+Then **reinstall the package** and your import will work.
+
+### Steps to reproduce
+
+```
+git clone --recurse-submodules https://github.com/FAIRmat-NFDI/pynxtools.git
+cd pynxtools
+pip install -e .
+cd ..
+```
+