Allow multiple teams and groups in clarification destinations #193

johnbrvc · 2025-01-31T13:51:36Z

Removed the to_team_id property from the clarifications object, and replaced it with to_team_ids and to_groups_ids. This allows a clarification response (or announcement) to be sent to multiple teams and/or groups and of course everyone.

Added a description of how the new properties work.

Changed the clarification examples to reflect the new properties.

Changed Filtering example to use to_team_ids since it previously used to_team_id.

This is a "breaking change" in that clients and servers that expect the to_team_id property for clarifications will no longer work properly until they are updated to use the new property(ies).

Instead of allowing only a single team or all teams to receive the reply to clarification (or an announcement from the admin or judges), allow multiple teams and/or groups to receive the reply/announcement. There are several use cases for this: 1) teams that are located in a specific area of the floor or a different room. Q:"Where are our printouts?" Reply: "There is a problem with the printer in your area, and it will be fixed shortly" 2) a group in a specific region: Q:"Why arent we getting balloons?" Reply to group: "The balloon printer in your region is out of paper and it is being fixed"

The description of the restrictions on from_team_id and to_team_ids and to_groups_ids was (is still?) ambiguous. Maybe still need better wording.

Indicate that the recipient list is the UNION of the to_team_ids and to_group_ids. Fix examples to use new properties. Fix up some awkward wording.

The filtering example happened to use to_team_id for clarifications as an example. This has to change to to_team_ids. Also changed the example to include multiple teams

nickygerritsen · 2025-01-31T15:03:25Z

Contest_API.md

+| id             | ID               | Identifier of the clarification.
+| from\_team\_id | ID ?             | Identifier of the [team](#teams) sending this clarification request, `null` iff a clarification is sent by the jury.
+| to\_team\_ids  | array of ID ?    | Identifiers of the [team(s)](#teams) receiving this reply, `null` iff a reply to all teams or a request sent by a team.
+| to\_group\_ids | array of ID ?    | Identifiers of the [ group(s)](#groups) receiving this reply, `null` iff a reply to all teams or a request sent by a team.


Suggested change

| to\_group\_ids | array of ID ? | Identifiers of the [ group(s)](#groups) receiving this reply, `null` iff a reply to all teams or a request sent by a team.

| to\_group\_ids | array of ID ? | Identifiers of the [group(s)](#groups) receiving this reply, `null` iff a reply to all teams or a request sent by a team.

Contest_API.md

eldering

Should it be allowed to specify team and group IDs that overlap? That is, a team that's also already part of a group?

eldering · 2025-02-01T10:15:11Z

Contest_API.md

-recipient by passing `to_team_id=X`. To filter on a `null` value,
-pass an empty string, i.e. `to_team_id=`. It must be possible to
+recipient by passing `to_team_ids=X,Y`. To filter on a `null` value,
+pass an empty string, i.e. `to_team_ids=`. It must be possible to


This suggests a real change: instead of just requiring filtering on properies with ID type, we would now also require filtering on properties with type array of ID.

That adds a bunch of extra complexity like: if you specify to_team_ids=X,Y, do you want to match entries where to_team_ids is exactly [X,Y], contains either X or Y, has [X,Y] as a subset, or... I don't think we should go there, and simply change this example to something else than clarifications.

The "OR" of all the to_team_ids (or to_group_ds) makes the most sense. eg. "Any of these teams"

I don't think we should go there, and simply change this example to something else than clarifications.

I agree, we should not add the requirement that you allow filtering on any property of type array of ID.

On a related note, when we say "any property with type ID" do we mean to include properties of type ID ?. We should clarify.

Discussed at meeting. We will not introduce filter on arrays as part of this change, but might later.

Contest_API.md

eldering · 2025-02-01T10:41:30Z

Contest_API.md

  "text":"May I ask a question?","time":"2017-06-25T11:59:27.543+01","contest_time":"1:59:27.543"},
- {"id":"2","from_team_id":null,"to_team_id":"34","reply_to_id":"1","problem_id":null,
+ {"id":"2","from_team_id":null,"to_team_ids":["34"],"reply_to_id":"1","problem_id":null,


Would be good to have an example where there are multiple team IDs and/or a group ID.

Agree. Will update.

Updated an example to include 3 team ids and a group id in a response.

johnbrvc · 2025-02-01T15:06:46Z

Should it be allowed to specify team and group IDs that overlap? That is, a team that's also already part of a group?

I had modified the description to say: "The recipients of a clarification are the union of to_team_ids and to_group_ids." Are you suggesting, perhaps it should say: "The recipients of a clarification are the union of to_team_ids and the teams that are members of to_group_ids."

eldering · 2025-02-01T22:44:24Z

Should it be allowed to specify team and group IDs that overlap? That is, a team that's also already part of a group?

I had modified the description to say: "The recipients of a clarification are the union of to_team_ids and to_group_ids." Are you suggesting, perhaps it should say: "The recipients of a clarification are the union of to_team_ids and the teams that are members of to_group_ids."

I think that's a better formulation that would be good to change. But it's not what I was trying to address.

I meant the following: let's say group A contains teams X and Y. Now is it legal to specify for a clarification to_team_ids = [X,Z] and to_group_ids = [A]? That is, can a team be specified in both the team and group lists, or should we explicitly forbid this? Or maybe @niemela would argue that this is overspecifying things that no-one reasonable should do? :-P

johnbrvc · 2025-02-01T23:36:35Z

Should it be allowed to specify team and group IDs that overlap? That is, a team that's also already part of a group?

I had modified the description to say: "The recipients of a clarification are the union of to_team_ids and to_group_ids." Are you suggesting, perhaps it should say: "The recipients of a clarification are the union of to_team_ids and the teams that are members of to_group_ids."

I think that's a better formulation that would be good to change. But it's not what I was trying to address.

I meant the following: let's say group A contains teams X and Y. Now is it legal to specify for a clarification to_team_ids = [X,Z] and to_group_ids = [A]? That is, can a team be specified in both the team and group lists, or should we explicitly forbid this? Or maybe @niemela would argue that this is overspecifying things that no-one reasonable should do? :-P

I think we discussed this on the call two weeks ago. I thought we decided that by specifying it as a "union" it specifically permits you have a team in the to_team_ids as well as be a member of a specified to_group_ids - because I asked the exact question you did.

niemela · 2025-02-03T02:44:28Z

I meant the following: let's say group A contains teams X and Y. Now is it legal to specify for a clarification to_team_ids = [X,Z] and to_group_ids = [A]? That is, can a team be specified in both the team and group lists, or should we explicitly forbid this? Or maybe @niemela would argue that this is overspecifying things that no-one reasonable should do? :-P

I would indeed argue that this is overspecifying, but I don't even think it's so unreasonable. Having overlap between the sets specified by to_group_ids and the set specified by to_team_ids is very similar to having overlaps between different sets in to_group_ids, and we certainly don't want to disallow that.

niemela · 2025-02-03T02:49:27Z

Contest_API.md

-recipient by passing `to_team_id=X`. To filter on a `null` value,
-pass an empty string, i.e. `to_team_id=`. It must be possible to
+recipient by passing `to_team_ids=X,Y`. To filter on a `null` value,
+pass an empty string, i.e. `to_team_ids=`. It must be possible to


I don't think we should go there, and simply change this example to something else than clarifications.

I agree, we should not add the requirement that you allow filtering on any property of type array of ID.

On a related note, when we say "any property with type ID" do we mean to include properties of type ID ?. We should clarify.

niemela · 2025-02-03T02:56:27Z

Contest_API.md

+| id             | ID               | Identifier of the clarification.
+| from\_team\_id | ID ?             | Identifier of the [team](#teams) sending this clarification request, `null` iff a clarification is sent by the jury.
+| to\_team\_ids  | array of ID ?    | Identifiers of the [team(s)](#teams) receiving this reply, `null` iff a reply to all teams or a request sent by a team.
+| to\_group\_ids | array of ID ?    | Identifiers of the [ group(s)](#groups) receiving this reply, `null` iff a reply to all teams or a request sent by a team.


As specified right now, nulls in one (but not both) of to_team_ids and to_group_ids is either illegal (because it must be null iff reply to all), (or it requires the non-null value to actually specify all teams), or it could be interpreted as the union of something and all, i.e. all. I don't think either of those are what we want.

It should be allowed to specify only to_team_ids (i.e. having to_group_ids as null) and that should mean that only the teams listed will get the message. Similar for only to_group_ids,

Removed extra space (cosmetic). Added a couple of team ID's and a Group ID to one of the clarification examples.

Made it clear, that from_team_id, to_team_ids AND to_group_ids must be null (or empty) to send to all teams. I think that makes it clear that if either to_team_ids or to_group_ids is non-null(empty), then the message is not sent to all teams, rather, only those teams

Change to_team_id to to_team_ids and add to_group_ids

johnbrvc added 4 commits January 10, 2025 09:11

Tried to make description a bit clearer

8e78f3f

The description of the restrictions on from_team_id and to_team_ids and to_groups_ids was (is still?) ambiguous. Maybe still need better wording.

Clarify the meaning of to_team_ids and to_group_ids

83433db

Indicate that the recipient list is the UNION of the to_team_ids and to_group_ids. Fix examples to use new properties. Fix up some awkward wording.

Update Filtering description example

0f7915d

The filtering example happened to use to_team_id for clarifications as an example. This has to change to to_team_ids. Also changed the example to include multiple teams

johnbrvc added documentation Improvements or additions to documentation enhancement New feature or request labels Jan 31, 2025

johnbrvc requested review from niemela, nickygerritsen, eldering, clevengr and deboer-tim January 31, 2025 13:51

johnbrvc self-assigned this Jan 31, 2025

nickygerritsen reviewed Jan 31, 2025

View reviewed changes

eldering reviewed Feb 1, 2025

View reviewed changes

niemela requested changes Feb 3, 2025

View reviewed changes

johnbrvc added 4 commits February 3, 2025 13:19

Changed an example for clars

b79b203

Removed extra space (cosmetic). Added a couple of team ID's and a Group ID to one of the clarification examples.

Added to_group_ids to clarifications access restrictions

56eea49

Change to_team_id to to_team_ids and add to_group_ids

More consistent wording for clarifications

b724def

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Allow multiple teams and groups in clarification destinations #193

Allow multiple teams and groups in clarification destinations #193

johnbrvc commented Jan 31, 2025

nickygerritsen Jan 31, 2025

johnbrvc Feb 3, 2025

eldering left a comment

eldering Feb 1, 2025

johnbrvc Feb 1, 2025

niemela Feb 3, 2025

niemela Feb 3, 2025

eldering Feb 1, 2025

johnbrvc Feb 1, 2025

johnbrvc Feb 3, 2025

johnbrvc commented Feb 1, 2025

eldering commented Feb 1, 2025

johnbrvc commented Feb 1, 2025

niemela commented Feb 3, 2025

niemela Feb 3, 2025

niemela Feb 3, 2025

	\| to\_group\_ids \| array of ID ? \| Identifiers of the [ group(s)](#groups) receiving this reply, `null` iff a reply to all teams or a request sent by a team.
	\| to\_group\_ids \| array of ID ? \| Identifiers of the [group(s)](#groups) receiving this reply, `null` iff a reply to all teams or a request sent by a team.

Allow multiple teams and groups in clarification destinations #193

Are you sure you want to change the base?

Allow multiple teams and groups in clarification destinations #193

Conversation

johnbrvc commented Jan 31, 2025

Choose a reason for hiding this comment

Choose a reason for hiding this comment

eldering left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

johnbrvc commented Feb 1, 2025

eldering commented Feb 1, 2025

johnbrvc commented Feb 1, 2025

niemela commented Feb 3, 2025

Choose a reason for hiding this comment

Choose a reason for hiding this comment