From 2945fd5e60626462ac19af71bbd0ce6b557df974 Mon Sep 17 00:00:00 2001 From: Zoheb Shaikh <26975142+ZohebShaikh@users.noreply.github.com> Date: Mon, 16 Nov 2026 12:44:45 +0000 Subject: [PATCH] docs: Update contribution guidelines --- .github/CODEOWNERS | 3 + .github/CONTRIBUTING.md | 78 ++++++++++++++++++- .github/ISSUE_TEMPLATE/1_bug_report.yml | 67 ++++++++++++++++ .github/ISSUE_TEMPLATE/2_feature_or_task.yml | 39 ++++++++++ .github/ISSUE_TEMPLATE/bug_report.md | 21 ----- .github/ISSUE_TEMPLATE/config.yml | 8 ++ .github/ISSUE_TEMPLATE/issue.md | 13 ---- .../pull_request_template.md | 18 +++++ .github/workflows/triage.yml | 58 ++++++++++++++ 9 files changed, 267 insertions(+), 38 deletions(-) create mode 100644 .github/CODEOWNERS create mode 100644 .github/ISSUE_TEMPLATE/1_bug_report.yml create mode 100644 .github/ISSUE_TEMPLATE/2_feature_or_task.yml delete mode 100644 .github/ISSUE_TEMPLATE/bug_report.md create mode 100644 .github/ISSUE_TEMPLATE/config.yml delete mode 100644 .github/ISSUE_TEMPLATE/issue.md create mode 100644 .github/workflows/triage.yml diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 0000000000..3efe49b16e --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,3 @@ +# Requests a review from the core team on every PR. GitHub's team +# auto-assignment (round robin) then picks one member, see CONTRIBUTING.md. +* @DiamondLightSource/developers-daq-core diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 31f4d34f32..f8887b016f 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -1,17 +1,87 @@ # Contribute to the project Contributions and issues are most welcome! All issues and pull requests are -handled through [GitHub](https://github.com/DiamondLightSource/blueapi/issues). Also, please check for any existing issues before -filing a new one. If you have a great idea but it involves big changes, please -file a ticket before making a pull request! We want to make sure you don't spend +handled through [GitHub](https://github.com/DiamondLightSource/blueapi/issues). Please check for existing issues before +filing a new one. If you have a great idea that involves big changes, please +open an issue before making a pull request. We want to make sure you don't spend your time coding something that might not fit the scope of the project. +The [DAQ core team](https://github.com/orgs/DiamondLightSource/teams/developers-daq-core) maintains this repository. + ## Issue or Discussion? -Github also offers [discussions](https://github.com/DiamondLightSource/blueapi/discussions) as a place to ask questions and share ideas. If +GitHub also offers [discussions](https://github.com/DiamondLightSource/blueapi/discussions) as a place to ask questions and share ideas. If your issue is open ended and it is not obvious when it can be "closed", please raise it as a discussion instead. +## Reporting security issues + +Please do not report security vulnerabilities in public issues. Use GitHub's +[private vulnerability reporting](https://github.com/DiamondLightSource/blueapi/security/advisories/new) +instead, so only the maintainers can see the report until a fix is released. + +## Issue lifecycle + +Every new issue starts with `needs-triage`. A core team member triages it by +swapping that label (and `awaiting-response`, if present) for one of the status +labels below. An issue has one status label at a time. + +| Label | Meaning | +| --- | --- | +| `needs-triage` | New, not yet looked at by the core team | +| `needs-info` | Waiting on the reporter for details or a reproduction. A reply from the reporter moves it back to `needs-triage`. Otherwise it is marked `stale` after 30 days and closed 7 days later | +| `under-discussion` | Accepted as a problem; the solution is still being worked out | +| `ready` | Agreed, scoped and has acceptance criteria. Anyone can pick it up | +| `backlog` | Valid, but not planned for now | +| `help-wanted` | We would welcome an outside contribution. Combine with `onboarding` for good first issues | +| `wont-do` | Out of scope or rejected. The issue is closed with a comment explaining why | + +Before starting on an issue, comment on it so it can be assigned to you and +work isn't duplicated. + +### Support priority + +Support staff can mark how urgently an issue affects beamline operations, +independently of the core team's own planning (`priority low`/`priority high`): + +| Label | Meaning | +| --- | --- | +| `support: critical` | Blocking experiments or users right now | +| `support: high` | Significant impact, workaround is painful | +| `support: medium` | Noticeable impact, workaround exists | +| `support: low` | Minor or cosmetic | + +The core team uses these labels as input when triaging and planning. + +## Pull requests + +- Link the issue it resolves (`Fixes #123`). Small fixes like typos don't need an issue. +- Keep pull requests small and focused on one change. Large changes are easier to review as a series. +- The title must follow [Conventional Commits](https://www.conventionalcommits.org/) (`feat:`, `fix:`, `docs:`, ...). CI checks this, and the title becomes the squashed commit message and release note. +- Add or update tests and docs alongside the code. +- Open as a draft while work is in progress, and mark it ready when you want a review. +- Pull requests need one approving review and passing CI before merging. + +### Reviews + +When a pull request is opened or marked ready for review, a member of the core +team is assigned as reviewer in turn (round-robin). This uses `CODEOWNERS` and +GitHub's [team review assignment](https://docs.github.com/en/organizations/organizing-members-into-teams/managing-code-review-settings-for-your-team). The assigned reviewer owns getting the pull request to a +decision. They may review it themselves or hand it to someone better placed. + +Reviewers should: + +- Be kind and explain the reasoning behind requests. +- Prefix optional suggestions with `nit:` so authors know what is blocking. +- Resolve their own threads once satisfied, and approve once there is nothing blocking. + +### Response times + +We aim to give every new issue and pull request a first response from the core +team within 3 days. A response can be a comment, a review or a triage +decision; it doesn't need to be a solution. If an issue still needs triage after +that time, a bot labels it `awaiting-response` and mentions the core team. + ## Code Coverage While 100% code coverage does not make a library bug-free, it significantly diff --git a/.github/ISSUE_TEMPLATE/1_bug_report.yml b/.github/ISSUE_TEMPLATE/1_bug_report.yml new file mode 100644 index 0000000000..f20eac3f31 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/1_bug_report.yml @@ -0,0 +1,67 @@ +name: Bug report +description: Report a bug or unexpected behaviour +labels: [bug, needs-triage] +body: + - type: markdown + attributes: + value: | + Thanks for taking the time to report this! Please search [existing issues](https://github.com/DiamondLightSource/blueapi/issues?q=is%3Aissue) (including closed ones) first. + Questions belong in [Discussions](https://github.com/DiamondLightSource/blueapi/discussions). Please report security vulnerabilities [privately](https://github.com/DiamondLightSource/blueapi/security/advisories/new), not here. + - type: textarea + id: description + attributes: + label: Description + description: What happened, and what did you expect to happen instead? + validations: + required: true + - type: textarea + id: reproduce + attributes: + label: Steps to reproduce + description: The smallest set of steps, commands, config or plan that shows the bug. + placeholder: | + 1. Start the server with `blueapi -c config.yaml serve` + 2. Run `blueapi controller run -i cm12345-1 my_plan '{"x": 1}'` + 3. See error + validations: + required: true + - type: textarea + id: logs + attributes: + label: Logs and tracebacks + description: Paste any relevant output. It is formatted as code automatically. + render: text + - type: input + id: version + attributes: + label: blueapi version + description: Output of `blueapi --version` + placeholder: blueapi, version 1.2.3 + validations: + required: true + - type: dropdown + id: environment + attributes: + label: Where are you running blueapi? + options: + - Beamline deployment (Kubernetes/Helm) + - Local or developer machine + - Other (say in the description) + validations: + required: true + - type: dropdown + id: impact + attributes: + label: Impact on operations + description: Helps the support team set a `support:` priority label. + options: + - Blocking experiments or users right now + - Significant, workaround is painful + - Noticeable, workaround exists + - Minor or cosmetic + - type: textarea + id: acceptance + attributes: + label: Acceptance criteria + description: How will we know this is fixed? + placeholder: "- Running X no longer raises Y" diff --git a/.github/ISSUE_TEMPLATE/2_feature_or_task.yml b/.github/ISSUE_TEMPLATE/2_feature_or_task.yml new file mode 100644 index 0000000000..b451f8dd09 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/2_feature_or_task.yml @@ -0,0 +1,39 @@ +name: Feature request or task +description: Suggest a new feature, design change or piece of work +labels: [needs-triage] +body: + - type: markdown + attributes: + value: | + Please search [existing issues](https://github.com/DiamondLightSource/blueapi/issues?q=is%3Aissue) first. Open-ended ideas are better started in [Discussions](https://github.com/DiamondLightSource/blueapi/discussions). + - type: textarea + id: problem + attributes: + label: Problem or motivation + description: What are you trying to do, who needs it, and why is it hard today? + validations: + required: true + - type: textarea + id: proposal + attributes: + label: Proposed solution + description: What you'd like to happen. Rough ideas are fine. + - type: textarea + id: alternatives + attributes: + label: Alternatives considered + description: Other approaches or workarounds you've thought about. + - type: textarea + id: acceptance + attributes: + label: Acceptance criteria + description: Specific criteria that will be used to judge if the issue is done. + placeholder: "- Users can do X from the CLI" + validations: + required: true + - type: checkboxes + id: contribute + attributes: + label: Contributing + options: + - label: I'd be willing to open a pull request for this diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md deleted file mode 100644 index 92087f5bcc..0000000000 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -name: Bug Report -about: The template to use for reporting bugs and usability issues -title: " " -labels: 'bug' -assignees: '' - ---- - -Describe the bug, including a clear and concise description of the expected behaviour, the actual behavior and the context in which you encountered it (ideally include details of your environment). - -## Steps To Reproduce -Steps to reproduce the behavior: -1. Go to '...' -2. Click on '....' -3. Scroll down to '....' -4. See error - - -## Acceptance Criteria -- Specific criteria that will be used to judge if the issue is fixed diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000000..196822f3c9 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,8 @@ +blank_issues_enabled: false +contact_links: + - name: Questions and ideas + url: https://github.com/DiamondLightSource/blueapi/discussions + about: Ask open-ended questions or float ideas in Discussions + - name: Report a security vulnerability + url: https://github.com/DiamondLightSource/blueapi/security/advisories/new + about: Report security issues privately to the maintainers diff --git a/.github/ISSUE_TEMPLATE/issue.md b/.github/ISSUE_TEMPLATE/issue.md deleted file mode 100644 index 52c84dd853..0000000000 --- a/.github/ISSUE_TEMPLATE/issue.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -name: Issue -about: The standard template to use for feature requests, design discussions and tasks -title: " " -labels: '' -assignees: '' - ---- - -A brief description of the issue, including specific stakeholders and the business case where appropriate - -## Acceptance Criteria -- Specific criteria that will be used to judge if the issue is fixed diff --git a/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md b/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md index 8200afe5c4..e266b9b745 100644 --- a/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md +++ b/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md @@ -1,8 +1,26 @@ + + Fixes #ISSUE +### What and why + + ### Instructions to reviewer on how to test: 1. Do thing x 2. Confirm thing y happens +### Breaking changes + + +### Checks for author +- [ ] Tests added or updated, and coverage has not dropped +- [ ] Docs updated if behaviour, config or the API changed + ### Checks for reviewer - [ ] Would the PR title make sense to a user on a set of release notes +- [ ] Are breaking changes clearly described above diff --git a/.github/workflows/triage.yml b/.github/workflows/triage.yml new file mode 100644 index 0000000000..376b025bbd --- /dev/null +++ b/.github/workflows/triage.yml @@ -0,0 +1,58 @@ +name: Triage + +# schedule and issue_comment only ever run the copy of this file on main, +# so nothing here takes effect until it has been reviewed and merged. +on: + schedule: + - cron: "0 9 * * 1-5" + issue_comment: + types: [created] + workflow_dispatch: + +permissions: + issues: write + +jobs: + stale: + if: github.repository == 'DiamondLightSource/blueapi' && github.event_name != 'issue_comment' + runs-on: ubuntu-latest + steps: + # PRs are left out: the round-robin reviewer already has a review request, + # and stale can't tell whether a PR is waiting on the reviewer or the author. + - name: Nudge the core team on untriaged issues + uses: actions/stale@v11 + with: + only-issue-labels: needs-triage + days-before-stale: 3 + days-before-close: -1 + days-before-pr-stale: -1 + stale-issue-label: awaiting-response + stale-issue-message: "@DiamondLightSource/developers-daq-core this issue has had no activity for 3 days and still needs triage. See [response times](https://github.com/DiamondLightSource/blueapi/blob/main/.github/CONTRIBUTING.md#response-times)." + # Ignore everything opened before this workflow was introduced. Set to the merge date. + start-date: "2026-11-15T00:00:00Z" + + - name: Close issues waiting on the reporter + uses: actions/stale@v11 + with: + only-labels: needs-info + days-before-stale: 30 + days-before-close: 7 + days-before-pr-stale: -1 + stale-issue-label: stale + stale-issue-message: "This issue has been waiting for more information for 30 days. It will be closed in 7 days unless there is a reply." + close-issue-message: "Closing as there was no reply. Please comment with the requested details and we will reopen it." + close-issue-reason: not_planned + + # A reply from the reporter hands the issue back to the core team, + # so needs-info never closes an issue that is waiting on us. + reporter-replied: + if: >- + github.event_name == 'issue_comment' && !github.event.issue.pull_request && + github.event.comment.user.login == github.event.issue.user.login && + contains(github.event.issue.labels.*.name, 'needs-info') + runs-on: ubuntu-latest + steps: + - run: gh issue edit "$NUMBER" -R "$GITHUB_REPOSITORY" --remove-label needs-info,stale --add-label needs-triage + env: + GH_TOKEN: ${{ github.token }} + NUMBER: ${{ github.event.issue.number }}