Chore/setup GitHub templates

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,22 @@
+---
+name: Bug Report
+about: Report reproducible errors, unexpected exceptions, or incorrect simulation outputs
+title: "[BUG] "
+labels: bug
+assignees: ""
+---
+
+### Problem Description
+<!-- Clear and concise explanation of what the bug is. -->
+
+### Steps to Reproduce
+1. Import or load data: `...`
+2. Call function with parameters: `...`
+3. Run command: `...`
+
+### Expected Behavior
+<!-- What you expected to happen. -->
+
+### Actual Behavior / Error Traceback
+```python
+# Paste full error traceback here

.github/ISSUE_TEMPLATE/documentation.md

@@ -0,0 +1,21 @@
+---
+name: Documentation Task / Improvement
+about: Propose new documentation, tutorials, docstring improvements, or corrections
+title: "[DOCS] "
+labels: documentation
+assignees: ""
+---
+
+### Documentation Target
+<!-- What needs to be documented, improved, or corrected? (e.g., API docstring, tutorial notebook, MkDocs guide, README) -->
+
+### Motivation / Problem
+<!-- Why is this documentation needed? Is the current explanation outdated, missing, or unclear? -->
+
+### Proposed Changes
+- [ ] Add/update docstrings in `path/to/module.py`
+- [ ] Write or refine documentation page/tutorial in `docs/`
+- [ ] Update code examples to reflect current API behavior
+
+### References & Context
+<!-- Link to relevant code, papers, or related issues, if applicable. -->

.github/ISSUE_TEMPLATE/feature_task.md

@@ -0,0 +1,19 @@
+---
+name: Feature / Task Request
+about: Propose a new feature, enhancement, or research task
+title: "[FEAT] "
+labels: enhancement
+assignees: ""
+---
+
+### Objective
+<!-- What problem does this solve, or what new capability does it introduce? -->
+
+### Technical Specifications & Context
+<!-- Provide implementation details: affected modules, mathematical formulas, expected inputs/outputs, or references. -->
+
+### Acceptance Criteria (Definition of Done)
+- [ ] Implementation completed in the target module
+- [ ] Unit test(s) covering standard and edge cases added to `tests/`
+- [ ] Documentation or usage example provided (if public API changed)
+- [ ] Pull request passes CI checks and is reviewed

.github/ISSUE_TEMPLATE/onboarding_task.md

@@ -0,0 +1,23 @@
+---
+name: Onboarding / Good First Issue
+about: Well-scoped task suitable for new students joining the team
+title: "[ONBOARDING] "
+labels: good first issue, documentation
+assignees: ""
+---
+
+### Task Description
+<!-- Describe the specific, small-scope task to be completed. -->
+
+### Relevant Files
+- `path/to/file`
+- `tests/`
+
+### Step-by-Step Guidance
+1. Checkout the branch from latest `main`.
+2. Follow the setup in `README.md` and activate the virtual environment.
+3. Make the specified adjustments.
+4. Run tests and linter to verify.
+
+### Expected Deliverable
+- A pull request with clean commits following the repository conventions.

.github/pull_request_template.md

@@ -0,0 +1,17 @@
+### Description
+<!-- Provide a concise summary of the changes made and the motivation behind them. -->
+
+### Related Issue
+<!-- Link the related issue to close it automatically upon merge, e.g., Closes #12 -->
+Closes #
+
+### Changes Made
+- [ ] Core implementation / algorithmic changes
+- [ ] Added or updated unit tests
+- [ ] Updated documentation / docstrings / examples
+
+### Contributor Checklist
+- [ ] The code runs locally without errors
+- [ ] All unit tests pass locally (`pytest`)
+- [ ] Static analysis and formatting pass (`ruff check .`)
+- [ ] Docstrings follow the project standard (inputs, outputs, exceptions)

CONTRIBUTING.md

@@ -0,0 +1,84 @@
+# Contributing Guidelines
+
+Thank you for your interest in contributing! We welcome contributions from research lab members, students, and the open-source community.
+
+---
+
+## Contribution Workflow
+
+We follow a **Trunk-Based Development** model: all active development targets the `main` branch through short-lived branches and Pull Requests.
+
+### 1. Issues First
+Before writing code or opening a pull request, verify that an issue tracks the task:
+- Navigate to the **Issues** tab and click **New issue**.
+- Choose the relevant template (**Feature Task**, **Bug Report**, **Documentation**, or **Onboarding**).
+- Fill in the requested details. Labels will be attached automatically.
+
+---
+
+### 2. Creating Your Branch
+
+#### For Lab Members & Direct Collaborators
+1. Open the assigned issue on GitHub.
+2. In the right sidebar under **Development**, click **"Create a branch"**.
+3. Use conventional branch prefixes:
+   - `feat/<issue-id>-short-description`
+   - `fix/<issue-id>-short-description`
+   - `docs/<issue-id>-short-description`
+   - `chore/<issue-id>-short-description`
+4. Fetch and checkout the branch locally:
+   ```bash
+   git fetch origin
+   git checkout <branch-name>
+   ```
+
+#### For External Contributors (Fork Workflow)
+1. Fork the repository to your GitHub account.
+2. Clone your fork locally and create a topic branch from `main`:
+   ```bash
+   git checkout -b feat/my-improvement
+   ```
+
+---
+
+### 3. Pull Requests (PR)
+
+1. Ensure all local tests and style checks pass prior to submission.
+2. Push your topic branch to GitHub:
+   - **Members:** `git push -u origin <branch-name>`
+   - **External contributors:** `git push -u origin feat/my-improvement` (to your fork)
+3. Open a Pull Request targeting the `main` branch.
+4. Complete the PR template checklist and link the issue in the description (e.g., `Closes #15`).
+5. A maintainer will review the code. All pull requests are merged using **Squash and merge**, and head branches are deleted automatically.
+
+---
+
+## Development & Code Quality
+
+- Follow the project's formatting, linting, and style conventions.
+- Ensure all public functions, classes, and APIs include descriptive documentation/docstrings.
+- Add or update automated tests covering new behavior whenever applicable.
+
+---
+
+## Troubleshooting: Committed Directly to `main`?
+
+If you committed directly to your local `main` branch and the push was blocked by branch protection rules, you can move your commits to a new branch without losing work:
+
+```bash
+# 1. Create a new topic branch preserving your local commits
+git branch feat/<issue-id>-my-task
+
+# 2. Reset your local main back to the clean remote state
+git reset --hard origin/main
+
+# 3. Switch to your topic branch and push normally
+git checkout feat/<issue-id>-my-task
+git push -u origin feat/<issue-id>-my-task
+```
+
+---
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the project's repository license.