Quarkus GitHub Lottery
A Quarkus-powered GitHub App that regularly sends short lists of GitHub issues for triagers/maintainers/stewards to consider.
Introduction
This GitHub App is based on the Quarkus GitHub App framework.
It periodically extracts GitHub issues from one "source" GitHub repository (e.g. https://github.com/quarkusio/quarkus) and notifies maintainers about them by commenting on GitHub issues in another "notification" GitHub repository (e.g. https://github.com/quarkusio/quarkus-github-lottery-reports). That second "notification" repository may be private, as it’s only about notifying maintainers.
Each maintainer who participates in the lottery (opt-in) gets their own dedicated GitHub issue in the "reports" repository, on which the application will add one comment mentioning the maintainer each time its sends a notification. That way, maintainers will get daily (or weekly) reports via email, sent by GitHub when the comment is added.
Issues are randomly assigned among eligible maintainers up to a limit they define themselves, so that everyone gets a chance to help according to the time they want to invest.
There are multiple categories of issues that one can be notified about; see Triagers/Maintainers/Stewards: how to get notifications for more information, but here’s what an email notification may look like:
Triagers/Maintainers/Stewards: how to get notifications
Basics
As a Quarkus triager, a Quarkus core/extension maintainer, or a Quarkus steward, in order to get notifications about Quarkus issues on GitHub:
-
Make sure you have access to the "notification" repository if not, request access to an admin of the quarkusio organization.
-
Send a pull request to the "watched" repository (most likely https://github.com/quarkusio/quarkus) to edit file
.github/quarkus-github-lottery.yml
. Add an entry with your username to theparticipants
section.
Here is what an entry will look like:
# [...]
participants:
- username: "yrodiere"
timezone: "Europe/Paris"
triage:
days: ["MONDAY", "WEDNESDAY", "FRIDAY"]
maxIssues: 3
maintenance:
labels: ["area/hibernate-orm", "area/hibernate-search"]
days: ["TUESDAY"]
feedback:
needed:
maxIssues: 4
provided:
maxIssues: 2
stale:
maxIssues: 5
stewardship:
days: ["MONDAY"]
maxIssues: 5
username
-
Your GitHub username.
String, mandatory, no default.
timezone
-
Your timezone, to get notifications at the right time on the right day.
java.time.ZoneId
as a String, optional, defaults toUTC
. triage
-
Optional section for triagers.
See Triage for details.
maintenance
-
Optional section for maintainers.
See Maintenance for details.
stewardship
-
Optional section for stewards.
See Stewardship for details.
The triage
, maintenance
and stewardship
sections are all optional;
you may participate in triage but not maintain an area of Quarkus nor do any stewardship, and vice-versa,
or do everything.
See below for details about each section.
Triage
If the triage
section is present, you will get notified when new issues are created
and need to be routed to the right person/team.
Addressing these notifications generally involves removing the triage/needs-triage
label,
adding the correct area/*
labels, and optionally pinging the relevant maintainers
(though the Quarkus GitHub Bot should generally take care of that part
once you add area/*
labels).
Of course, some more discussion might be necessary before that, and that’s fine: issues that don’t change will reappear in another notification, a few days later.
The triage
section will look like this:
# [...]
participants:
- username: "yrodiere"
triage:
days: ["MONDAY", "TUESDAY", "WEDNESDAY", "THURSDAY", "FRIDAY"]
maxIssues: 3
days
-
On which days you wish to get notified about triage.
Array of
WeekDay
s, mandatory, no default. maxIssues
-
How many issues, at most, you wish to be included in the "triage" category for each notification.
Integer, mandatory, no default.
Maintenance
If the maintenance
section is present, you will get notified about issues
related to a specific area (e.g. area/hibernate-orm
)
that may be stalled and require intervention from maintainers or reporters.
Issues in "maintenance" notifications will be split in three categories:
- Feedback Needed
-
These issues have the
triage/needs-reproducer
label, and it looks like the Quarkus team was the last to comment on the issue, quite some time ago.Depending on the actual content of the issue, you might want to:
-
send a (gentle!) reminder to the reporter that we need feedback (a reproducer, more information, …) before we can do anything.
-
or, if it’s really been too long, close the issue because we cannot work on it.
-
- Feedback Provided
-
These issues have the
triage/needs-reproducer
label, and it looks like someone who is not from the Quarkus team was the last to comment on the issue, quite some time ago.There might be feedback (a reproducer, more information, …) there, in which case you might want to remove the
triage/needs-reproducer
label and have a closer look. - Stale
-
These issues have not been updated for a very long time.
Depending on the actual content of the issue, you might want to:
-
prioritize the issue and work on it soon;
-
or send a reminder to someone you’ve been waiting on;
-
or close the issue because it’s no longer relevant.
-
Of course, in every situation, simply continuing the conversation, pinging someone, or even doing nothing at all are perfectly acceptable responses: it’s all up to you, and issues that don’t change will reappear in another notification, a few days later.
The maintenance
section will look like this:
# [...]
participants:
- username: "yrodiere"
maintenance:
labels: ["area/hibernate-orm", "area/hibernate-search", "area/elasticsearch"]
days: ["MONDAY", "TUESDAY", "WEDNESDAY", "THURSDAY", "FRIDAY"]
feedback:
needed:
maxIssues: 4
provided:
maxIssues: 2
stale:
maxIssues: 5
labels
-
The labels identifying issues you are interested in, as a maintainer. Issues mentioned in notifications will have at least one of those labels.
Array of Strings, mandatory, no default.
days
-
On which days you wish to get notified about maintenance.
Array of
WeekDay
s, mandatory, no default. feedback.needed.maxIssues
-
How many issues, at most, you wish to be included in the "Feedback needed" category for each notification.
Integer, mandatory, no default.
feedback.provided.maxIssues
-
How many issues, at most, you wish to be included in the "Feedback provided" category for each notification.
Integer, mandatory, no default.
stale.maxIssues
-
How many issues, at most, you wish to be included in the "Stale" category for each notification.
Integer, mandatory, no default.
Stewardship
Important
|
This section should only be of interest to stewards: core contributors who spend significant time working on GitHub issues. If you don’t already know what this section is about, you probably don’t want to use it. |
If the stewardship
section is present, you will get notified about issues that just became stale,
across the whole project, without any consideration for the labels assigned to those issues.
Depending on the actual content of the issue, you might want to simply continue the conversation, ping someone, close the issue, or even do nothing at all: it’s all up to you, and issues that don’t change will reappear in another notification, a few days later.
Note
|
Notifications to stewards are sent independently of notifications to maintainers, so that the work of maintainers won’t be affected by the work of stewards. It is entirely possible for a maintainer to be notified about an issue at the same time as a steward. |
The stewardship
section will look like this:
# [...]
participants:
- username: "yrodiere"
stewardship:
days: ["MONDAY"]
maxIssues: 5
days
-
On which days you wish to get notified about stewardship.
Array of
WeekDay
s, mandatory, no default. maxIssues
-
How many issues, at most, you wish to be included in the "stewardship" category for each notification.
Integer, mandatory, no default.
Suspending notifications
You can suspend notifications (temporarily or forever) simply by closing the dedicated GitHub issue created for you in the "notification" repository.
See the footnote in the notifications you receive.
Admins: how to install and initialize configuration
Installing
Here is a link to the application on GitHub: https://github.com/apps/quarkus-github-lottery
The application needs to be installed on both the "source" repository (the one issues are extracted from) and the "notification" repository (the one "notification" issues are added to).
Important
|
For security reasons, the two GitHub repositories need to be in the same organization (technically, the same "installation"). Failing that, lottery draws will error out and will not send any notification. |
Tip
|
The "notification" repository should ideally be private:
|
Configuring
The configuration file .github/quarkus-github-lottery.yml
includes several sections that are common to all participants to the lottery:
notifications:
createIssues:
repository: "quarkusio/quarkus-github-lottery-reports"
buckets:
triage:
label: "triage/needs-triage"
delay: PT0S
timeout: P3D
maintenance:
feedback:
label: "triage/needs-reproducer"
needed:
delay: P21D
timeout: P3D
provided:
delay: P7D
timeout: P3D
stale:
delay: P60D
timeout: P14D
stewardship:
delay: P60D
timeout: P14D
# [...]
notifications.createIssues.repository
-
The full name of the GitHub repository where "reports"/"notification issues" will be created.
String, mandatory, no default.
buckets.triage.label
-
The label identifying GitHub issues that require triage.
String, mandatory, no default.
buckets.triage.delay
-
How much time to wait after the last update on an issue before including it in the lottery in the "triage" bucket.
String in ISO-8601 duration format, mandatory, no default.
buckets.triage.timeout
-
How much time to wait after an issue was last notified about before including it again in the lottery in the "triage" bucket.
String in ISO-8601 duration format, mandatory, no default.
buckets.maintenance.feedback.label
-
The label identifying GitHub issues for which feedback (a reproducer, more information, …) was requested.
String, mandatory, no default.
buckets.maintenance.feedback.needed.delay
-
How much time to wait after the last update on an issue before including it in the lottery in the "feedback needed" bucket.
String in ISO-8601 duration format, mandatory, no default.
buckets.maintenance.feedback.needed.timeout
-
How much time to wait after an issue was last notified about before including it again in the lottery in the "feedback needed" bucket.
String in ISO-8601 duration format, mandatory, no default.
buckets.maintenance.feedback.provided.delay
-
How much time to wait after the last update on an issue before including it in the lottery in the "feedback provided" bucket.
String in ISO-8601 duration format, mandatory, no default.
buckets.maintenance.feedback.provided.timeout
-
How much time to wait after an issue was last notified about before including it again in the lottery in the "feedback provided" bucket.
String in ISO-8601 duration format, mandatory, no default.
buckets.maintenance.stale.delay
-
How much time to wait after the last update on an issue before including it in the lottery in the "stale" bucket.
String in ISO-8601 duration format, mandatory, no default.
buckets.maintenance.stale.timeout
-
How much time to wait after an issue was last notified about before including it again in the lottery in the "stale" bucket.
String in ISO-8601 duration format, mandatory, no default.
buckets.stewardship.delay
-
How much time to wait after the last update on an issue before including it in the lottery in the "stewardship" bucket.
String in ISO-8601 duration format, mandatory, no default.
buckets.stewardship.timeout
-
How much time to wait after an issue was last notified about before including it again in the lottery in the "stewardship" bucket.
String in ISO-8601 duration format, mandatory, no default.
Validation of the configuration
The application will automatically add a check to any pull request that changes its configuration file.
The check is fairly simple, it just attempts to deserialize the YAML file and reports any exception.
Comment-based commands
Comment-based commands are available for admins. You can invoke it by adding a comment on any issue or pull request for repositories where the app is installed.
It supports the following commands:
-
/lottery draw
: force a lottery draw immediately. Timeouts are still complied with, so this command is mostly useful if you manually edited the notification history or changed the configuration, which may happen frequently in dev mode in particular.
Contributing
To participate in the development of this GitHub App, create a playground project in your own org and follow the steps outlined in the Quarkus GitHub App documentation.
When registering your app, request the following Repository permissions:
-
Checks -
Read & Write
: to validate configuration files. -
Issues -
Read & Write
: to list issues that should be notified, and create "notification" issues in another repository. -
Pull Requests -
Read & Write
: to react to comment-based commands.
And subscribe to the following events:
-
Check run, Check suite, Pull request: to validate configuration files.
-
Issue comment: to listen to comment-based commands.
Deployment
Deployment should happen automatically when pushing to the main
branch.
Maintainers can review the application and update configuration/secrets at https://console-openshift-console.apps.ospo-osci.z3b1.p1.openshiftapps.com/
Be careful about which configuration you change in the UI, as deployment may overwrite part of the topology.
License
This project is licensed under the Apache License Version 2.0.