diff --git a/docs/dev/how-to/contribute.md b/docs/dev/how-to/contribute.md index a12a991c1..8e6791063 100644 --- a/docs/dev/how-to/contribute.md +++ b/docs/dev/how-to/contribute.md @@ -52,3 +52,22 @@ - **Trivial Changes:** For minor changes like fixing typos, feel free to skip the issue creation step and go straight to making a PR. - **Stay Up-to-Date:** Make sure your branch is up-to-date with the latest changes in the main branch before submitting your PR. Use `git rebase` if necessary. + +### 6. CI Automation + +DIRACGrid repositories use shared CI workflows (defined in [`DIRACGrid/.github`](https://github.com/DIRACGrid/.github)) to streamline the review process. + +#### Automatic draft conversion on changes requested + +When a reviewer requests changes on your PR, it is **automatically converted to a draft**. This makes it clear that the PR is back in the contributor's hands and not ready for another review round. + +Once you've addressed the feedback: + +1. Push your updates to the branch. +2. Mark the PR as **Ready for review** again using the GitHub UI. + +The reviewer will be re-notified and can continue the review. + +#### PR review reminders + +A daily digest of open (non-draft) PRs is posted to Mattermost on weekday mornings. The digest includes the PR title, author, assigned reviewer, age, and review status for all repositories in the DIRACGrid organisation. This ensures that open PRs don't get forgotten. diff --git a/docs/dev/reference/issue-triage.md b/docs/dev/reference/issue-triage.md new file mode 100644 index 000000000..1f1351a7c --- /dev/null +++ b/docs/dev/reference/issue-triage.md @@ -0,0 +1,120 @@ +# Issue Triage and Project Management + +This page describes how issues are tracked and triaged across DIRACGrid repositories using GitHub Projects. + +## Issue workflow + +Issues follow a structured process from idea to completion: + +```mermaid +stateDiagram-v2 + [*] --> Idea + + Idea --> IssueCreated : Anyone creates GitHub issue + + IssueCreated --> NeedsTriage : Auto-added to Project + + NeedsTriage --> NeedsDesign : Complex/risky, needs architect input + NeedsTriage --> Triaged : Valid issue, needs refinement + + NeedsDesign --> Triaged : Architect provides design doc/ADR + + Triaged --> ReadyForSprint : Clear scope + acceptance criteria + estimate + + ReadyForSprint --> InSprint : Selected during sprint planning + + InSprint --> InProgress : Contributor starts work + + InProgress --> InReview : PR opened + + InReview --> InProgress : Changes requested in review + InReview --> Done : PR approved and merged + + Done --> [*] +``` + +## Workflow states + +Issues are tracked through **Project Status** fields, not labels. + +### Needs Triage + +New issues are automatically added to the Project with Status = "Needs triage". Maintainers review the issue to: + +- Confirm it's valid and not a duplicate +- Set appropriate fields (see [Project fields](#project-fields) below) +- Determine if it needs design work or can go to the backlog + +### Needs Design + +Applied to complex or risky issues that require architectural input. An architect or senior developer will: + +- Create a design document or Architecture Decision Record (ADR) +- Outline the technical approach +- Identify potential risks or trade-offs + +Once design is complete, status moves to "Triaged". + +### Triaged + +The issue is valid and understood but needs refinement. During refinement/grooming: + +- Add clear acceptance criteria +- Add a story point estimate using the **Story Points** field +- Clarify any open questions + +Once refined, status moves to "Ready for sprint". + +### Ready for Sprint + +The issue has clear scope, acceptance criteria, and a story point estimate. It is ready to be selected during sprint planning. Only maintainers can move issues to this status. + +### In Sprint + +The issue is assigned to a specific sprint using the **Sprint** field. It was selected during the sprint planning meeting and a developer may be assigned at this stage. + +### In Progress + +A developer has started work. Typically indicated by an open PR or assignment. The issue should be linked to the PR. + +### In Review + +A pull request has been opened and is awaiting code review. May loop back to "In Progress" if changes are requested. + +### Done + +The PR has been approved and merged. The issue is automatically closed if properly linked in the PR (e.g. `Closes #123`). + +## Project fields + +Each issue in the GitHub Project has the following fields: + +| Field | Values | +| -------------------- | ----------------------------------------------------------------------------- | +| **Area** (epic) | pilot, core, wf-mgmt, data-mgmt, resource-mgmt, deployment, obs-analytics, ui | +| **Priority** (label) | priority:critical, priority:high, priority:medium, priority:low | +| **Type** (label) | bug, enhancement, documentation, question | +| **Story Points** | Estimated effort | +| **Sprint** | Sprint assignment | + +## Creating issues + +### Bug reports + +When creating a bug report, include: + +- A clear description of the bug +- Confirmation that you've searched for duplicates +- Steps to reproduce the issue +- Expected vs. actual behaviour +- Environment details (OS, version, etc.) +- Log output if available + +### Feature requests + +When requesting a feature, provide: + +- A user story (As a [user], I want [goal], so that [benefit]) +- Description of the proposed feature +- Definition of Done -- what criteria must be met? +- Related or blocking issues diff --git a/mkdocs.yml b/mkdocs.yml index 462c4d046..1650a82ff 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -184,6 +184,7 @@ nav: - Security policies: dev/reference/security-policies.md - Security properties: dev/reference/security-properties.md - Test recipes: dev/reference/test-recipes.md + - Issue triage: dev/reference/issue-triage.md markdown_extensions: - admonition