Send clarification reply (or announcement) to specific teams and/or groups

[johnbrvc]

The current specification does not provide a way to send a reply to a clarification (or a judge's announcement) to multiple teams and/or groups. Currently, a reply (or judge's announcement) may only be sent to a single team or to ALL teams. Example use cases for this new feature could be:

1. teams that are located in a specific area of the floor or a different room. Team Question: "Where are our printouts?" Judge's Reply to teams 1,22,24,55,56: "There is a problem with the printer in your area, and it will be fixed shortly"
2. judge's announcement to specific teams (ex. those teams sitting in the first row): Announcement: "Please be careful if you must leave your workstation, since the floor is wet in your area."
3. a group in a specific region: Team Question from Hawaii: "Why aren't we getting balloons?" Reply to group 1025 (Hawaii): "The balloon printer in your region is out of toner and will be back up shortly"

Since the specification provides for the concept of "#groups" it makes sense to allow clarification reply's (or announcements) to be sent to groups in addition to a team or teams.

This is a breaking change since the to_team_id property would be changed to to_team_ids and it would be an array of ID's. I suppose it may be possible to leave to_team_id and add to_team_ids (as well as to_group_ids), but this makes it more difficult for those folks trying to implement the specification. (eg. If to_teams_ids is not null, then ignore to_team_id)

I created a branch on my fork: John's branch on his fork that has proposed changes to the Current CLICS Clarifications section section.

Note: A judge's announcement is when reply_to_id and from_team_id are both null.

[deboer-tim]

FWIW I'd just create the PR here. You can make it draft state if you aren't proposing to merge it yet, but makes it slightly easier to review.

It's not clear to me when you send to a group if the team ids would be null, or must be the list of teams in that group.

As pointed out in 2 we likely already use 'clarifications' for things that aren't strictly clarifications. I'm wondering if this is a sign we should make them even more generic or try to cover more types of messages between users.

Or thinking wider (beyond the scope of this issue): should there be a category to help organize for A2Q, or allow teams to ask sysops vs judging questions? Should contest_time be optional in order to allow questions immediately after a contest or during open practice?

[johnbrvc]

It's not clear to me when you send to a group if the team ids would be null, or must be the list of teams in that group.

Either list or both may have things in them. The union of all teams in the teamsId array and the teams belonging to the groups in the groups list would receive the message. eg. team ids: 54, 104, 114 and groups: "North East" and "East Central". teams do not have to be in one of the groups.

[deboer-tim]

It's not clear to me when you send to a group if the team ids would be null, or must be the list of teams in that group.

Either list or both may have things in them. The union of all teams in the teamsId array and the teams belonging to the groups in the groups list would receive the message. eg. team ids: 54, 104, 114 and groups: "North East" and "East Central". teams do not have to be in one of the groups.

I'm fine with this approach (and even if a team is listed and in a group), but I think the spec needs be explicit to ensure everything is interoperable.

[niemela]

Should contest_time be optional in order to allow questions immediately after a contest or during open practice?

Slightly related: I don't we specify anywhere that contest_time must be strictly within [0, duration], but I think we all think that it must (?), at least it's implied by this question.

[niemela]

This is a breaking change since the to_team_id property would be changed to to_team_ids and it would be an array of ID's. I suppose it may be possible to leave to_team_id and add to_team_ids (as well as to_group_ids), but this makes it more difficult for those folks trying to implement the specification. (eg. If to_teams_ids is not null, then ignore to_team_id)

Using your suggested semantics (that the recipient is the union of what's listed in to_teams_ids and to_group_ids) and expanding it to include to_team_id in the union, you would not have to ignore to_team_id.

[nickygerritsen]

Should contest_time be optional in order to allow questions immediately after a contest or during open practice?

Slightly related: I don't we specify anywhere that contest_time must be strictly within [0, duration], but I think we all think that it must (?), at least it's implied by this question.

We (DOMjudge) often have people sending clarifications before the contest started as a pre-announcement. I think currently we (again DOMjudge) set a negative contest time (which might be a lie if you pause and resume the countdown).

[niemela]

We discussed this at today's meeting. The general feeling was that this is a good change. @johnbrvc will update his draft based on the discussions and create a PR.

[johnbrvc]

This is a breaking change since the to_team_id property would be changed to to_team_ids and it would be an array of ID's. I suppose it may be possible to leave to_team_id and add to_team_ids (as well as to_group_ids), but this makes it more difficult for those folks trying to implement the specification. (eg. If to_teams_ids is not null, then ignore to_team_id)

Using your suggested semantics (that the recipient is the union of what's listed in to_teams_ids and to_group_ids) and expanding it to include to_team_id in the union, you would not have to ignore to_team_id.

I think that keeping to_team_id is probably not a good idea from a client perspective. For example, consider a client that only expects to_team_id (and not implement the optional to_team_ids and/or to_group_ids). If only to_team_ids (or to_group_ids) is populated by the API server (CCS or CDS for example), a client who does a GET on the clarifications EP would receive a null back for to_team_id, leading the client to believe it was a "send to everybody", when in fact, it is not. I think we make this a breaking change and do away with to_team_id.

[johnbrvc]

Should contest_time be optional in order to allow questions immediately after a contest or during open practice?

Slightly related: I don't we specify anywhere that contest_time must be strictly within [0, duration], but I think we all think that it must (?), at least it's implied by this question.

We (DOMjudge) often have people sending clarifications before the contest started as a pre-announcement. I think currently we (again DOMjudge) set a negative contest time (which might be a lie if you pause and resume the countdown).

In fact, one of the examples in the specification does exactly this, that is, specifies a negative contest_time.