w3c/tpac-breakouts

Documentation and Management of TPAC plenary day breakouts

TPAC breakout sessions management

About this Repository

This repository contains:

1. a set of generic tools used to organize breakout sessions during W3C TPAC events,
2. documentation about tooling for breakout sessions planners,
3. good practices for breakout session chairs, and
4. TPAC breakout session policies.

This repository does not contain breakout session proposals. To see breakout session proposals, please check dedicated repositories per TPAC, such as TPAC 2023 Breakouts.

Documentation

This repository includes documentation for TPAC participants:

• Good Practices for Session Chairs
• TPAC Breakout Policies

There is also documentation for TPAC meeting planners.

Tools

This repository includes tools to:

• Validate a breakout session proposal, chair info and schedule data.
• Suggest, save and restore a schedule that minimizes conflicts.
• Initialize IRC channels with bots and agenda.
• Update the TPAC breakout sessions calendar.
• Update session data with links to IRC-based minutes when available.
• Create recording pages with transcripts.
• Gather a list of session chairs.

The tools are specific to TPAC events. Some of them require W3C team privileges.

About the Issues List

Please use the issues list of this repo for general questions or suggestions about TPAC breakout management and tools.

Please do not use the issues list of this repo to propose TPAC breakout sessions.

Historical note

This repository was originally used to help organize tooling for TPAC 2019 breakout session management.

tpac-breakouts's Issues

Any way to configure IRC bots based on channel data in GitHub?

Each session will have an IRC channel name (provided or generated). The morning of the meeting, can we automatically configure the bots on irc.w3.org based on this data?

Warn if minutes are not stored on origin with strong persistence policy

I am for the moment going to assume that minutes stored on w3.org (e.g., from IRC) or GitHub are sufficiently persistent.

I propose that we include a warning when a minutes link does not include one of those origins.

Display chairs in calendar summary

Discussed in Strat.

Establish and document conventions for meeting deliverables in markdown

Can we add a section automatically to the issue template that is pre-filled with markdown needed for links to minutes, slides, etc.?

No calendar setting for sessions "restricted to TPAC participants"

Breakout sessions may be restricted to TPAC participants, but there is no way to restrict showing the join information to TPAC participants in calendar entries. The closest setting is "People invited to the event and holders of a W3C account with Member access", but there are non-member people who may be TPAC participants (e.g., people participating in a CG that meets at TPAC).

Systems team says: "we could add the ACL next year" (no UI change needed, calendar events are already linked to TPAC through the notion of "Big Event")

Contact information for all session chairs?

We send several messages before and after TPAC to "session chairs." It would be handy to have a (team-visible) list email addresses of all session chairs (ideally both those proposing the session and those named as co-chairs).

Add "check: irc channel" label when channel was generated

Code that generates the IRC channel if not provided does it silently for now. We probably want to review generated IRC channel names: they will likely end up being too long. A check: irc channel label would allow to distinguish proposals for which the IRC channel name was generated.

Case-sensitivity important to GitHub identity in mapping to W3C identity?

In one issue, a co-chair was identified using a GitHub identity with @CamelCase. I mapped that to a W3C identity and the validation failed to find the W3C identity. I surmised that the Github identity needed to be lowercase, and when I changed the mapping that worked.

Is a GitHub id case-sensitive? If not, could we ignore case when validating the mapping?

Suggest that people add emojis to issue descriptions to gauge level of interest

Via @sideshowbarker: "As a way to gauge the level of interest in each session proposal, would it be good to suggest somewhere that people add emojis to the issue descriptions?"

This could be broadened to issue comments: one of the arguments for switching to GitHub was that it facilitated preliminary discussions on proposals. I don't think that we encourage such discussions anywhere.

Drop Agenda link?

Our experience from TPAC 2023 suggests that the agenda link may not be very useful, and may be a common source of formatting errors. Should the "agenda" link be dropped?

Add mechanism to remove issue author from the list of session chairs

Current assumption is that all session proposal authors will chair their session. While this should remain an exception to the rule, there may be a couple of proposals for which the proposer just proxies someone else. One such example is w3c/tpac2023-breakouts#12

IRC: one session at a time!

The IRC commands run in parallel right now, with the bot joining all IRC channels at once. This makes the IRC server reject commands after some time with "You have joined too many channels".

Sessions should really processed one after the other: join, run commands, leave.

Load Zoom room calendar with session-specific titles

We expect to have a fixed number of all-day room-specific "Zoom Rooms". But for each individual session, the title should appear on the equipment in the room (and the name of the meeting will appear to zoom participants). We will needs to work with @swickr on this.

Document repo secrets and variables

New secrets and variables are needed on the repository for jobs to run. Today, they are documented in the job files, e.g., in update-calendar.yml

These should be documented with examples and perhaps screenshots in Setting up the breakouts repo.

style for columns

Via Amelia:

Can someone add a little CSS to the giant table on https://w3c.github.io/tpac-breakouts/sessions.html so that it scrolls when it can't fit on the screen, instead of squishing down the column widths until all the text overlaps?

.wide { overflow: auto; }
.breakouts { width: auto; }

Should Project be in private repo?

At first we thought the Project might be useful during the development of the schedule, and thus we made it public. That turned out to be unnecessary. Should we put the Project in a private repo (and use it to store all the private data)?

Warn if two sessions with same chair scheduled at same time

If two simultaneously scheduled sessions have a common chair.

Tool to extract session chair contact information

For communications before and after TPAC with session chairs, it would be handy to be able to extract the contact information for email.

Checklist for copying info to a new TPAC repo

(As we make changes to the repo, document them here.)

Ian to start with instructions

Warn if two sessions in track scheduled in different rooms at same time

Where to collect breakout session proposals

Proposals for breakout sessions have been collected through a Wiki page (e.g. the one for 2022). This issue looks at main pros and cons of different mechanisms which could be used to create a single source of truth that could ideally be processed automatically.

Collect proposals on a Wiki page

Pros:

• Easy to edit a Wiki page.
• All proposals are visible at once.
• Easy to adjust the template and perform a search+replace across proposals to reflect changes as needed.
• Easy to track updates and rollback to a previous state if needed.
• Through manual interventions to curate the list of proposals on a regular basis, it's relatively easy to create a tool that converts the list of proposals to a structured list that follows some JSON format.
• We're used to that approach already.

Cons:

• Currently requires manual processing to convert the list to a JSON structure that can then be validated and reused, e.g. to enter the grid. That manual processing is error prone, especially because...
• Easy for people not to follow the provided template, or to be creative, starting with the list of proposers (with or without email, with or without "and", etc.). This requires more manual interventions to fix the proposal so that it may be converted to other formats (notably HTML).
• No clean separation between fields that are up to proposers and fields that are to maintained by organizers, such as annotations to set the breakout room and slot.
• "This wiki is restricted to members of one or several W3C groups". It may not be that easy for everyone to edit a Wiki page.

Collect proposals as GitHub issues

Pros:

• GitHub's form schema could be used to impose the session template upon submission.
• Relatively easy to view all proposals at once, by listing open GitHub issues (which could be flagged with a proposal label)
• Useful to gather comments on proposals, point proposers to related proposals, suggest changes, etc.
• Easy to use labels to annotate proposals for organizers (e.g. track, room, slot, approval).
• Relatively easy to create automated jobs that run whenever an issue is updated to validate the proposal, possibly flag it as invalid, convert it to JSON, etc.
• W3C's calendaring system uses GitHub Flavoured Markdown already, no conversion needed for structured info.

Cons:

• GitHub's form schema is fairly limited. There are no provisions for arrays for instance, which could typically be used to tell proposers apart.
• GitHub's form schema is fairly limited (bis). Once the issue has been created, the proposer may further edit it in place, which is both good to update the info it contains, and bad because these edits are unconstrained (the initial form no longer gets used). Once that happens, we're back to the same issue as with Wiki: manual intervention from organizers is required to fix (reporting validation errors automatically could be envisioned, but that seems heavy at first sight, and not very welcoming feedback for newcomers willing to propose a session).
• Above point means that, in practice, automation may often break when proposers update their proposal. We're back to the same problem as with the Wiki.
• Validation jobs will often break with annotations too. For instance, to swap proposals between rooms, an organizer will typically (1) remove the first room label from the first session, (2) add the second room label to the first session, (3) remove the second room label from the second session and then (4) add the first room label from the second session. If jobs run after each update, validation will fail after (2), because the update creates a temporary scheduling conflict (two sessions at the same time in the same room).
• Requires a GitHub account. Basically all groups use GitHub nowadays, so that shouldn't be too much of a burden.

Collect proposals through WBS

Pros:

• Easy to constrain the fields, even for updates
• Integrated with W3C users database

Cons:

• Still no support for arrays
• WBS forms are per proposer, not per idea. One proposer can only submit one proposal.
• Not sure how to automate retrieval of WBS results in practice, but that should be doable :)

Collect proposals through some custom web app

Pros:

• Easy to create the right HTML form and get structured results right away

Cons:

• Hard to integrate with some login mechanism to identify proposers and allow them to update their proposals after submission in particular.
• Hard to integrate features such as history tracking or comments on proposals. Or rather, it's easy to end up with a long list of features that seem easy on paper but would require dev resources that we don't have.
• Requires deploying the logic somewhere.

Tools/Jobs to automate grid creation from GitHub issues

This is meta-issue to track progress on command-line tools and jobs that are needed to semi-automate the creation of a breakout session grid, materialized through calendar entries in the relevant W3C calendar.

• Issue creation form template
• Logic to validate a session proposal
  • Validate proposal body format and manage "error: format" label accordingly
  • Validate capacity preference and manage "warning: capacity" label accordingly
  • Validate duration preference and manage "warning: duration" label accordingly
  • Validate conflicts and manage "warning: conflicts" label accordingly.
    Note: requires looking into other issues, and could perhaps rather be done when the grid gets validated
  • Validate session chairs and manage "warning: chairs" label accordingly (see #18)
    Note: requires hooking into the W3C API to retrieve W3C account information
• Job to validate a session proposal whenever it gets created, edited, labeled, re-opened
  • Check presence of comments and manage "check: comments" label accordingly
  • Add issue to the breakout session project upon creation or when a session label is added
  • Run logic to validate the session proposal
• #30
• CLI to propose and possibly apply a grid for the existing sessions.
• Manual job based on the previous CLI to set room and slot labels on issues accordingly
  • Figure out the incremental story, e.g., possibility to add a session to an existing grid without altering it, possibility to minimize changes, possibility to re-create the grid from scratch
• Manual job to validate the grid
  • #28 (not really needed in practice)
  • For each session, run logic to validate the session proposal
• CLI to generate the right set of commands to send to the W3C calendar endpoint
  • Retrieve information about session chairs from the W3C API
  • Format all calendar entry properties based on the info provided on GitHub
  • Retrieve existing breakout session entries from the calendar for incremental update purpose
  • Manage Zoom meeting info based on room name (see #17)
• CLI based on the previous one to update the W3C calendar
  • For each session issue, manage link to the underlying calendar entry
• Manual job based on previous CLI to update the W3C calendar
  • Figure out authentication needs

What session state management do we need?

The question of "tentative sessions" came up. Although we might need a more sophisticated set of session states, I propose the following:

• If a proponent wants a session to be included, they raise and issue and leave it open. We will treat all open issues that represent session proposals as "to be included."
• If, at any time, a proponent changes their mind, they simply close the issue.

Need tools to ease/automate copying of slides and minutes to w3.org

Post-TPAC, we need to collect slides and minutes, and ideally move them to w3.org for persistence.

Minutes taken on IRC are already under w3.org.

When Google documents are used for slides and minutes, it should be relatively easy to:

1. Create a PDF version of the document using Puppeteer
2. Add the PDF to CVS
3. Set appropriate ACLs on the created document (or make sure that the default ACL of the folder that will contain the documents is public)
4. Adjust the session descriptions accordingly

Note the tool would be useful in a broader context: it is common for someone to present slides during a group meeting, which always requires a little manual dance to collect a standalone version of the slides, publish it under w3.org and update links to target the published version.

Add floor information to room names

Meeting planner guidance: "It would be good to record the room floors indeed, in order for people to save some time finding their rooms."

Fail if "check: comments" labels remain

Replace inline tabs with spaces in calendar entries

People may use tabs in the session description in GitHub, which get turned into blockquotes when the calendar entries are ingested in the schedule page. The update-calendar script should replace tabs with spaces to avoid that.

Add track labels to calendar entry

The tool that converts session proposals to calendar entries does not yet do anything with track labels. It should report the tracks in a "Track(s)" section in the agenda description.

Borked links

https://validator.w3.org/checklink?url=https://w3c.github.io/tpac-breakouts/sessions.html
28 borked links (sponsor logos at the bottom of page mainly, but links to other TPAC pages as well)

1 Broken fragment:
https://w3c.github.io/tpac-breakouts/sessions.html#slot6 (line 473)

Detect conflicting IRC channels

No two sessions should use the same IRC channel. We should add a check and a new error: irc conflict label when that happens.

Labels as validation signals to meeting planners are a source of confusion

We now have experience that when validation tools use labels to communicate information to meeting planners, that is creating confusion for session chairs.

@tidoust has mentioned variables as an alternative.

I expect we'll revisit this topic for TPAC 2024.

Tools to process recordings (clipping, upload to streaming service)

For a given room, will same Zoom info be reused all day long?

If this is the case, we can do more to ensure that the calendar has the proper zoom information even when a session changes room. I will document the meeting planner's response to this question here.

Use more neutral mechanism to remove issue author from the list of session chairs

Mechanism introduced in #39 uses author-- to say "issue author is not to be listed as session chairs". That works, but author-- could perhaps also be read as a negative evaluation of the author, which is obviously not intended. Something like -author would be more neutral.

Manage when issues close after scheduling has begun

Per @tidoust:

What's missing is a job triggered when an issue is closed that:

• removes the session from the project
• cancels the calendar entry
• removes references to the issue in the conflict section of other issues
• re-validates sessions that got updated (if there was a real conflict due to the now closed issue, this conflict should be gone)

Update issue with shortname right after creation

When it is not povided, the shortname is automatically generated on the fly from the session's title. To make sure that it looks good enough, the shortname should rather be added to the issue's body after validation.

Consider creating a job to remove a session from the project automatically when it gets closed

This should be low priority.

Set up buddy program for first-time facilitators

To make it easier for newcomers to propose and run breakouts, it would be nice to set up some sort of buddy program where someone who hasn't done this before could be paired with someone with more experience among a pool of volunteers. This could also help balancing the chairing/presenting tasks for people running a session on their own.

(I would suggest the buddy be offered and identified early in the proposal lifecycle, so they can offer assistance in the preparation phase, not just to run the session)

No direct notification of issue edits

Session chairs (or breakout meeting organizers) may update proposal descriptions at any time. As opposed to new comments in an issue, these edits do not seem to trigger any notification. This is problematic because that means we don't know when a calendar entry needs to be updated. This does trigger the validation session job though, so one can look at the job execution history to tell which proposals got updated. A more direct notification mechanism would be good.

Possible solutions:

1. Add some notification mechanism to the job that validates session; or
2. Update and run the job that updates the calendar entry automatically upon description edits. Update required includes not creating the calendar entry until we started doing it, and figure out a way to tell which status the calendar entry should have (draft, tentative or confirmed)

IRC: channel operator rights

When the bot creates the IRC channel, it gains channel operator rights. When it leaves, no one has channel operator rights by default. This means that no one can change the topic.

IRC: check responses from bots

In some channels, RRSAgent does not seem to have acknowledged the commands that it received. It would seem a good idea to look for these acks and re-issue commands if they don't appear.

Make clearer (via template) how to manage minutes, slides, cal links

We needed to fix numerous session descriptions around agenda/slides/minutes links. Let's generate better instructions to help people understand how to manage that info.

Email improvements

• Add overall expected calendar of events: (1) desired deadline for submissions (2) when schedule will be available. (At least in most emails)

Define breakout session

Manage expectations by defining what is expected for a breakout session and what might be considered out of scope. Examples:

• Breakout sessions are for community discussion. They are not intended as group meetings.
• Are there problematic areas, such as using a session to promote a commercial product?

Advise people not to edit calendar entry

In each generated calendar entry, include a link to the session description. Ask people not to edit the calendar entry (e.g., to add the agenda URL) but instead add discussion to the GitHub issue.

Session chairs in "Additional individual attendees" in calendar entries

The job that updates calendar entries uses the "Additional individual attendees" field to list session chairs so that they appear somewhere. When it updates calendar entries, it resets that field.

Problem is this field lists all people who subscribe to the event, so resetting the field actually unsubscribes these people.

Ideally, session chairs should rather be listed as organizers, but organizers can update the calendar entries, which is what we were trying to avoid.

Job could continue to use the "Additional individual attendees" field, but should no longer reset the field. This creates another problem though: If the list of chairs changes, the job will fail to remove chairs who were removed from the entry. That should not happen and should not be a big deal though!

[Policy] Are there requirements related to minutes?

• Do minutes have to be public?
• Does there need to be a copy of minutes on w3.org?

Create tool/job to add links to IRC minutes

How can we record zoom information so that it is not publicly shared?

In theory, the best place is the calendar entry, but may raise issues.

Document tools and jobs