From afd260dac75a49f0fafea54d49d899a2121c64a1 Mon Sep 17 00:00:00 2001 From: Sergio Costa Date: Mon, 21 Sep 2026 18:50:01 -0300 Subject: [PATCH 1/2] chore: add issue templates, PR template and contributing guide --- .github/ISSUE_TEMPLATE/bug_report.md | 22 ++++++++++++++++++++++ .github/ISSUE_TEMPLATE/documentation.md | 21 +++++++++++++++++++++ .github/ISSUE_TEMPLATE/feature_task.md | 19 +++++++++++++++++++ .github/ISSUE_TEMPLATE/onboarding_task.md | 23 +++++++++++++++++++++++ .github/pull_request_template.md | 17 +++++++++++++++++ 5 files changed, 102 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.md create mode 100644 .github/ISSUE_TEMPLATE/documentation.md create mode 100644 .github/ISSUE_TEMPLATE/feature_task.md create mode 100644 .github/ISSUE_TEMPLATE/onboarding_task.md create mode 100644 .github/pull_request_template.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..241160e --- /dev/null +++ b/.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 + + +### Steps to Reproduce +1. Import or load data: `...` +2. Call function with parameters: `...` +3. Run command: `...` + +### Expected Behavior + + +### Actual Behavior / Error Traceback +```python +# Paste full error traceback here \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/documentation.md b/.github/ISSUE_TEMPLATE/documentation.md new file mode 100644 index 0000000..d587526 --- /dev/null +++ b/.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 + + +### Motivation / Problem + + +### 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 + \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/feature_task.md b/.github/ISSUE_TEMPLATE/feature_task.md new file mode 100644 index 0000000..dcfc0eb --- /dev/null +++ b/.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 + + +### Technical Specifications & Context + + +### 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 \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/onboarding_task.md b/.github/ISSUE_TEMPLATE/onboarding_task.md new file mode 100644 index 0000000..4f3585e --- /dev/null +++ b/.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 + + +### 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. diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..58f0c65 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,17 @@ +### Description + + +### Related Issue + +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) \ No newline at end of file From ba15ba120d4170a6281514416ff736c7860cbffb Mon Sep 17 00:00:00 2001 From: Sergio Costa Date: Mon, 21 Sep 2026 19:51:25 -0300 Subject: [PATCH 2/2] docs: add contributing guidelines --- CONTRIBUTING.md | 84 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 84 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..1063e86 --- /dev/null +++ b/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/-short-description` + - `fix/-short-description` + - `docs/-short-description` + - `chore/-short-description` +4. Fetch and checkout the branch locally: + ```bash + git fetch origin + git checkout + ``` + +#### 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 ` + - **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/-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/-my-task +git push -u origin feat/-my-task +``` + +--- + +## License + +By contributing, you agree that your contributions will be licensed under the project's repository license.