Skip to content
Open
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
3 changes: 3 additions & 0 deletions .github/CODEOWNERS
Original file line number Diff line number Diff line change
@@ -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
78 changes: 74 additions & 4 deletions .github/CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down
67 changes: 67 additions & 0 deletions .github/ISSUE_TEMPLATE/1_bug_report.yml
Original file line number Diff line number Diff line change
@@ -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"
39 changes: 39 additions & 0 deletions .github/ISSUE_TEMPLATE/2_feature_or_task.yml
Original file line number Diff line number Diff line change
@@ -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
21 changes: 0 additions & 21 deletions .github/ISSUE_TEMPLATE/bug_report.md

This file was deleted.

8 changes: 8 additions & 0 deletions .github/ISSUE_TEMPLATE/config.yml
Original file line number Diff line number Diff line change
@@ -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
13 changes: 0 additions & 13 deletions .github/ISSUE_TEMPLATE/issue.md

This file was deleted.

18 changes: 18 additions & 0 deletions .github/PULL_REQUEST_TEMPLATE/pull_request_template.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,26 @@
<!--
Thanks for contributing! Please read .github/CONTRIBUTING.md first.
The PR title must follow Conventional Commits (e.g. "fix: Handle missing task ID");
it becomes the squashed commit message and the release note.
Open as a draft until it is ready; a reviewer is assigned when you mark it ready.
-->

Fixes #ISSUE

### What and why
<!-- What does this change, and why is it needed? -->

### Instructions to reviewer on how to test:
1. Do thing x
2. Confirm thing y happens

### Breaking changes
<!-- Anything users or deployments must change when upgrading (API, CLI, config, Helm values)? Write "None" if not. -->

### 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
58 changes: 58 additions & 0 deletions .github/workflows/triage.yml
Original file line number Diff line number Diff line change
@@ -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 }}
Loading