FAQ / Troubleshooting

🧩 Common issues and how to fix them when working with this project template.

---

🐍 Import Error: from template_project import plotters

Problem: Python can’t find the template_project module.

✅ Option 1: Install the package locally (recommended)

Activate your environment:

micromamba activate template_env  # or conda activate template_env

Then install your project in “editable” mode:

pip install -e .

This lets Python find your package and reflects changes without needing to reinstall. Restart your kernel to apply changes.

📚 See also: setup.md

🛠 Option 2: Add the path manually (in a notebook)

If you’re working in a Jupyter notebook and haven’t installed the package, insert this before importing:

import sys
sys.path.append("/path/to/your/template-project")

Then you can run:

from template_project import plotters

This is useful for testing during development, but installation is preferred.

---

💥 Pip install error in GitHub Actions

Error message:

× Getting requirements to build editable did not run successfully.
│ exit code: 1
╰─> See above for output.

This usually means something is wrong with the local installation process. Try the following locally in a clean environment:

virtualenv venv
source venv/bin/activate && micromamba deactivate
pip install -r requirements.txt
pip install -e .

If this works locally, your GitHub Actions will likely succeed too.

📁 GitHub workflows live in .github/workflows/*.yml

---

🤔 What’s the difference between template-project and template_project?

• template-project is the name of the repository — it’s fine to use hyphens in GitHub repo names.

• template_project is the name of the Python package (i.e., the importable module) — dashes are not allowed in Python package names.

Term	Use For
template-project	GitHub repository name
template_project	Python package (import syntax)

Could they be the same name?

• ✅ Yes: Both could be template_project

• 🚫 No: Avoid template-project for the Python module

Why this setup?

• Originally accidental, but it reinforces the distinction between repo and code module.

• Helps clarify which name to use in each context, especially when editing docs, imports, or packaging configs.

---

😬 I accidentally committed to main instead of a branch

It happens! If you haven’t pushed yet:

🧼 Option 1: Create a new branch from the current commit

git branch new-feature-branch

Then switch to it:

git checkout new-feature-branch

You’re now safe to push your changes and create a pull request.

🗑 Option 2: Move the commit off main (before push)

git branch temp-fix

git reset --hard origin/main  # resets main to the last pushed commit

git checkout temp-fix

Now your main is clean and you can cherry-pick or merge your changes onto a feature branch properly.

⚠️ Only use reset --hard if you’re sure you haven’t pushed yet and don’t need to keep local-only changes.

---

🚨 Continuous Integration (CI) is failing

🧪 If the failure is in tests:

Run tests locally to reproduce the issue:

pytest

Try running an individual test:

pytest tests/test_tools.py::test_my_function

📚 See: writing_tests.md

📚 If the failure is in documentation:

Try rebuilding the docs locally:

cd docs
make html

Then open _build/html/index.html in a browser.

📚 See: build_docs.md

If your changes involve docstrings or .md files, a local preview will help catch errors before pushing.

💡 The GitHub Actions logs show exactly which step failed — start there!

---

🧭 How do I check which branch I’m on?

In the terminal:

git branch

The active branch is marked with an asterisk.

In VSCode:

• Look at the lower-left corner — your current branch name is shown there.

---

🔄 I cloned the repo but don’t see the latest updates

Make sure you’re on the main branch and that it’s up to date:

git checkout main
git pull origin main

If you forked the repo, check out gitcollab.md for syncing instructions.

---

✍️ I made changes but GitHub doesn’t show them

You need to commit and push your work:

git add .
git commit -m "Describe your changes"
git push origin your-branch-name

💡 Pushing updates your branch on GitHub. Committing saves changes locally.

---

📋 I opened a pull request — what happens now?

• Your changes will be reviewed.

• GitHub Actions (CI) will check that tests and docs pass.

• You might be asked to tweak something.

• Once all is approved, your changes will be merged.

---

🙋 Still stuck?

Check setup.md, or ask a question by opening an issue at github.com/eleanorfrajka/template-project.

✅ This FAQ is a living document — feel free to suggest improvements!