From 3420ab921da718155944c7ec366b690ac3a4f8fc Mon Sep 17 00:00:00 2001 From: BiswasNehaa Date: Sat, 27 Jun 2026 22:52:39 +0530 Subject: [PATCH 1/4] Add WORKFLOW.md, issue templates, and PR template (closes #7) --- .github/ISSUE_TEMPLATE/bug_report.yml | 55 +++++++++++ .github/ISSUE_TEMPLATE/feature_request.yml | 56 +++++++++++ .github/ISSUE_TEMPLATE/task.yml | 39 ++++++++ .github/PULL_REQUEST_TEMPLATE.md | 19 ++++ WORKFLOW.md | 106 +++++++++++++++++++++ 5 files changed, 275 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.yml create mode 100644 .github/ISSUE_TEMPLATE/feature_request.yml create mode 100644 .github/ISSUE_TEMPLATE/task.yml create mode 100644 .github/PULL_REQUEST_TEMPLATE.md create mode 100644 WORKFLOW.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..01af5b0 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,55 @@ +name: Bug report +description: Report something that isn't working as expected +title: "[Bug]: " +labels: + - bug +type: Bug +body: + - type: markdown + attributes: + value: | + Thanks for taking the time to report a bug! Please fill out the details below + so we can reproduce and fix the issue. + + - type: textarea + id: description + attributes: + label: What happened? + description: A clear and concise description of the bug. + validations: + required: true + + - type: textarea + id: expected + attributes: + label: What did you expect to happen? + validations: + required: true + + - type: textarea + id: repro + attributes: + label: Steps to reproduce + description: List the steps needed to reproduce the behavior. + placeholder: | + 1. Run `uv run -m tapio.cli ...` + 2. ... + validations: + required: true + + - type: textarea + id: environment + attributes: + label: Environment + description: OS, Python version, and whether you're using the dev container, Codespaces, or a manual setup. + validations: + required: false + + - type: textarea + id: logs + attributes: + label: Relevant logs or output + description: Paste any relevant error output. This will be rendered as code automatically. + render: shell + validations: + required: false diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..bdeef37 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,56 @@ +name: Feature request +description: Suggest a new capability or enhancement +title: "[Feature]: " +labels: + - enhancement +type: Feature +body: + - type: markdown + attributes: + value: | + Thanks for suggesting an improvement! Please describe the feature and the + problem it solves. + + - type: textarea + id: problem + attributes: + label: What problem does this solve? + description: Describe the use case or limitation that motivates this request. + validations: + required: true + + - type: textarea + id: proposal + attributes: + label: Proposed solution + description: Describe what you'd like to see, as concretely as you can. + validations: + required: true + + - type: textarea + id: alternatives + attributes: + label: Alternatives considered + description: Any other approaches you considered, and why this one is preferred. + validations: + required: false + + - type: dropdown + id: area + attributes: + label: Area + description: Which part of the system does this mostly affect? (You can also add area labels after the issue is created.) + options: + - agents + - auth + - dx + - ops + - partners + - platform + - rag + - safety + - security + - ux + - Not sure + validations: + required: false diff --git a/.github/ISSUE_TEMPLATE/task.yml b/.github/ISSUE_TEMPLATE/task.yml new file mode 100644 index 0000000..df04a4b --- /dev/null +++ b/.github/ISSUE_TEMPLATE/task.yml @@ -0,0 +1,39 @@ +name: Task / research spike +description: Exploratory work, maintenance, or a task that doesn't fit a bug or feature +title: "[Task]: " +labels: + - task +type: Task +body: + - type: markdown + attributes: + value: | + Use this for maintenance work, exploratory research, or anything that isn't + squarely a bug fix or a new user-facing feature. + + - type: textarea + id: goal + attributes: + label: Goal + description: What are we trying to learn, build, or clean up? + validations: + required: true + + - type: textarea + id: checklist + attributes: + label: Checklist + description: Break the work into concrete, checkable steps if you can. + placeholder: | + - [ ] ... + - [ ] ... + validations: + required: false + + - type: textarea + id: context + attributes: + label: Context / references + description: Links to related issues, discussions, or external resources. + validations: + required: false diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..ae5252b --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,19 @@ +## Description + + + +## Checklist + +- [ ] I ran `uv run pytest` and all tests pass +- [ ] I ran `uv run prek run --all-files` (or `uv run ruff check .` and `uv run ruff check . --fix`) and addressed any issues +- [ ] I ran `uv run mypy tapio` and `uv run pyrefly check` and addressed any issues +- [ ] New/changed code meets the project's 80% coverage guideline (`uv run pytest --cov=tapio`) +- [ ] I updated `README.md` if this PR changes user-facing behavior + +## Related issue + + + +## Additional context + + diff --git a/WORKFLOW.md b/WORKFLOW.md new file mode 100644 index 0000000..ec93549 --- /dev/null +++ b/WORKFLOW.md @@ -0,0 +1,106 @@ +# Project Workflow + +This document explains how we organize and triage work in the Tapio project: the GitHub +Project board, our label taxonomy, and how issues move from idea to done. + +## Table of Contents + +- [Project Board](#project-board) + - [Status](#status) + - [Priority](#priority) + - [Iteration](#iteration) + - [Size](#size) +- [Issue Types](#issue-types) +- [Label Taxonomy](#label-taxonomy) + - [Area Labels](#area-labels) + - [Triage Labels](#triage-labels) +- [Triage Process](#triage-process) + +## Project Board + +All issues live on the [Finntegrate Team project board](https://github.com/orgs/Finntegrate/projects/1). +The board has several views (Board, Current iteration, Roadmap, My items) over the same +underlying set of fields: + +### Status + +- **Todo** — not yet started +- **In progress** — actively being worked on +- **Done** — completed (hidden from the default board view, which filters with `-status:Done`) + +### Priority + +- **High** — should be picked up first; usually foundational or blocking other work +- **Medium** — important, but not urgent +- **Low** — nice to have, or exploratory + +Priority reflects project importance, not difficulty. A `good first issue` can still carry +a `High` priority label. + +### Iteration + +Some issues are assigned to a numbered iteration (e.g. `Iteration 2`) for sprint-style +planning. Most issues are not yet assigned to an iteration and simply sit in the backlog +until prioritized. + +### Size + +An optional t-shirt-size estimate (e.g. `M`) can be set on an issue once its scope is +understood. Most issues do not yet have a size set — add one if you have enough context +to estimate the work, but don't block on it. + +## Issue Types + +GitHub's built-in issue type field (`Bug`, `Feature`, `Task`) is available and used on some +issues (for example, #4 is typed `Task`), but adoption across the backlog is inconsistent — +many issues, including substantial engineering proposals, currently have no type set. If +you're triaging or filing an issue, setting a type when it's clear-cut (a defect is a `Bug`, +a net-new capability is a `Feature`, exploratory or maintenance work is a `Task`) is helpful, +but don't assume an unset type means anything in particular about an existing issue. + +## Label Taxonomy + +Labels fall into two categories: **area labels**, which describe what part of the system an +issue touches, and **triage labels**, which describe the issue's status or kind. + +### Area Labels + +| Label | Description | +| --- | --- | +| `agents` | Multi-agent / LangGraph | +| `auth` | Authentication and authorization | +| `dx` | Developer experience | +| `ops` | Observability, monitoring, alerting | +| `partners` | Partner integrations and visibility | +| `platform` | Infrastructure, deployment, hosting | +| `rag` | Retrieval pipeline | +| `safety` | AI safety, guardrails, response quality | +| `security` | Security and compliance | +| `ux` | User experience and interface | + +An issue can carry more than one area label if it spans multiple parts of the system. + +### Triage Labels + +| Label | Description | +| --- | --- | +| `documentation` | Improvements or additions to documentation | +| `duplicate` | This issue or pull request already exists | +| `good first issue` | Good for newcomers | +| `help wanted` | Extra attention is needed | +| `invalid` | This doesn't seem right | +| `question` | Further information is requested | +| `wontfix` | This will not be worked on | + +## Triage Process + +When a new issue comes in: + +1. A maintainer adds it to the [project board](https://github.com/orgs/Finntegrate/projects/1), + which sets its initial **Status** to `Todo`. +2. The maintainer applies relevant **area label(s)** and a **Priority**. +3. If the issue looks approachable for new contributors, `good first issue` and/or + `help wanted` are added. +4. Contributors can comment on an issue to claim it, then open a pull request that + references the issue number once work begins, following the + [Pull Request Process](CONTRIBUTING.md#pull-request-process) in `CONTRIBUTING.md`. From c0c0039a92eb5c87f521c098f52a633ce0932d36 Mon Sep 17 00:00:00 2001 From: Neha Biswas Date: Sun, 28 Jun 2026 19:00:55 +0530 Subject: [PATCH 2/4] Update .github/ISSUE_TEMPLATE/task.yml Co-authored-by: Brylie Oxley --- .github/ISSUE_TEMPLATE/task.yml | 2 -- 1 file changed, 2 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/task.yml b/.github/ISSUE_TEMPLATE/task.yml index df04a4b..b79ba0f 100644 --- a/.github/ISSUE_TEMPLATE/task.yml +++ b/.github/ISSUE_TEMPLATE/task.yml @@ -1,8 +1,6 @@ name: Task / research spike description: Exploratory work, maintenance, or a task that doesn't fit a bug or feature title: "[Task]: " -labels: - - task type: Task body: - type: markdown From 863b10205a9385685d61aceb9a5f39a98d500b67 Mon Sep 17 00:00:00 2001 From: Neha Biswas Date: Tue, 30 Jun 2026 21:18:12 +0530 Subject: [PATCH 3/4] Apply suggestion from @brylie Co-authored-by: Brylie Oxley --- .github/ISSUE_TEMPLATE/bug_report.yml | 2 -- 1 file changed, 2 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index 01af5b0..3a8a8c0 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -1,8 +1,6 @@ name: Bug report description: Report something that isn't working as expected title: "[Bug]: " -labels: - - bug type: Bug body: - type: markdown From 6da5d52fa076f408777826e7064b54485cc7fdaf Mon Sep 17 00:00:00 2001 From: Neha Biswas Date: Tue, 30 Jun 2026 21:18:26 +0530 Subject: [PATCH 4/4] Apply suggestion from @brylie Co-authored-by: Brylie Oxley --- .github/ISSUE_TEMPLATE/feature_request.yml | 2 -- 1 file changed, 2 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml index bdeef37..d241ef5 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.yml +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -1,8 +1,6 @@ name: Feature request description: Suggest a new capability or enhancement title: "[Feature]: " -labels: - - enhancement type: Feature body: - type: markdown