Contribution process proposal

# Contribution Process Proposal

With the recent increase in contribution activity in our repository, it seems like a good time to formalize and automate our contribution process.

The [hier-sdk-python](https://github.com/hiero-ledger/hiero-sdk-python)
repository uses a well-designed workflow developed by its community. @exploreriii also gave an excellent presentation on this at LFDT Maintainer Days ([available on YouTube](https://www.youtube.com/watch?v=I87WCpiXOOs)). Inspired by that work, I’d like to propose the following process.

## Roles

| Role | Definition |
|----------------------|---|
| **Maintainer** | Has `admin` or `write` permission on the repository |
| **Core contributor** | Has `triage` permission on the repository |
| **Contributor** | Everyone else |

Maintainers and core contributors are exempt from all assignment and PR-linking rules described below. PRs from `dependabot` are also exempt. Maintainers may directly assign any contributor to any issue at any time, bypassing eligibility checks.

## Issue Lifecycle

### Issue types

Every issue should carry a type:

- `bug` — something is broken
- `feature` — new feature or improvement
- `task` - a specific piece of work

And zero or more state labels:

- `good-first-issue` — well-scoped, self-contained; suitable for a first contribution
- `ready` — triaged and accepted; an external contributor may open a PR for this issue

An issue without a `ready` label is **not ready for contribution**. External contributors should not start work on issues without one of these labels.

### Creating an issue

Anyone may open an issue using the `bug` or `feature` template. New issues start untriaged. Maintainers review and apply `ready` or `good-first-issue` once the issue is well-defined and accepted.

### Claiming an issue

Contributors must claim an issue **before** opening a PR:

1. Comment `/assign` on the issue.
2. The bot checks:
- The issue carries `ready`.
- The contributor has **no more than two open assigned issues** (limit: 2 across all issues).
3. If both conditions are met, the bot assigns the contributor and confirms in a comment.
4. To release an issue voluntarily, comment `/unassign`.

Maintainers may assign any contributor directly via GitHub's native assignment UI — this bypasses all bot eligibility checks.

### Issue inactivity

Once assigned, the bot monitors activity (comments, linked PR events):

- **After 5 days of no activity**: bot posts a reminder comment tagging the assignee.
- **After 7 days of no activity**: bot unassigns the contributor with an explanatory comment. The issue becomes available for others to claim.
- **After 9 days assigned with no linked PR opened**: bot posts a reminder asking the contributor to open a PR or comment `/working` if they are still active.

A contributor can reset the inactivity timer at any time by commenting `/working`.

## PR Lifecycle

### Linking a PR to an issue

Every PR opened by an contributor must reference an open issue carrying `ready`, using a closing keyword in the PR description (e.g. `Fixes #123`). Additionally:

- The PR author must be **assigned to the linked issue**.

PRs by maintainers, core contributors, and `dependabot` are exempt from both requirements.

If either condition is not met for an contributor's PR, the bot posts a warning comment. If the PR remains non-compliant for **12 hours**, it is automatically closed with an explanation.

### PR inactivity

- **After 5 days of no activity** (commits, review responses, comments): bot posts a reminder tagging the author.
- **After 7 days of no activity**: bot closes the PR with an explanatory comment. The linked issue is **not** automatically unassigned — the contributor may open a new PR against the same issue within their original assignment window.

### PR checks

Standard automated checks run on every PR:

- DCO sign-off
- Unit tests
- Integration tests
- Linter
- etc ..

A PR may not be merged until all checks pass. Maintainers may override in exceptional circumstances.

## Coordination Summary

```
Maintainer triages issue → labels it `ready`
↓
Contributor comments /assign
↓
Bot checks: label ok + open assignments within limits → assigns contributor
↓
Contributor opens PR with "Fixes #N" within 7 days
↓
Bot verifies: issue is open + author is assigned to it
↓
CI passes + maintainer review → merge → issue closes automatically
```

---

# Next steps

Please review the proposal and share your feedback so we can refine it further. Once aligned, we can implement the process and test it on the fabric-x repository. If it proves effective, we can roll it out across other repositories (e.g., orderer, committer, FSC, TokenSDK, etc.).

What do you think?