For TPAC Meeting Planners

Principles

The tools in this repository can be used to organize:

• multi-day group meetings during W3C TPAC events; or
• single-day breakout sessions during W3C breakouts events.

At a high level, the tools support the following flow:

• Proposals for meetings from the community.
• Validation of the information provided in these proposals.
• Scheduling of all those proposed meetings, assigning them to rooms/dates/time slots, doing a "best fit" between the preferences of the proponents and available resources (e.g., available rooms and their capacities). The tool supports both "automatic scheduling" mode and manual overrides.
• Pushing the resulting schedule to a W3C calendar. In this phase, multiple adjacent session slots are combined into a single calendar entry. Typically, other resources (e.g., grid view on the event site) are derived from the calendar (but are not directly part of this system).

The general idea is to create a dedicated GitHub repository and a GitHub project per event. For W3C TPAC events, the purpose of the GitHub repository is to gather the list of groups that will meet. For W3C breakouts events, the purpose of the GitHub repository is to gather the list of breakout session proposals. In both cases, the list is managed as a set of open issues in the repository, to allow proposers and organizers to adjust things as needed over time, and encourage discussions.

On top of issues, the GitHub repository will contain:

1. an issue template that provides the issue form for people who create issues;
2. a series of jobs to automate (or semi-automate) event management;
3. a README to set expectations.

The GitHub repository will not contain actual code, the jobs directly reference the w3c/tpac-breakouts repository to access the tools.

The jobs are used to validate group meetings (group names, requested times, room capacity) or breakout session proposals (topics, description format, constraints, preferences), suggest a schedule, synchronize the list of group meetings and sessions with an underlying W3C calendar, setup IRC bots, etc. The jobs are for meeting planners.

The jobs run in the name of the W3C TPAC Breakout sessions bot (@tpac-breakout-bot). That is on purpose, to make it clear that possible updates were made through some automated process.

The GitHub project is used to assign data (what GitHub calls fields) to GitHub repository issues. Through the GitHub project, meeting planners can assign and manage rooms, days, and slots to group meetings and session proposals, visualize validation issues, and take a peak at the resulting schedule grid.

Note

A breakouts event may be associated with a W3C TPAC event but, as far as the tools are concerned, both events need to be organized separately (one repository and one project for each of them).

Organization topics

The organization of W3C TPAC events is out of scope for this documentation. For W3C breakouts events, the following considerations are based on our experience with organizing such events in 2023 and 2024:

• Early Prep
  • Define/Refine policies (deadlines, late proposal policy, hybrid, public, no zoom links made public to avoid zoom-bombing, registration policy, fee policy)
  • Find volunteers to be session buddies for first time chairs (possibly starting from last year's pool of chairs).
  • Work with the systems team to create a breakout sessions in W3C Calendar for this year's TPAC (should appear under https://www.w3.org/calendar/tpacYYYY/breakout-sessions/ with YYYY the current year)
  • Create the GitHub repo and project for this year's TPAC.
• Three months before TPAC:
  • Gather sessions
  • Train session organizers (chairing, tools, accessibility)
  • Strategy Team (or CG) should work so that hot topics are surfaced at TPAC.
• Close to TPAC:
  • Schedule sessions (rooms and sizes, slot lengths, tagging for themes, timing constraints, avoiding conflicts, mergers, ...)
  • Socialize breakouts to reach full w3c community (slack events channel? social media?)
  • Socialize draft schedule with staff to perceive any conflicts; ask them to sign up for sessions.
• During TPAC:
  • Last-minute management of sessions (scheduling or room changes)
  • Help those running sessions (IRC or other, minutes)
  • Strategy Team (or CG) should be aware of breakouts and attend critical ones.
• After TPAC:
  • Communicate (get feedback, gather minutes, "next steps" as GitHub discussion)
  • Strategy Team (or CG) should review breakouts
  • Publish any recordings
• Throughout:
  • Collaborate with meeting planners (space, communications)
  • Maintain tools (IRC bots, calendar)

Calendar and Communications

• For sample calendar, see TPAC 2023 breakouts planners calendar
• For sample communications, see TPAC 2023 breakouts communications

Setting up the GitHub repository and project for the event

Create the GitHub project

Create the project

• Go to the list of W3C projects
• Click on the "New project" button
• Set a project name. The type of project does not matter much. A "Table" project is fine. Naming suggestions: TPAC YYYY meetings, TPAC YYYY breakout sessions or Breakouts Day YYYY, with YYYY the current year, depending on the event being organized.

Adjust project settings

• Go to the project's settings through the hamburger menu icon on the right.
• Edit the project's short description as described below. This information is used by tools.
• Consider making the project public through the "Danger zone". That is not mandatory. Experience suggests that proposers do not really like to see internals, especially if these internals include validation errors and warnings.
• Under "Manage access", give @tpac-breakout-bot write access to the project.
• Add a new Room field through the "+ New field" button, field type "Single select". List room names as options. The list of rooms can be provided or adjusted later on. For obvious reasons, rooms must be known before attempting to create a schedule grid.
• Add a new Day field through the "+ New field" button, field type "Single select". List event days as options, following the format Day (YYYY-MM-DD) or simply YYYY-MM-DD, e.g., Monday (2023-09-11). The list of days can also be provided or adjusted later on. As for rooms, days must be known before attempting to create a schedule grid. For a TPAC breakouts day or other single-day events, the list will contain only one option!
• Add a new Slot field through the "+ New field" button, field type "Single select". List TPAC breakout session slots as options, following the format HH:mm - HH:mm, e.g., 11:00 - 12:00. Duration of the slot will be computed automatically. The list of slots can also be provided or adjusted later on. As for rooms and days, slots must be known before attempting to create a schedule grid.
• If the sessions can be scheduled more than once during the event, add a new Meeting field through the "+ New field" button, field type "Text". That is typically needed for meetings at TPAC as groups may meet over a two-day period that spans multiple slots.
• If the sessions can be scheduled more than once during the event, add a new Try me out field through the "+ New field" button, field type "Text". That field will make it easier to try schedule changes.
• Add a new Error field through the "+ New field" button, field type "Text".
• Add a new Warning field through the "+ New field" button, field type "Text".
• Add a new Check field through the "+ New field" button, field type "Text".
• Add a new Note field through the "+ New field" button, field type "Text".

Create views

Views are not mandatory but are useful to manually adjust the schedule and to keep track of validation errors and warnings. Additionally, for breakouts events, the "By room" and "By slot" views can prove useful to take a peak at the current schedule. There is unfortunately no way to visualize the current schedule from project views for group meetings. You will have to use the View current schedule job instead.

To start with, rename the default view Flat list and make sure its layout is "Table". Adjust column headings:

• For a single-day breakouts event, show Title, Labels, Room, Day, Slot, Error, Warning, Check, Note.
• For multi-day group meetings, show Title, Labels, Room, Meeting, Try me out, Error, Warning, Check, Note.

Tip

You may use the "Duplicate view" option from the "View options" menu of the Flat list view to speed up the creation of the following "Table" views.

Create additional "Table" views:

• Create an Errors view
  • Under "Configuration", set "Group by" to be "Error"
  • Adjust column headings as for the Flat list view
• Create a Warnings view
  • Under "Configuration", set "Group by" to be "Warning"
  • Adjust column headings as for the Flat list view
• Create a Checks view
  • Under "Configuration", set "Group by" to be "Check"
  • Adjust column headings as for the Flat list view
• Create a Notes view
  • Under "Configuration", set "Sort by" to be "Note"
  • Adjust column headings as for the Flat list view

Important

Be sure to "Save" views as you create them!

For a breakouts event, you may also create the following views:

• Create a By room view
  • Make sure layout is "Board"
  • Under "Configuration", set "Column by" to be Room. Sort by Slot
  • Make Labels a visible field; unselect Room
• Create a By slot view
  • Make sure layout is "Board"
  • Under "Configuration", set "Column by" to be Slot. Sort by Room
  • Make Labels a visible field; select Room and Labels

The "By room" and "By slot" views are only partially editable. Due to GitHub:

• In the "By room" view, you can move sessions from room to room, but you cannot reorder the slot times.
• In the "By slot" view, you can move sessions from slot to slot, but you cannot change the room.

Short description

The project's short description can be updated through the project's Settings page. We're using the description to set useful project's metadata that tools need. The description must be a comma separated list of key/value pairs. Possible keys are:

• meeting (required): the name of the "Big meeting" linked to the event in the W3C calendar, typically "TPAC YYYY" for TPAC events. For example, see "Big meeting" in the calendar entry associated with one of TPAC 2023 breakout sessions. If there is no "Big meeting" for the event in the W3C calendar yet, get in touch with the Systems team. You may enter a temporary value in the meantime, but synchronization with the calendar will not work.
• timezone (required): the timezone of the event. For example, "Europe/Madrid", "America/Los_Angeles", or "Etc/UTC". See TZ identifiers for a list of possible values.
• type (optional, default value is "breakouts"): what issues represent. One of "breakouts" or "group".
• calendar (optional, default value is "no"): the status that calendar entries should have in the calendar. One of "no", "draft", "tentative" or "confirmed". The "no" value means that the code will not touch the W3C calendar at all. That is typically useful when you start gathering issues and do not yet want to propagate scheduling information to a W3C calendar.
• rooms (optional, default value is "show"): whether to set the room location (and associated Zoom information) of a meeting in calendar entries. One of "show" or "hide". Setting the value to "hide" can be useful initially if you want to propagate the overall schedule but do not want actual rooms to be known because they may still change.
• plenary room (optional, default value is "plenary"): the name of the room that can be used for plenary sessions. This is only useful for breakouts events and if you envision that there will be "plenary" sessions.
• plenary holds (optional, default value is 5): number of breakout sessions that a plenary meeting may contain.

Examples of descriptions:

• meeting: TPAC 2023, timezone: Europe/Madrid: breakouts event in Spain, calendar updates disabled
• meeting: TPAC 2024, timezone: America/Los_Angeles, type: group, calendar: confirmed: group meeting on the West Coast, calendar entries to be confirmed.
• meeting: W3C Breakouts Day 2024, timezone: Etc/UTC, calendar: tentative, rooms: hide, plenary room: Ukulele, plenary holds: 3: virtual breakouts event, tentative calendar entries without room info, plenary room name is Ukulele and can hold 3 sessions per slot.

Room names and characteristics

The list of rooms appears under the Room field in the project settings. Each room is associated with an option. Room name may be anything, e.g., Salon Ecija. Room characteristics may be provided through the option's description. The description must be a list of characteristics names and values, separated by a newline. A line may start with - or *. The name of the characteristic must be followed by :. Casing in names and spaces do not matter, and characteristic names may appear in any order.

Recognized room characteristics are:

• capacity: to set the room's capacity in number of seats. Value must be an integer.
• location: to set the room's location. Value can be any string, e.g., 2nd floor, or next to the registration desk.
• vip: boolean flag to make the room a VIP room. A VIP room appears in the schedule grid and you can assign a session or group meeting to a VIP room yourself (see How to adjust the schedule), but the scheduler never assigns any session or group meeting to a VIP room by itself. Value must be true or false.

You may set additional characteristics. The code will simply ignore them.

For example, to define a VIP room Salon Ecija with capacity 45 at the 2nd floor, set its description to:

- capacity: 45
- location: 2nd floor
- vip: true

Note

Room characteristics used to be captured in the room name itself. For example, you could also define a room whose name is Salon Ecija (45 - 2nd floor) (VIP) without a description. The code still supports this but this mechanism is deprecated. Please set characteristics using the room's description instead.

Other notes on the project

• While the project will de facto be tied to the repository, projects are at the organizational level on GitHub.
• The project's Status field serves no purpose but it cannot be removed (you may still remove the options it contains)

Create the GitHub repository

Naming suggestions:

• For a W3C TPAC event, w3c/tpacYYYY-meetings with YYYY the current year. For example, w3c/tpac2024-meetings
• For a breakouts event linked to TPAC, w3c/tpacYYYY-breakouts with YYYY the current year. For example, w3c/tpac2023-breakouts
• For a breakouts event on its own, w3c/breakouts-day-YYYY with YYYY the current year. For example, w3c/breakouts-day-2024

Give W3C TPAC Breakout sessions bot (@tpac-breakout-bot) write access to the repository through "Settings > Collaborators and teams" menu.

Copy the code to the repo

Latest version of the code should be in past year's repository. Get it from there. You should typically end up with the following structure:

• .github
  • ISSUE_TEMPLATE
    • session.yml
  • workflows
    • a bunch of .yml files
• .gitignore
• README.md
• package-lock.json
• package.json
• w3c.json

Adjust the contents of the README.md file to match the event.

Set "watch" to "All Activity" for the repo to be sure to receive comments left on issues.

Adjust the contents of the issue template (the session.yml file) to match the event, but please note that substantive changes to the issue template probably require also adjusting underlying tools.

Note: Tools are shared among breakout year repos, and the source is in the w3c/tpac-breakouts repository.

Associate project to repo

• Under the Projects tab, associate the repo to the project

Copy wiki pages

Given the small number of wiki pages, we just copied last year's pages to this year's wiki. The resources of interest are:

• Breakout time slots
• Meeting planner resources, including a calendar for breakout-related activities and drafts of communications to the community.

Setup action secrets and variables, labels

For both Secrets and Actions:

• Go to the repo "Settings"
• Under "Secrets and Variables", click on "Actions"

Secrets tab

• Ask François (@tidoust) to create a new repository secret named GRAPHQL_TOKEN, set to a valid Personal Access Token (classic version) with repo (public_repo is enough if repository is public, not if the repository is private) and project scopes, created on the @tpac-breakout-bot account. This secret is used to retrieve information from GitHub and update information on GitHub. Most jobs will fail to run without that secret.
• Unless you prefer to run the tool that uploads breakout sessions info to the W3C calendar locally, create a new repository secret named W3C_PASSWORD, set to the W3C team password of the person, identified by the W3C_LOGIN variable defined below, on behalf of which the calendar entries will be edited. This step can be done at a later time, once you start integrating with the W3C calendar.

Note: We recommend attaching the Personal Access Token to @tpac-breakout-bot, and not to your own GitHub user account, so that it is clear to session proposers that validation operations get done by a bot, and are not the result of some manual processing. The @tpac-breakout-bot account is currently managed by François (@tidoust).

Variables tab

• Create a new repository variable named PROJECT_NUMBER set to the number of the project you created. That number appears in the URL of the project's pages, e.g., https://github.com/orgs/w3c/projects/xx
• (Optional) Create a new repository variable named PROJECT_OWNER set to the name of the repository owner. Default value if this variable is not defined is w3c which should be what you need.
• Create a new repository variable named W3CID_MAP initially set to {}.
• Create a new repository variable named ROOM_ZOOM initially set to {}.
• Unless you prefer to run the tool that uploads breakout sessions info to the W3C calendar locally, create a new repository variable named W3C_LOGIN set to the W3C login of the person on behalf of which the calendar entries will be edited, e.g., fd. The W3C_PASSWORD secret must be set to the W3C password of the person identified by the W3C_LOGIN variable.

For a breakouts event, the W3CID_MAP variable is to contain the mapping between GitHub identities or names of sessions chairs and their W3C IDs, when that mapping cannot be determined automatically, typically because the person did not associate their W3C account with their GitHub identity, or because the person does not have a GitHub identity. If the person does not have a W3C account, use a -1 value (or a string) to tell the code to ignore the problem. For example:

{
  "tidoust": 41989,
  "Simone's cat": -1
}

For group meetings, the W3CID_MAP variable is to contain the mapping between group names and their W3C IDs, when that mapping cannot be determined automatically, either because the name of the group is not exactly the same as the name of the group in the W3C database (and you do not want to use the real name for some reason) or because the group is not a W3C group, such as "Web Platform Tests", "WHATWG" or "W3C Chapters and Evangelists". Use a -1 value (or a string) for the latter case. For example:

{
  "PING": 52497,
  "Web Platform Tests": -1,
  "W3C Chapters and Evangelists": "BFF"
}

You will typically need to adjust the W3CID_MAP variable over time, as new sessions or group meetings get created.

The ROOM_ZOOM variable is to contain the mapping between room names and Zoom meeting coordinates. Zoom coordinates can either be a URL, or an object with link, id and passcode properties. For example:

{
  "Ukulele": {
    "id": "111 111 1111",
    "passcode": "w3crocks",
    "link": "https://w3c.zoom.us/j/11111111111?pwd=blahblahblahblahblah"
  }
}

The ROOM_ZOOM variable can be completed closer to the event. It is used to add Zoom links to the calendar entries.

Initialize labels

Go to the list of labels for the repository you created (through "Issues > Labels") and create a session label. The session label is used to distinguish session proposals from any other issues people may raise in the repo. The session label is added via the template.

You may create labels to manage tracks. These labels must start with track: , e.g., track: media. There must be a space between the ":" and the track name.

Jobs for meeting planners

The jobs are used to validate group meetings or breakout session proposals, synchronize the information in the repository and project with the W3C calendar, setup IRC bots, etc.

Note

Job names start with [A] to signal jobs that run automatically when some event is triggered (typically when an issue is created or edited), or [M] to signal jobs that need to be manually triggered.

Validate session and update W3C calendar

The description of a breakout session or group meeting issue needs to follow a specific structure so that code can parse it. This structure is more or less enforced by the issue template, but nothing prevents proposers from further editing the issue description afterwards, and experience shows that they will do that. Proposers may also set a number of constraints (room capacity, sessions that would conflict with this one, instructions for meeting planners, etc.).

The "Validate session and update W3C calendar" job runs whenever an issue gets created or edited. As its name suggests, its name is twofolds:

1. Validate the breakout session or group meeting, reporting errors, warnings and things to check in the "Error", "Warnings" and "Check" custom project fields. This allows meeting organizers to track what needs fixing through the project's user interface. Possible values are described below.
2. Synchronize the information in the issue with the W3C calendar. That step only happens if the project's short description enables calendar synchronization (calendar key set to something else than no), if the issue does not have any validation error, and if the issue is scheduled already.

For breakouts events, upon issue creation, the job also adds a message from the bot to thank the session proposer and set expectations.

Tip

You may use the "Note" custom project field to store meeting planner notes on the session.

Errors

• chair conflict: Session scheduled at the same time as another session with an overlapping chair. Pick up another slot.
• group conflict: Session scheduled at the same time as another session with an overlapping group. Adjust the groups schedule.
• chairs: Cannot retrieve the W3C account of a session chair. Look for the chair in the W3C user database and adjust the W3CID_MAP variable accordingly.
• groups: Two possibilities: either the group(s) cannot be identified from the session title, or the group already had a dedicated issue. For the former case, look for the group in the W3C database and adjust the W3CID_MAP variable accordingly. For the latter case, close the duplicate issue and re-validate.
• conflict: One of the issues listed as a conflicting session is not a breakout session proposal. Drop it from the list.
• format: Jobs cannot parse the issue due to some formatting issue. Fix the session description, making sure that it respects the structure imposed by the issue template.
• irc: IRC channel conflicts with another session scheduled in the same time slot. Use different IRC channels.
• scheduling: Session scheduled in the same room and at the same time as another session. Error also reported for plenary meetings when they are not scheduled in the plenary room or when there are too many sessions scheduled in the same plenary meeting. Pick up another slot or another room for the session.
• meeting format: The meeting string could not be parsed as a list of meetings. Fix the string (see How to adjust the schedule for group meetings).
• meeting duplicate: The meeting string contains two meetings that are at the exact same time. Remove the duplicate.

Warnings

• capacity: Session room is smaller than requested capacity. Pick up another room if possible.
• conflict: Session scheduled at the same time as another session identified as conflicting. Pick up another slot if possible.
• duration: Session scheduled during a 30mn slot but 60mn was preferred. Pick up another slot if possible.
• minutes: No link to the minutes whereas session is past. Check with session chairs.
• minutes origin: Minutes are not stored on www.w3.org or lists.w3.org. Publish minutes on W3C's web site.
• switch: Session scheduled in two different rooms from one slot to the other (note a switch of room between days and non consecutive slots is not reported as a warning)
• track: Session scheduled at the same time as another session in the same track. Pick up another slot if possible.
• times: Session scheduled at different times than requested ones in the session description. Make sure that everyone is fine with the schedule.
• plenary: Session scheduled in parallel with a plenary meeting. Make sure that is intended.

Some warnings cannot be fixed: a session may have no minutes, there may be too many sessions in a track to avoid scheduling conflicts, there may be no room left to meet the requested capacity, etc. To tell the validation logic to stop reporting a warning, add a -warning:[value] instruction to the "Note" custom project field. For instance, to drop the "minutes" warning, add -warning:minutes to the "Note" field.

Checks

• instructions: Proposal has instructions for meeting planners. Check and remove flag once addressed.
• irc channel: IRC channel name was generated from the title. Check and remove flag once addressed.

Validate a session

This job can only be triggered manually through the "Run workflow" menu on the GitHub's repository Actions tab. It allows meeting planners to re-validate a session manually, which is useful if a scheduling conflict was fixed. You will need to provide the issue number of the session to re-validate.

Manual session validation does not synchronize the W3C calendar. Run the Update W3C calendar job to do that.

Validate all sessions

This job can only be triggered manually through the "Run workflow" menu on the GitHub's repository Actions tab. It allows meeting planners to re-validate the whole schedule, or to re-validate everything. Validation does not touch the W3C calendar. Run the Update W3C calendar job to do that.

Update W3C calendar

This job can only be triggered manually through the "Run workflow" menu on the GitHub's repository Actions tab. It allows meeting planners to synchronize the contents of the repository with the W3C calendar. Depending on the parameters provided, the job can either synchronize a specific session (identified by its nuber) or the entire list. Synchronizing the entire list may take a few minutes.

The job will typically need to run to fill the calendar in the first place once meeting planners are confident that the schedule is good enough to share.

Note

Sessions that have validation errors cannot be synchronized with the calendar.

View current schedule

This job can only be triggered manually through the "Run workflow" menu on the GitHub's repository Actions tab. It allows meeting planners to visualize the current schedule in an HTML page.

There is no direct way to create an HTML page as an output of a job on GitHub. To work around that, the job produces what GitHub calls an artifact, which is a ZIP file that contains the HTML page and that gets attached to the job run results. To download the ZIP and visualize the HTML page, click on the last run of the job and retrieve the "schedule" artifact that should appear at the end of the page.

Create a schedule

This job can only be triggered manually through the "Run workflow" menu on the GitHub's repository Actions tab. It allows meeting planners to create a schedule for the entire event. The job requires a few parameters to run:

• First parameter describes what previous meeting information the scheduling algorithm needs to preserve. This is useful when there already exists a partial schedule that you would like to complete. Default is to preserve everything.
• If the first parameter says "preserve everything", second parameter describes exceptions to the rule, sessions for which existing meetings should be discarded.
• Third parameter sets whether to suggest a schedule (default) or apply it. Applying it updates the information on GitHub. To be done with care once you're confident the schedule looks good!
• Fourth parameter can be used to set the seed that is used to shuffle the list of sessions at the beginning of the scheduling algorithm. The fourth parameter is useful to re-generate the schedule of a previous run (the seed appears in the generated HTML page).

The job reports the created schedule in an HTML page. As with the View current schedule job, there is no direct way to create an HTML page as an output of a job on GitHub, so the job produces an artifact attached to the job run results. To download the ZIP and visualize the HTML page, click on the last run of the job and retrieve the "schedule" artifact that should appear at the end of the page.

Try schedule changes

Warning

The job is currently limited to group meetings. It cannot be used to try schedule changes for breakout sessions.

This job can only be triggered manually through the "Run workflow" menu on the GitHub's repository Actions tab. It allows meeting planners to try schedule changes before applying them. This proves very useful in practice because it is very easy to introduce conflicts when adjusting a schedule).

The job will pick up meeting changes in the Try me out project field for each group meeting, replace the Meeting field with them, and validate the resulting schedule.

Before you run the job, set the Try me out fields of the group meetings that you would like to modify to a new valid list of meetings.

Warning

The job will fail if no Try me out field is set (also if the field does not exist).

The job reports the resulting schedule in an HTML page. As with the View current schedule job, there is no direct way to create an HTML page as an output of a job on GitHub, so the job produces an artifact attached to the job run results. To download the ZIP and visualize the HTML page, click on the last run of the job and retrieve the "schedule" artifact that should appear at the end of the page.

The command does not alter the data on GitHub by default but you may instruct it to apply the created schedule, which will effectively update the project's Meeting fields and reset all Try me out fields on GitHub.

Local tools for meeting planners

The good thing about jobs is that they can be triggered from the user interface on GitHub without having to install anything. No technical knowledge required! Now, some of the tools have not been turned into jobs yet, and it can sometimes be more convenient to run tools locally for immediate feedback. This section explains how to do so. No need for deep technical expertise, but a bit of familiarity with command-line interfaces, Git and Node.js probably helps.

Pre-requisites

The following tools must be installed on your computer:

• Git.
• Node.js (current LTS or a more recent version)
• The gh CLI. Make sure you're logged in, running gh auth login.

You may now clone the GitHub repository of the event to a local directory and install dependencies, through the following commands (replacing xxx with the name of the repository you created for the event):

git clone [email protected]:w3c/xxx.git
cd xxx
npm ci

Note

You do not need to clone the w3c/tpac-breakouts repository. The tools are installed as dependencies.

Next, you need to create a Personal Access Token (classic version), with repo (public_repo is enough if repository is public, not if the repository is private) and project scopes. This can be done through your profile page on GitHub (under "Settings > Developer Settings").

Save the token to a local config.json file in the directory where you cloned the repository. The file should look like:

{
    "GRAPHQL_TOKEN": "..."
}

Tools tend to evolve rapidly. To make sure that you're using the latest version of the tools, we recommend that you refresh the contents of the repository and re-install dependencies before you run the tools:

git pull origin main
npm ci

If you just pushed a change to the tools themselves and want to bump the version of the tools used by the repository yourself, you may run:

npm update
git add package-lock.json
git commit -m "Bump tools"
git push origin main

Main command-line interface

A single command-line interface (CLI) allows to perform the same actions as the jobs. Its name is tpac-breakouts. It comes with built-in usage help. To get started, run:

npx tpac-breakouts --help

The CLI exposes the following commands:

• view: to vizualize the current schedule
• schedule: to create a schedule
• validate: to validate sessions
• sync-calendar: to update the W3C calendar

Visualize the current schedule

For breakouts events, the project views ("By room", "By slot") are useful to visualize the current schedule. These views are totally useless for group meetings events though, because the schedule of a group needs to be captured in the meeting field in that case, which is an opaque string for GitHub. The view-event tool can be used to create an HTML page that contains the current schedule, and additional information about sessions.

The view-event tool is the tool run by the View current schedule job.

To run the tool and save the result to a grid.html file:

npx view-event > grid.html

Create a schedule

The schedule command creates a possible schedule grid for the event. The command reports an HTML page that contains the resulting grid and additional information about sessions. The command does not alter the data on GitHub by default but you may instruct it to apply the created grid, which will effectively update the project's data fields (Meeting, Room, Day, Slot) on GitHub.

The Create a schedule job runs the schedule command.

Internally, the command starts by randomizing the list of issues. This is done both to give equal weight to issues (no reason why first created issues would take precedence for instance) and to suggest different schedules with each and every run. The command reports the short string that was used to seed this randomizing process. To make the command deterministic and re-create the same schedule, just pass the same seed to the command.

Note

Passing the seed just guarantees that the sessions will be listed in a particular order at the beginning of the scheduling process. The created schedule may differ if other changes were made in between runs. For example, if a conflict was fixed or an additional issue created.

Some examples:

• Run npx tpac-breakouts schedule > grid.html to create a schedule locally and save the HTML page to a file.
• Run npx tpac-breakouts schedule --preserve all --except none --seed myseed to create a schedule locally with the seed myseed that preserves meetings information already assigned to session issues.
• Run npx tpac-breakouts schedule --seed myseed --apply to create a schedule with the seed myseed that preserves meetings information already assigned to session issues, and to update the session issues with the created schedule.

Test schedule changes

The schedule command may also be used to test changes that you might be tempted to make to an existing schedule. This proves very useful in practice because it is very easy to introduce conflicts when adjusting a schedule). To test changes, pass in a changes file as value of the --changes option, for example:

npx tpac-breakouts schedule --changes changes.yml

But first you need to create a suitable changes.yml file. That YAML file needs to contain the list of sessions for which you would like to change something, along with the list of changes that you would like to make. Session are identified by their issue number. Possible changes are field names followed by the new value. To reset all fields before applying the changes, add reset: all. To reset a particular field, mention it in the value the reset key. The following example changes the room and meetings of session #18, and resets all fields of session #42 and sets a couple of meetings for it.

- number: 18
  room: Bambu
  meeting:
    - Monday, 09:30
    - Monday, 11:00
- number: 42
  reset: all
  meeting:
    - Tuesday, 09:30, Ficus
    - Tuesday, 11:00, Salon Ecija

Conveniently, the HTML page generated by the view current schedule and the create a schedule jobs ends with a serialization of the grid data as YAML. You may copy-and-paste that data into a changes.yml file, optionally amend it, and provide it as input to the schedule command to re-create the grid.

The command will apply these changes to the schedule it creates, and validate and report the resulting schedule. Once you are satisfied with the changes, you may apply them (manually, using project views).

Try changes

The try-changes command exposes another mechanism to try schedule changes that is less technically involved than the --changes option of the schedule command. The command retrieves would-be schedule changes defined in the Try me out field, replaces the Meeting field with them, and validates the resulting schedule.

The Try schedule changes job runs the try-changes command.

The command reports an HTML page that contains the resulting schedule and additional information about sessions. The command does not alter the data on GitHub by default but you may instruct it to apply the created schedule, which will effectively update the project's Meeting fields and reset all Try me out fields on GitHub.

npx tpac-breakouts try-changes > grid.html

Warning

The mechanism is currently limited to group meetings. It cannot be used to try schedule changes for breakout sessions.

Validate session

The Validate a session and Validate all sessions jobs run the validate command. To run the command it, just pass the session issue number, or "all" to validate all sessions:

npx tpac-breakouts validate 61
npx tpac-breakouts validate all
npx tpac-breakouts validate all --what scheduling

Update W3C calendar

The Update W3C calendar job runs the sync-calendar command. The command allows you to synchronize the contents of the GitHub repository with the W3C calendar.

The command may synchronize a specific session, or all of them. You may also pass a calendar status (draft, tentative or confirmed) to override the project's calendar setting.

To interact with the W3C calendar, the command needs to impersonate you (or someone from the team). For that to be possible, you need to set two environment variables locally (either as real environment variables or as entries in the config.json file):

• W3C_LOGIN with your W3C login
• W3C_PASSWORD with your W3C password

Caution

Writing down your W3C password in plain text is obviously not a fantastic feature. We'll try to improve tools. In the meantime, take care of your credentials!

npx tpac-breakouts sync-calendar 61
npx tpac-breakouts sync-calendar all
npx tpac-breakouts sync-calendar 42 --status tentative
npx tpac-breakouts sync-calendar all --status confirmed

List session chairs

The list-chairs tool returns information about session chairs, including W3C IDs, and emails whenever possible. This tool is only useful for breakouts events. The tool returns private information about session chairs (email, mapping between GitHub account and W3C ID). That information is retrieved from team-only pages on the W3C web site. As with the Update W3C calendar, this means that you need to set two environment variables locally (either as real environment variables or as entries in the config.json file) so that the tool can impersonate you when it accesses the team-only pages:

• W3C_LOGIN with your W3C login
• W3C_PASSWORD with your W3C pasword

To get the list:

npx list-chairs

How to

How to use these tools overall

1. Set things up. At this stage, you should not try to enable synchronization with the W3C calendar (i.e., do not set the calendar setting in the short description): there is nothing to schedule, there is no schedule, and you would not want to publicize it in any case.
2. Collect breakouts/groups session proposals as open issues. Look for validation problems in project views and fix them (formatting problems, unknown groups or chairs, etc.).
3. Create and apply a first schedule grid. You may want to create and review multiple grids before you apply one! Fix conflicts when they arise. Adjust the schedule as needed.
4. Once you are happy with the schedule, you may want to enable synchronization with the W3C calendar. Set the calendar setting to draft first, update the W3C calendar. Make sure the entries look good. Then set the setting to tentative, and update the W3C calendar again ("draft" calendar entries can be deleted, "tentative" calendar entries can only be canceled). If you do not want to propagate room names to the W3C calendar initially, add rooms: hide to the project's description.
5. From then on, you can continue to adjust things: create new issues, change schedule, etc. At any time, you can visualize the current schedule. Note canceling a session is not automated yet and requires manual interventation to cancel calendar entries that might have already been created.
6. Once you are confident that the schedule will not change anymore:
   • In the project, drop rooms: hide and update the calendar setting to confirmed
   • Run the job to update the W3C calendar for all sessions with calendar entry status of confirmed.

How to adjust the shedule

How to adjust the schedule for a breakouts event

In a breakouts event, a session is scheduled when its Room, Day and Slot project fields are set. You may view and edit the fields through the project views. The project fields also appear on the right side of an issue on GitHub (or at the bottom on narrow screens).

Updating the Room, Day or Slot field of a session effectively changes the schedule. Once you are done with the edits, you will need to:

• re-validate the schedule, using the Validate all sessions job. You may ask the job to only validate "scheduling".
• propagate the updates to the W3C calendar, using the Update W3C calendar job.

Tip

It is extremely easy to introduce conflicts in a schedule and there is no easy way to rollback changes once you have made them. Before you make changes to the schedule, we strongly recommend testing these changes through the try schedule changes job (for group meetings), or the test schedule changes feature of the schedule command (for breakout sessions or meeting planners who like command-line tools).

How to adjust the schedule for group meetings

For group meetings, a session is scheduled when its Meeting project field is set to a valid list of meetings. You may view and edit the field through the project views. The Meeting field also appears on the right side of an issue on GitHub (or at the bottom on narrow screens).

Valid list of meetings

Important

We try to make tools flexible but the Meeting project field still needs to follow a precise structure. If you run into validation problems with the Meeting project field ("meeting format" errors), make sure you respect the following rules!

The following rules apply:

• A valid list of meetings is a set of meeting entries separated by a semicolon (;). The order of entries in the list does not matter. Spaces before or after a semicolon are not significant.
• A meeting entry is composed of a room, a day, and a slot. The order does not matter but the room, day, and slot must be separated by a comma (,). Spaces before or after a comma are not significant. The room may be omitted if there is a room by default.
• The day may be specified as the day's label (e.g., "Monday"), or using the date (e.g., "2023-09-11").
• The slot may be specified through its full name (e.g., "11:00 - 12:00"), but stating the slot's start time (e.g., "11:00") is enough. If really needed, you may also use a more advanced syntax to set custom start/end times.
• All individual slots must be specified. There is no shortcut mechanism to say "the group meets throughout Monday", all slots need to be listed. The synchronization with the W3C calendar is smart enough to combine contiguous slots for the same day into one and only one calendar entry. For example, if there are 4 slots per day, starting at 09:30 and ending at 18:30, and the Meeting field lists them all for Monday, the code will only generate one calendar entry for the group on Monday from 09:30 to 18:30.

Some examples for an event with days "Monday (2023-09-11)", "Tuesday (2023-09-12)":

• Monday, 09:30, Salon Ecija: one meeting on Monday at 09:30 in Salon Ecija
• 2023-09-11, 09:30 - 11:00, Salon Ecija: same as above
• Ficus,11:00,Monday; Tuesday,09:30,Bambu: two meetings, one on Monday at 11:00 in Ficus, the other on Tuesday at 09:30 in Bambu.

Room by default

The Room project field may still be used for group meetings. When set, it defines the room to use for the meeting entries, unless the meeting entries specify a different room. This is particularly useful for group meetings because groups tend to stay in the same room throughout an event. It allows meeting planners to quickly visualize the room used by a group, and to simplify the Meeting string. The job that creates a schedule sets the Room field when possible.

For example, if a group meets in "Bambu" on Monday and Tuesday mornings, you may end up with the following fields:

• Room: Bambu
• Meeting: Monday, 09:30; Monday, 11:00; Tuesday, 09:30; Tuesday, 11:00

The above example creates the exact same meetings as if you had not set the Room field and had set the Meeting field to Monday, 09:30, Bambu; Monday, 11:00, Bambu; Tuesday, 09:30, Bambu; Tuesday, 11:00, Bambu.

Beware though, if a group needs to use more than one room, the Room field no longer shows anything useful, and can become misleading.

Note

The Day and Slot fields can also be set for group meetings, with the same "default value" meaning. For your own sanity, we do not recommend setting these fields.

Custom start/end times

Possible slots are imposed through project settings and this should be good enough for the vast majority of meetings. If you need to schedule a meeting using slightly different start/end times, you may use the following advanced notation for slots in the Meeting field: add the actual start/end time right after the slot's time enclosed in <> (without any space before the left angle bracket). For example:

• 9:00<8:30>: meeting starts at 8:30, not 9:00
• 9:00 - 11:00<10:45>: meeting ends at 10:45, not 11:00
• 11:00<11:30> - 13:00<12:45>: meeting starts at 11:30 and ends at 12:45

Important

You still need to base the schedule on existing slots. That is, you cannot directly write 11:30 - 12:45 to set the meeting, you must write 11:00<11:30> - 13:00<12:45> instead.

The custom start/end times must make sense:

• The custom start time cannot overlap with a previous slot
• The custom end time cannot overlap with a next slot
• The custom start/end times must be different from the times they refine
• The custom start time must be before the custom end time.

Applying changes

Updating the Meeting, Room (Day and Slot as well, but we do not recommend doing that for group meetings) fields effectively changes the schedule. Once you are done with the edits, you will need to:

• re-validate the schedule, using the Validate all sessions job. You may ask the job to only validate "scheduling".
• propagate the updates to the W3C calendar, using the Update W3C calendar job.

Tip

It is extremely easy to introduce conflicts in a schedule and there is no easy way to rollback changes once you have made them. Before you make changes to the schedule, we strongly recommend testing these changes locally through the try schedule changes job (for group meetings), or the test schedule changes feature of the schedule command (for breakout sessions or meeting planners who like command-line tools).

How to set the title of group meeting issues

For a single group meeting, the issue title must be the name of the group that will meet, as it appears in the W3C database, group type included (e.g., Community Group, Working Group). The group type may be abbreviated (BG, CG, IG, WG) to keep the title shorter. Casing does not matter.

For a joint meeting, the title must be the list of group names separated by a comma, and or &. The title must also end with joint meeting. Casing also does not matter.

For example:

• Second Screen CG
• WebTransport Working Group
• Media WG & Web Real-Time Communitcations WG joint meeting
• JSON for linking data CG, Web of Things WG, RDF Dataset Canonicalization and Hash WG Joint Meeting

Session validation fails when the name of a group cannot be identified as an existing W3C group. If the group is supposed to be a W3C group, check the group name and type against the W3C database and fix the name accordingly. If the group is not a W3C group ("Web Platform Tests", "WHATWG") but should meet nevertheless, add the group to the W3CID_MAP variable to tell the validation logic that this is normal. See Variables tab for details.

Session validation also fails when more than one issue exists for the same group, unless highlights are used as described below.

Group meeting highlight

The issue title may also be completed with a meeting highlight. That meeting highlight can be used to clarify that the group will discuss a specific topic during a specific slot. This can be useful for groups with a large number of deliverables. Meeting highlights must come after a : or a >. Any number of spaces may be inserted before/after these characters.

For example:

• WICG: Digital Credentials API
• Second Screen WG > OSP
• Media WG : WebCodecs

The full issue title (with the meeting highlight) will be used in the schedule grid and calendar.

Multiple issues may be defined for the same group(s) provided they define different meeting highlights. For example, there may be three issues defined with the following titles:

• WICG
• WICG: Digital Credential API
• WICG: Fenced Frame

How to add a room, day or slot

You may adjust project settings at any time. For example, you may introduce more slots, more rooms or extend the event to another day simply by adjusting the corresponding project fields. Of course, if you remove a room, day, or slot, you may want to validate all sessions again after updates to check group meetings in particular.

How to enable plenary meetings

Warning

Changes made to the tools to handle group meetings partially broke the plenary meeting mechanism. If you need plenary meetings for your event, ask François (@tidoust) to stop procrastinating.

To enable plenary meetings at the event (larger and broader audience, to raise awareness on a series of sessions):

1. Make sure that the session.yml file contains a type selection field that lets proposers choose between breakouts and plenary types, as done for Breakouts day 2024
2. If the name of the plenary room is different from "Plenary", add plenary room: [room] to the project's short description, e.g., plenary room: BigGreatRoom.
3. If the number of sessions in a plenary meeting is different from 5, add plenary holds: [nb] to the project's short description, e.g., plenary holds: 6.
4. If the IRC channel for plenary meetings is different from #plenary, add plenary channel: [channel] to the project's short description, e.g., plenary channel: #brilliant-ideas.

The scheduler will automatically assign a plenary meeting to an available slot and avoid scheduling breakout sessions in parallel with any other sessions. To force a specific slot, assign it to one of the sessions in the plenary before you run the scheduler.

The scheduler will create one calendar event per plenary meeting, linked from all sessions in the plenary meeting.

Sessions in a plenary meeting are listed in the agenda of the calendar event in the order of their issue number. To specify a different order, add order: [pos] instructions to the "Note" custom project field of each session in the plenary, where order: 1 signals the first position (sessions without an explicit order are listed last, in the order of their issue number).

Cancel a session

Not yet automated; see issue 30 for what needs to be done.

Testing

Generated HTML

Testing of HTML generation is done against reference pages. When HTML generation changes, the tests need to be updated:

• Set a local environment variable UPDATE_REFS (to any value)
• Run 'npm test'
• Check diffs and commit the reference pages