Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .github/CODEOWNERS
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
# Public ownership is intentionally explicit while the maintainer rotation grows.
* @openai0229

/.github/ @openai0229
/script/github/ @openai0229
198 changes: 198 additions & 0 deletions .github/COMMUNITY_OPERATIONS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,198 @@
# Community Operations

This runbook defines how Chat2DB Community work moves from intake to a shipped
release. It is the maintainer contract behind the public
[Community Project](https://github.com/orgs/OtterMind/projects/3).

## Sources Of Truth

Each concern has one owner. Do not duplicate status in labels or comments.

| Concern | Source of truth |
| --- | --- |
| Submission evidence | Issue form and Issue body |
| Work type | GitHub Issue Type |
| Product classification | `area/*`, `db/*`, `platform/*`, and `edition/*` labels |
| Missing evidence or decision | `needs/*` labels |
| Urgency | Project Priority |
| Lifecycle | Project Status |
| Active contributor | Assignee and the claim bot comment |
| Delivery commitment | Milestone |
| Implementation and verification | Linked pull request |
| User delivery | GitHub Release |

## Ownership And Response Targets

The current primary Product, Triage, Review, and Release owner is
[@openai0229](https://github.com/openai0229). A Ready Issue must also name its
review maintainer in the Issue body. A backup reviewer is required before a
task is committed to a Milestone; do not invent a backup when no second
maintainer has accepted the responsibility.

| Event | Target |
| --- | --- |
| P0 Issue acknowledgement | Same day |
| P1 Issue triage | 2 business days |
| P2 Issue triage | 7 calendar days |
| P3 Issue review | Monthly backlog review |
| Question on a Ready Issue | 3 business days |
| First substantive pull request review | 5 business days |
| Follow-up review after contributor changes | 3 business days |

An automated acknowledgement is not a substantive response. If a target will
be missed, the owner must post the blocker and next review date. If review
capacity disappears, remove the `contribution/*` label and move the Issue to
Backlog instead of leaving an unsupported task published.

Sensitive security reports use the private route in [`SECURITY.md`](../SECURITY.md)
and never enter this public queue.

## End-To-End Flow

### 1. Intake

- Reproducible defects use a Bug form.
- Product improvements use the Feature form.
- Documentation gaps use the Documentation task form.
- Repository, test, build, and maintenance work uses the Maintainer task form.
- Questions and open-ended ideas use GitHub Discussions.
- Pro, Local, or other commercial-edition work is rerouted and is not
published as a Community contribution task.

New public Issues enter Project Status `Inbox`.

### 2. Triage

The triage maintainer must set exactly one Issue Type and `edition/*` label, at
least one `area/*` or `db/*` label, one Priority, and one Project Status.
Evidence gaps use `needs/info`, `needs/reproduction`, or `needs/decision`.

Choose one outcome:

- close with a concrete duplicate, completion, support, or boundary reason;
- keep in `Backlog` while evidence or a decision is missing;
- assign for internal work;
- turn the Issue into a contributor-ready task.

### 3. Contribution-Fit Gate

Use [`contribution-boundaries.yml`](contribution-boundaries.yml) before
publishing a task.

- `open`: maintainers may scope and publish the task.
- `approval-required`: record the design or ownership decision before work.
- `closed`: do not accept public implementation; explain the reason and offer
the listed alternative.

An `open` boundary does not make an Issue Ready by itself. Scope, verification,
and review capacity are still mandatory.

### 4. Ready Contract

Before applying a `contribution/*` label, append a `Maintainer Ready Contract`
to the Issue containing all of the following:

```markdown
## Maintainer Ready Contract

- User outcome:
- In scope:
- Non-goals:
- Suggested code or documentation area:
- Acceptance criteria:
- Exact verification:
- Dependencies or required environment:
- Review maintainer: @login
- First substantive review target: 5 business days
- Milestone: version or `Not release-committed`
```

Then set Project Status to `Ready`, set Priority, and apply exactly one of:

- `contribution/good-first-issue` for bounded work with a short setup path and
an established implementation pattern;
- `contribution/help-wanted` for work that requires broader codebase or domain
knowledge.

### 5. Claim And Implementation

The contributor comments `/claim`. The bot assigns one seven-day pre-PR lease;
`/claim status`, one `/renew`, and `/unclaim` are supported. The contributor
creates a focused branch, reproduces the baseline, and opens a linked draft or
regular pull request with `Closes #<issue>`.

A linked draft pull request moves the Project item to `In Progress`. A pull
request that is ready for maintainer review moves to `In Review`.

### 6. Review And Merge

Review in this order:

1. Issue scope and non-goals.
2. User-visible correctness and compatibility.
3. Tests and the exact verification contract.
4. Security, privacy, and Community/commercial boundaries.
5. Documentation, migration, and rollback needs.

All required checks and review conversations must pass before merge. When a
real second reviewer joins the rotation, enable a required approving review on
`main`; until then, do not claim that independent review is enforced.

### 7. Milestone And Release

Milestones are product delivery windows, never workflow columns. A Milestone
must state the user outcome, due date, release owner, inclusion rule, exit
criteria, and move-out rule. Only scoped work with an owner and executable
acceptance evidence is committed.

Before closing a Milestone, the release owner verifies:

- every included Issue is closed or moved with a public reason;
- release artifacts and checksums exist for the promised platforms;
- updater and Docker paths are checked when applicable;
- release notes link the delivered Issues and pull requests;
- post-release installation or smoke verification is recorded.

The Milestone closes only after the GitHub Release is published and verified.

## Project State Matrix

| Evidence | Project Status |
| --- | --- |
| New Issue awaiting triage | Inbox |
| Confirmed but not executable | Backlog |
| Ready contract complete, no linked PR | Ready |
| Linked draft or regular PR | In Progress |
| PR ready for maintainer review | In Review |
| Issue closed or PR merged | Done |

The maintainer checks the Project weekly for closed items outside `Done`, open
items in `Done`, Ready items without a `contribution/*` label, published tasks
without a review owner, and expired Milestones.

## Operating Cadence

### Daily

- Triage new P0/P1 Issues.
- Answer contributor questions and pull request reviews due that day.
- Release expired claims through the scheduled claim workflow.

### Weekly

- Empty `Inbox` or record the owner and next action for each remaining item.
- Keep at least six unassigned Ready tasks when review capacity allows: two
good-first tasks and four help-wanted tasks.
- Reconcile Project status, contribution labels, assignees, linked pull
requests, and Milestones.

### Monthly

- Review P3 and `needs/decision` backlog items.
- Revisit contribution boundaries whose `review_after` date is approaching.
- Publish counts for new Issues, triaged Issues, Ready tasks, claims, first-time
contributor pull requests, first review time, merges, and releases.

Metrics describe observed events only. Do not report a successful external
contribution, elapsed response time, claim expiry, or release until that event
has actually occurred.
92 changes: 92 additions & 0 deletions .github/ISSUE_TEMPLATE/maintenance.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,92 @@
name: Maintainer task
description: Propose bounded test, refactoring, build, release, or repository maintenance work
type: Task
body:
- type: dropdown
id: edition
attributes:
label: Chat2DB Edition
description: Select the edition this task concerns.
options:
- Chat2DB Community
- Chat2DB Local
- Chat2DB Pro
validations:
required: true

- type: dropdown
id: category
attributes:
label: Task Category
options:
- Automated test
- Refactoring
- Build or release
- Contributor infrastructure
- Other maintenance
validations:
required: true

- type: textarea
id: problem
attributes:
label: Problem
description: Describe the concrete maintenance gap and why it matters.
validations:
required: true

- type: textarea
id: scope
attributes:
label: Scope
description: List the behavior, code, or files included in this task.
validations:
required: true

- type: textarea
id: non-goals
attributes:
label: Non-goals
description: State what this task must not change.
validations:
required: true

- type: textarea
id: acceptance
attributes:
label: Completion Criteria
description: List observable conditions a maintainer can use to accept the work.
validations:
required: true

- type: textarea
id: verification
attributes:
label: Verification
description: Provide exact commands, fixtures, or environments when known.
validations:
required: true

- type: dropdown
id: contribution
attributes:
label: Contribution
description: Tell us how you can help after the task is reviewed.
options:
- I can submit a pull request
- I can review or test a pull request
- I cannot contribute implementation work
validations:
required: true

- type: checkboxes
id: checklist
attributes:
label: Submission Checklist
options:
- label: I searched existing Issues and Discussions for duplicates.
required: true
- label: I selected the affected Chat2DB edition.
required: true
- label: This proposal does not include credentials, private data, or unpublished vulnerability details.
required: true
55 changes: 49 additions & 6 deletions .github/ISSUE_TRIAGE.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,7 @@ The machine-readable taxonomy is [`issue-taxonomy.json`](issue-taxonomy.json).
| Database compatibility bug | Bug | Database-specific connection, metadata, SQL, or editor behavior |
| Feature request | Feature | A new capability or product improvement |
| Documentation task | Task | Documentation corrections, additions, examples, or translations |
| Maintainer task | Task | Tests, refactoring, build, release, or repository maintenance |

Questions belong in GitHub Discussions. Sensitive security reports are outside
this public issue process and must be submitted through the [security policy](../SECURITY.md).
Expand Down Expand Up @@ -131,9 +132,34 @@ claim lease.
The `contribution/*` label is the claim bot's machine-readable publication
switch. Apply it only after setting Status to `Ready`, and remove it whenever a
task moves back to `Inbox` or `Backlog`; label removal automatically releases an
active claim. The linked-pull-request workflow moves work to `In Progress`.
When the pull request is ready for maintainer review, set `In Review` manually;
GitHub does not provide a built-in ready-for-review Project workflow.
active claim. The source-controlled Project workflow adds new Issues as
`Inbox`, moves linked draft pull requests to `In Progress`, ready pull requests
to `In Review`, and closed Issues or merged pull requests to `Done`.

Before publishing, apply the contribution-fit gate in
[`contribution-boundaries.yml`](contribution-boundaries.yml). `open` work can be
scoped, `approval-required` work needs a recorded design or ownership decision,
and `closed` work must be declined with the listed reason and alternative.

Every published task must append the complete `Maintainer Ready Contract` from
[`COMMUNITY_OPERATIONS.md`](COMMUNITY_OPERATIONS.md). A contribution label
without that contract, a named review maintainer, or executable verification is
a publishing defect and must be removed during weekly reconciliation.

## Ownership And Cadence

The current primary Product, Triage, Review, and Release owner is `@openai0229`.
Each Ready Issue names its actual review maintainer. A backup reviewer is
required for Milestone-committed work; leave work outside the Milestone when no
second maintainer has accepted that responsibility.

- Daily: P0/P1 triage, due contributor responses, and claim automation health.
- Weekly: empty Inbox, replenish Ready inventory, and reconcile Project drift.
- Monthly: review P3 and decision backlog, boundaries, and observed funnel data.

Ready-Issue questions target three business days, first substantive pull
request reviews target five business days, and follow-up reviews target three
business days. Automated comments do not satisfy these targets.

## Triage Procedure

Expand All @@ -148,6 +174,22 @@ GitHub does not provide a built-in ready-for-review Project workflow.
6. Close duplicates or completed work with a concrete link and GitHub state
reason.

Choose one explicit result after those fields are set: close or reroute, keep in
Backlog with the missing evidence or decision named, assign for internal work,
or publish through the Ready contract. Do not leave reviewed Issues in Inbox.

## Milestones And Release

Milestones are versioned product delivery windows, not workflow phases. Create
one only when there is a user outcome, due date, release owner, inclusion rule,
exit criteria, and move-out rule. Only scoped work with an owner and executable
acceptance evidence enters a Milestone.

Before closing a Milestone, move every incomplete Issue with a public reason,
publish and verify the GitHub Release, check promised artifacts and update paths,
and link the release notes. Project Status continues to describe workflow while
Milestone describes the delivery commitment.

The label sync script only creates or updates labels from the taxonomy. It
never deletes legacy labels.

Expand Down Expand Up @@ -180,9 +222,10 @@ issues.
review the target configuration, then add `--apply`. The script creates or
validates Project metadata, Status, Priority, repository linkage, and saved
views. It also creates a missing Project when `--project` is omitted.
6. In the Project UI, add the `Type` column where useful, rename or remove the
default `View 1`, and configure the built-in workflows printed by the script.
GitHub does not expose update APIs for these settings.
6. In the Project UI, add the `Type` column where useful and rename or remove
the default `View 1`. GitHub does not expose update APIs for those settings.
Project lifecycle automation is source-controlled in
`community-project-sync.yml` and uses the repository `ACCESS_TOKEN` secret.

Do not bulk-import the historical backlog. The Project auto-add workflow adds new
matching Issues and later re-activated historical Issues without backfilling all
Expand Down
Loading
Loading