docs: Update contributing guidelines and development workflow (#24)

* chore: add GitHub issue templates and config

* docs: update contributing guidelines, move tests guidance to a new doc, linked

Move Code Style, Testing, and Documentation sections up.
Add links to ensure new contributors can understand code documentation styles
Explain Taskfile and reference commands in Taskfile when possible

* test: bump up coverage threshold to 80, to match original Testing target

"Maintain test coverage above 80%"

Author: bcdady

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,35 @@
+---
+name: "
F41B Bug Report"
+about: "Create a report to help us improve"
+title: "[Bug] "
+labels: bug
+assignees: ""
+---
+
+### Describe the bug
+
+A clear and concise description of what the bug is.
+
+### Reproduction steps
+
+1. Go to '...'
+2. Run '...'
+3. Observe '...'
+
+### Expected behavior
+
+What you expected to happen.
+
+### Screenshots / Logs
+
+If applicable, add screenshots or paste the relevant console/terminal output.
+
+### Environment
+
+- OS (e.g. Ubuntu 22.04):
+- Python/Terraform/`<other>` versions:
+- Commit SHA:
+
+### Additional context
+
+Add any other context about the problem here.

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Report a security vulnerability
+    url: https://github.com/rafaelherik/tfsumpy/security/advisories/new
+    about: Report a security vulnerability in tfsumpy.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,23 @@
+---
+name: "
F31F Feature Request"
+about: "Suggest an idea or enhancement"
+title: "[Feature]"
+labels: enhancement
+assignees: ""
+---
+
+### Problem to solve
+
+What limitation or pain point are you facing?
+
+### Proposal
+
+Describe the feature or behaviour you'd like to see.
+
+### Alternatives considered
+
+Have you considered any alternative solutions? If so, list them here.
+
+### Additional context
+
+Add any other context or references (links, diagrams, etc.) about the feature request here.

.github/workflows/ci.yaml

@@ -36,11 +36,11 @@ jobs:
       - name: Run tests with coverage
         run: |
           poetry run pytest --cov=tfsumpy --cov-report=term
-          poetry run coverage report --fail-under=75
+          poetry run coverage report --fail-under=80
 
       - name: Coverage reminder
         if: success()
-        run: echo "::notice ::Current threshold is 75%. PRs that raise coverage are welcome!"
+        run: echo "::notice ::Current threshold is 80%. PRs that raise coverage are welcome!"
 
       - name: Build package
         run: poetry build

Taskfile.yml

@@ -15,9 +15,9 @@ tasks:
       - .venv
 
   test:
-    desc: Run all tests with pytest
+    desc: Run tests with coverage
     cmds:
-      - . .venv/bin/activate && poetry run pytest --cov=tfsumpy --cov-report=term && poetry run coverage report --fail-under=75
+      - . .venv/bin/activate && poetry run pytest --cov=tfsumpy --cov-report=term && poetry run coverage report --fail-under=80
     deps: [install]
 
   lint:
@@ -37,4 +37,4 @@ tasks:
     desc: Run all checks (install, lint, test)
     cmds:    
       - poetry run ruff check .
-    deps: [install]
+    deps: [install]

docs/contributing.md

@@ -1,18 +1,49 @@
-# Contributing to tfsumpy
+# Contributing Guidelines
+
+## Code Style
+
+- Follow [PEP 8 guidelines](https://peps.python.org/pep-0008/)
+- Use [type hints](https://docs.python.org/3/library/typing.html) for better code clarity and IDE support
+- Write docstrings for all public methods following [PEP 257](https://peps.python.org/pep-0257/) conventions
+- Keep functions focused and small
+
+## Documentation
+
+- Update documentation for new features
+- Include [docstrings](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings) in code (Google style preferred)
+- Update example usage in README.md
+- Add type hints to function signatures
+
+## Making Changes
+
+1. Review [open issues](https://github.com/rafaelherik/tfsumpy/issues) and [pull requests](https://github.com/rafaelherik/tfsumpy/pulls) to see if there is any related work that's already in progress
+2. Get or update your own copy of the project to work with
+3. Write new and/or update existing tests for your changes
+4. Develop and implement your changes
+5. Commit your changes in small, useful chunks
+6. Ensure all tests pass
+7. Update documentation as needed
+8. Push your changes to your fork
+9. Create a Pull Request
 
 ## Getting Started
 
 1. Fork the repository
 2. Clone your fork:
-```bash
-git clone https://github.com/your-username/tfsumpy.git
-```
+
+    ```bash
+    git clone https://github.com/your-username/tfsumpy.git
+    ```
 
 3. Set up development environment:
-```bash
-cd tfsumpy
-pip install -e ".[dev]"
-```
+
+    This project uses [Task](https://taskfile.dev/) to run set up, and run linting, and testing tasks consistently with how they are run in CI. Start by making sure you have [Task](https://taskfile.dev/) installed.
+
+    Running the `task install` command will create a local virtual environment, install dev requirements and then execute the individual tools.  Running these commands in the [Taskfile](Taskfile.yml) guarantees that everyone, including CI workflows, uses the same versions and settings.
+
+    ```bash
+    task install
+    ```
 
 ## Development Process
 
@@ -22,25 +53,55 @@ pip install -e ".[dev]"
 git checkout -b feature/your-feature-name
 ```
 
-### Running Tests
+### Testing
+
+- **Unit Tests**: Required for all new features and bug fixes
+  - Follow our [Testing Guide](tests.md) for best practices
+  - Use [pytest](https://docs.pytest.org/)-style tests with `assert` statements
+  - Maintain test coverage above 80%
+  - Run tests with `task test` (executes `pytest` with coverage)
+
+- **Test-Driven Development (TDD)**:
+  - Write tests first, then implementation
+  - Follow the [TDD workflow](https://realpython.com/test-driven-development-python/)
+  - Keep tests focused and fast
+
+- **Test Types**:
+  - Unit tests for individual functions/classes
+  - Integration tests for component interactions
+  - See [Testing Guide](tests.md) for detailed patterns
+
+### Linting
+
+Linting and static analysis are automated in GitHub Actions. To help you get an approval for your pull request, you'll need to have all Actions workflow checks pass. To run the same tools locally you can use the [Taskfile](Taskfile.yml) to achieve the same results. First make sure you have the [Task](https://taskfile.dev/) runner [installed](https://taskfile.dev/#/installation).
 
 ```bash
-pytest
+cd tfsumpy
+# Run ruff, mypy and bandit (fails on any issues)
+task lint
+
+# Optionally, auto-fix style issues detected by ruff
+task lint-fix
 ```
 
-### Running Linting
+The Taskfile will create a local virtual environment if needed, install all dev requirements and then execute the individual tools.  Running the tasks guarantees that everyone uses the same versions and settings.
+
+### Running Tests
+
+Automated tests run in GitHub Actions. To help you get an approval for your pull request, you'll need to have all Actions workflow checks pass. To run the same tests locally you can use the [Taskfile](Taskfile.yml) to achieve the same results. First make sure you have the [Task](https://taskfile.dev/) runner [installed](https://taskfile.dev/#/installation).
 
 ```bash
-pylint tfsumpy
-mypy tfsumpy
+# Run pytest with coverage threshold enforcement (mirrors CI)
+task test
 ```
 
-### Making Changes
+This task sets up the virtual-env if necessary, installs all dev dependencies, then executes
 
-1. Write tests for your changes
-2. Implement your changes
-3. Ensure all tests pass
-4. Update documentation if needed
+```bash
+pytest --cov=tfsumpy --cov-report=term && coverage report --fail-under=80
+```
+
+so you get quick feedback on both test failures and coverage.
 
 ### Committing Changes
 
@@ -56,23 +117,3 @@ git push origin feature/your-feature-name
 2. Update the documentation if needed
 3. Ensure all tests pass
 4. Create a Pull Request with a clear description of changes
-
-## Code Style
-
-- Follow PEP 8 guidelines
-- Use type hints
-- Write docstrings for all public methods
-- Keep functions focused and small
-
-## Testing
-
-- Write unit tests for new functionality
-- Maintain test coverage above 80%
-- Include integration tests where appropriate
-
-## Documentation
-
-- Update documentation for new features
-- Include docstrings in code
-- Update example usage in README.md
-- Add type hints to function signatures 

docs/tests.md

@@ -0,0 +1,60 @@
+# Adding and Updating Tests
+
+New to pytest? Start here:
+
+- [Official Quick Start (5-min read)](https://docs.pytest.org/en/stable/getting-started.html) – concise intro, test discovery rules, and basic assertions
+- [Real Python “Getting Started With pytest”](https://realpython.com/pytest-python-testing/) – longer, example-driven walkthrough
+
+## Project guidelines
+
+1. Location & naming
+
+- Put tests in the tests/ directory, mirroring the package layout.
+- Filenames should start with test*, and test functions/classes with test*…, so pytest will auto-discover them.
+
+2. Keep them simple
+
+- Prefer plain assert statements—pytest rewrites them to show expressive failure messages.
+- One logical assertion per test is ideal; use multiple tests rather than many asserts in one function.
+
+3. Re-use set-up code with fixtures
+
+- Place shared fixtures in conftest.py at the project root or the relevant sub-directory.
+- Example:
+
+```python
+import pytest
+from tfsumpy import SomeClass
+
+@pytest.fixture
+def sample_instance():
+    return SomeClass(param="value")
+```
+
+4. Parametrize when inputs vary
+
+```python
+@pytest.mark.parametrize("raw,expected", [(1, "1"), (None, "")])
+def test_coerce_to_str(raw, expected):
+    assert utils.coerce_to_str(raw) == expected
+```
+
+5. Measure coverage locally
+
+`task test` runs `pytest --cov=tfsumpy …`. Aim to increase the coverage number or at least keep it above 80 %.
+
+6. Writing new tests
+
+- Start by reproducing the current behaviour (red).
+- Implement or fix code (green).
+- Refactor while tests stay green (TDD cycle).
+
+7. Run only what you need while developing:
+
+```bash
+# Single test file
+pytest tests/test_utils.py
+
+# Filter by keyword
+pytest -k "coerce and str"
+```