Staffing¶
Staffing decides which volunteer does which job, and where. An event defines its own jobs, called staff roles. Some are needed in the talks: a session chair who introduces the speaker, a timekeeper, a person for audio and video. Others are needed at a station, a place that is not a talk room, such as the reception: checking badges, answering questions. A talk or a shift at a station is a duty.
Volunteers say when they are free and where and what they would like. On the grid they ask for open spots and rank single talks and shifts. Administrators decide who goes where, helped by an automatic allocation that turns those answers into a plan.
Source: the staffing/ app,
with templates in
templates/staffing/.
Who can do what¶
A volunteer of an event is one of these:
- a superuser
- a user with staff status who is a member of the event
- a user who is staff for that event
This rule is narrower than the one for Q&A moderation. Staff status moderates the Q&A of every event that the user can open. For staffing, the user must also be a member of the event. A Discord role can grant staff status, and without this rule every such user could read the roster of any public event. Every staffing page requires a login.
| Action | Volunteer | Superuser |
|---|---|---|
| See who staffs each talk and shift | yes | yes |
| Declare availability and preferences | yes | yes |
| Ask for an open spot | yes | no |
| Rank a duty, plan to watch a talk | yes | yes |
| Give up one of their own spots | yes | yes |
| Take an open spot shortly before it starts | yes | no |
| Put a person (themselves too) into a spot, or clear it | no | yes |
| Lock an automatic assignment | no | yes |
| Run the automatic allocation, apply it, discard it | no | yes |
| Edit roles, stations, shifts, and settings | no | yes |
A user who is staff for particular events sees only those events. A talk, role, or run of another event answers with the same 404 as one that does not exist.
Roles and slots¶
A role belongs to one event, and its scope says where it is needed: in talks, or in shifts at a station. A new event starts with one talk role, "Session Chair", so chairing works with no setup. You edit an event's roles on the event's page in the Django admin.
| Field | Meaning |
|---|---|
| Name | Shown on the grid. |
| Description | Shown to volunteers, so they know what the job is. |
| Scope | Talks, or shifts at a station. |
| Default slots | For a talk role: people each talk needs. Use 0 for a role that few talks need. |
| Importance | Nice to have, normal, or essential. Scarce volunteers go to the important roles first. |
| Combinable | Whether one person can hold this role together with another role in the same duty. |
| Order | Position on the grid. |
| Active | An inactive role is hidden and ignored. Its assignments are kept. |
A single talk can need a different number of people. Set that on the talk's page in the Django admin, under "Staff slots". A count of 0 removes the role from that talk.
One person can hold several roles in the same talk or shift. This is the normal fallback in a small room, where the chair also keeps the time. The automatic allocation prefers separate people. If nobody else is free, it combines roles. Turn "Combinable" off for a role that needs full attention.
If you lower a slot count below the number of people already assigned, nobody is removed. The extra person stays visible on the grid with an "extra" badge. An administrator clears the spot by hand.
Stations and shifts¶
A station is a place where volunteers are needed that is not a talk room, such as the reception, an info desk, or the cloakroom. It is kept apart from the talk rooms, which come from Pretalx and appear on the public schedule. You add stations on the event's page in the Django admin.
A shift is a stretch of time at a station, with the number of people it needs in each shift role. A station's page has "Generate a day of shifts": give a day, a start and end time, a shift length, and the people per role. It creates the shifts one after another, the last one shorter if needed. You can change each shift afterwards.
For every rule below, a shift counts like a talk. Someone at the reception from 09:00 to 12:00 is not given a talk at 10:00, by hand or by the allocation.
The grid: who is where¶
The page at /staffing/ lists the roles of each talk and shift and who fills each slot. Rooms come
first, then stations. The old address /talks/chairs/ redirects here. Volunteers find the page in
the header and, on a phone, as the "Staffing" tab of the bottom bar.
The page has two layouts, like the schedule. Below the md width it is an agenda:
one column of time slots, with buttons that a thumb can hit. From md up it is the grid. A switch
on phones shows the grid at any width.
Only administrators put people into slots. A volunteer acts on the cards in two ways:
- Ask for this. The open slots of a role show as one item, such as "2 open", with this button. It asks for that role in that talk or shift. The slot then shows "You asked · #2", the number of the ask in the volunteer's list for the day, with "Take back". A volunteer can ask for several roles in one talk, and for talks and shifts at the same time. An ask that overlaps one of the volunteer's own duties is refused, with the duty named.
- For me. One menu per card holds the volunteer's answer for the duty: Favorite, Happy to, If needed, Never, In the audience (talks only), or Not set. A level here ranks the duty against the others at the same time and overrides the level of its room or station. "Room 1 over room 3, room 3 over rooms 2 and 4" at 10:00 becomes four cards with Favorite, Happy to, and If needed. Not set lets the level of the place count. Superusers get this menu too: they volunteer as well, and the automatic allocation reads their answers like anyone's.
Asks and the "For me" menu answer different questions. An ask says "I would like this spot". The menu ranks the talks and shifts the volunteer did not ask for, and its "Never" says "not this one, even when I am free then". They never disagree: "Never" takes back the asks for the duty, and an ask lifts a "Never". Nobody can sit in the audience of one talk and help elsewhere at the same time, so the newest answer wins, and the grid names the duty whose ask or plan it replaced.
The order of asks¶
The volunteer's asks of each day are one list, most wanted first. A new ask goes last, and the ↑ and ↓ buttons in the list above the grid move it. Taking an ask back closes the gap. "Palladium as session chair, then Palladium as timekeeper, then badge control, then the T-shirt desk" is the start of such a list.
The order decides only between asks that overlap, because only one of those can be granted. Each ask in the list names the ones it overlaps, such as "Overlaps #1, #3". An ask at 15:00 that is fifth on the list counts as a first choice when the four above it are all in the morning. The overlaps are worked out from the times whenever the list is shown, so a talk that moves is compared with the right asks.
The list is per day, not per group of overlapping asks. A chain of overlaps can join asks that never meet: badge control 08:00 - 11:00 overlaps the T-shirt desk 09:00 - 12:00, which overlaps the reception 11:00 - 14:00, but badge control and the reception do not overlap.
Above the grid, "My duties and asks" lists everything the volunteer has going on, which is where a volunteer with a phone looks first:
- "Open now": open spots starting soon, across the whole event, that the volunteer could take themselves (see below), each with "Take it".
- their coming duties, each with "I can't make it" and an optional reason. That gives the spot up: it is free at once, so another volunteer can ask for it or take it.
- their asks, one numbered list per day in the volunteer's order, with the asks each one overlaps and the buttons that change the order. An ask for a role they were given is marked "you have this spot".
- the talks they will watch from the audience.
Each line has a button to take it back. The talk page links volunteers to the talk's day on the grid.
A superuser sees on each card who asked for a spot there, for which role, and at which number in that person's list for the day, such as "Ana (Session Chair #1, Timekeeper #2)". They select "Assign" or "Change" on a slot to pick a person, themselves included. "Assign" on the open item of a role fills its first open slot, and the next one moves up. The picker groups the volunteers by what they declared for that duty: asked for it, free with a favorite place and role, free, declared nothing, not free or not willing, and busy elsewhere. People who asked come first when no ask they put higher competes with this one, and in the other groups the better fit comes first. Then the lower load decides. Each name carries a short note, such as "#2 on their list", "here only if needed", or "never this role", so the superuser sees what they would overrule, and each person's time on duty that day. "Cancel" closes the picker without a change. On a filled slot, "Clear this spot" empties it. An open slot that a volunteer gave up says so to superusers, such as "Given up by Ana: train delayed", until it is filled again.
Giving up and taking spots¶
A volunteer who cannot make a duty gives the spot up with "I can't make it", with an optional reason. The slot is free right away: nobody has to wait for an administrator before another volunteer asks for it. The system notes "could not do this", so no later run puts that person back, and the superusers see who gave the spot up and why, on the grid and under "Needs your attention", while it stays open.
Shortly before a talk or shift starts, waiting for an administrator does not work either. From 30 minutes before the start until the end, an open slot offers "Take it" instead of "Ask for this". A volunteer who takes it gets the spot at once, under the same rules a superuser works with: no two duties at once, and no combination a role forbids. The grid marks such a spot as taken by the volunteer, and a superuser can still change it. "Open now", above the grid, lists these spots across the whole event for each volunteer who could take them: free then by what they declared, not on duty elsewhere, not in an audience, not a role they marked "Never" unless they asked for it, and not a role that cannot be combined with one they hold there. Hidden talks never appear. Each event sets its own window; 0 turns taking off. Filling a slot that someone gave up ends the note about it.
The grid refuses a change that puts a person in two places at once. If one of two roles is not combinable, it also refuses the second role in a duty. Other problems produce a warning, and the change still happens:
- The person has too little time to change places. The limit is the event's change-of-place time.
- The person reserved that time to sit in the audience of a talk.
- The person did not say they are free then, ruled out the duty, its place, or the role, or could not do this duty before.
The names of the staff are shown to volunteers only, on the grid and on the talk page. Someone who set no name shows as a masked email address to other volunteers, and in full to administrators.
Availability and preferences¶
Each volunteer has a page at /staffing/availability/, per event. It asks three short questions,
and every answer is saved as soon as it is given. Answers about one particular talk or shift are
given on its card on the grid, as described above.
- When are you free? Time ranges, day by day, such as "Saturday 08:00 to 13:00 and 14:00 to
18:00". Shortcuts set the whole day, the morning, the afternoon, or "not this day". A volunteer
is never planned outside these times. Times are always 24-hour, typed as
16:20,1620, or16. These are plain text fields, because a browser shows a time field in 12 or 24 hours after its own language settings, and a page cannot change that. A range belongs to the day it starts on and can run past midnight, because a talk in the evening can end the next day: "22:00 to 00:30" ends at 00:30 the next day, and "Whole day" reaches to the end of the last talk. Only an end up to 06:00 counts as the next day; "13:00 to 09:00" is an error, since it is far more likely a typo than a 20-hour stretch. A day is saved as soon as both ends of a range are filled in, and "Remove" takes one range out. - Where would you like to be? Each room and each station gets one of four levels: Favorite, Happy to (the default), If needed, or Never. "Never" keeps the volunteer out of that place.
- What would you like to do? The same four levels for each role.
Levels give a ranking with ties. "Room 1 over room 3, room 3 over rooms 2 and 4" becomes room 1 Favorite, room 3 Happy to, rooms 2 and 4 If needed. Rooms with the same level count the same. A level given to one talk or shift on the grid overrides the level of its place for that duty only.
"Limits and a note" holds the most hours on duty per day and a note for the organizers.
The rules behind the page:
- Being free for a time already says the volunteer is willing to help then. Preferences only rank the places and roles; they never rule anything in.
- An ask for one duty is enough on its own, even outside the volunteer's free time: it is their newer and more specific answer. The grid warns them when they ask, in case it was a slip, and the list above the grid marks such an ask. The volunteer does not need to mark the time as free, and a role ruled out in general is allowed when they ask for it in that one duty. An ask covers only the role asked for: asking to chair a talk is no answer about doing its A/V, so the picker, the warnings, and the allocation treat that role by the volunteer's general answers.
- A volunteer who declared nothing does not take part in the automatic allocation. An administrator can still assign them.
- An ask or an audience plan that overlaps one of the volunteer's own duties is refused, with the duty named. Only an administrator moves duties.
- Removing free time that a duty needs does not remove the duty. It flags the duty for the administrators and tells the volunteer. Giving the time back removes that flag again.
Why free time is stored as time ranges¶
Free time is stored as "from this time to that time", not as links to talks. The schedule moves before a conference. If a talk is shifted, a time range keeps its meaning. A link to the talk follows the talk to a time that the volunteer never agreed to.
An ask or a level for one duty is the opposite. Wanting to introduce a friend's talk is about that talk. If the talk moves, the ask follows it.
The edges of a range are strict. A volunteer who leaves at 17:00 is not free for a duty that ends at 17:05.
The automatic allocation¶
A superuser opens "Automatic allocation" at /staffing/allocation/. The page shows how many slots
of each role are filled, what each volunteer declared, and "Needs your attention": spots a volunteer
gave up that are still open, and duties that no longer match what the volunteer declared since (free
time they took back, a place or role they ruled out, or a talk they will attend). It also starts a
run.
A run has two choices:
- What the plan can change. "Plan again" replaces earlier automatic assignments that are not locked. "Only fill empty slots" keeps every existing assignment.
- How long to search: quick, normal, or thorough.
The run is computed in the background. When the plan is ready, the page updates. The result is a preview. Before the superuser selects "Apply this plan", nothing is assigned.
The preview shows:
- how many open spots the plan fills, and what it adds and removes, duty by duty, with the reason for each new assignment, such as "asked for this, #2 on their list"
- every spot that stays open, with why each eligible person is not in it
- every ask the plan does not grant, with its number on the volunteer's list and the reason, such as "gets another of their asks at that time instead"
- the time on duty per volunteer after the plan, in hours and minutes
If the schedule, the staffing, or someone's availability changes after the preview was computed, the preview can no longer be applied. Start a new run. This rule exists because a plan for an older state can put a person in two places at once.
What a run never changes¶
- A spot that a superuser assigned by hand.
- A spot flagged because its volunteer took back the free time it needs. An administrator decides.
- A spot a volunteer took themselves shortly before the start.
- An automatic assignment that a superuser locked, with the "Lock" button on that assignment.
- Any assignment in a duty that is already over.
- Any talk that is hidden. A hidden talk is embargoed or cancelled, and volunteers cannot see it.
Hard rules¶
The plan never breaks these rules. A spot stays empty instead.
- A person is placed only in a duty whose whole time they marked as free, or that they wished for.
- A person is never placed at a place they marked "Never".
- A person is in one place at a time, across talks and shifts. A partial overlap counts.
- A person is not placed during time they reserved.
- A role gets at most as many people as it has open slots.
- A person never gets a role they marked "Never", unless they asked for it by name in one duty.
- A role that is not combinable is never combined.
- A person stays within their daily limit.
- By default, a person is never given two duties in different places with less than the change-of-place time between them. An event can allow this at a cost, and the preview then lists each case.
Wishes and their weights¶
Among the plans that keep the hard rules, the allocation picks the one with the highest score.
| Wish | Points |
|---|---|
| A slot is filled | 1000, times the role importance |
| An ask is granted, by its choice (see below) | 400, then 50 less each, at least 200 |
| An earlier automatic assignment stays as it is | 80 |
| The duty: favorite, happy to, if needed | 60, 30, 10 |
| The role: favorite, happy to, if needed | 30, 15, 5 |
| The person stays in the same place after a duty | 25 |
| One person holds a second role in the same duty | -300 |
| A tight change of place (in events that allow it) | -450 |
| Each minute above the even share of the work | -2 |
| Each minute of the highest load of any volunteer | -1 |
The level of the duty is the one the volunteer gave it on the grid, else the level of its room or station. The levels of the duty and of the role count only for roles the volunteer did not ask for. An asked role is scored by the volunteer's order alone, so a lower choice in a favorite room cannot overtake a first choice. On a card where the volunteer asked for a role, "For me" says so.
The sizes are the design. A filled slot beats any wish, so the plan never leaves a slot empty to please someone. An ask beats general preferences, even as a fourth choice. An ask's choice is 1 when no ask the volunteer put higher on the day's list overlaps it, 2 when one does, and so on. Of asks that overlap, the plan grants the earliest choice it can. Fairness decides between plans that are otherwise similar. A second role in the same duty costs less than the least important filled slot is worth. If somebody else is free, the plan thus uses that person.
The importance of a role scales the first row: 50% for nice to have, 100% for normal, and 200% for essential.
Ties¶
When two people wish for the same spot, fairness decides first: the person with the lower load gets it. If that is also equal, the person who declared their availability earlier gets it. Both rules are part of one objective, so they hold for every tie in the plan, not only for wishes.
Event settings¶
Each event has staffing settings on its page in the Django admin.
| Setting | Default | Meaning |
|---|---|---|
| Change-of-place time | 5 min | Two duties in different places closer than this are a tight change. |
| Forbid tight changes | on | Off allows a tight change as the last way to fill a slot. |
| Fairness | normal | Relaxed halves the fairness points. Strict multiplies them by three. |
| Take window | 30 min | How long before the start volunteers may take an open spot; 0 is off. |
The default change-of-place time comes from CHAIR_ROOM_TRANSITION_MINUTES, and the default take
window from STAFFING_TAKE_WINDOW_MINUTES.
How the allocation works¶
The rules live in
staffing/solver.py.
That module takes plain values and returns plain values. It does not use the database, so each rule
has a test on a problem built by hand.
staffing/allocation.py
reads an event into such a problem, stores the result, and applies it.
The solver is CP-SAT from OR-Tools, a solver for problems with yes-or-no decisions and rules between them. Each decision is "this person takes this role in this duty". The solver does not know talks from shifts: both are a place, a start, an end, and roles with slots.
A simpler method, such as min-cost flow or the assignment problem, does not fit. Those methods need every decision to be independent of the others. Three rules link the decisions of one person. Duties of different lengths overlap partially. Fairness depends on the person's total load. The change-of-place rule connects pairs of duties.
allocate(event, mode):
fixed = assignments that stay (manual, taken, locked, flagged, in duties that are over)
replaceable = unlocked automatic assignments, in "plan again" mode
open slots = slots per role and duty (talk or shift), minus the fixed assignments
candidates = (person, duty) pairs: free for the whole duty and the place not "Never",
or wished for; minus reserved time, overlaps and tight changes with fixed duties
for each day, in order:
takes[person, duty, role] = yes or no, for each allowed choice
add the hard rules
load[person] = minutes so far + minutes of this day
score = points of each choice
- 2 * minutes above the even share
- 1 * highest load
maximize score * big number - sum of submission ranks of the people placed
preview = what to add, what to keep, what to remove
report = open spots with reasons, wishes not granted with reasons, loads
Three details are worth knowing.
The days are solved one after the other. Every hard rule is about one day. Only fairness looks across days, and it is carried forward as the minutes each person already has. This keeps each model small. A day with 80 volunteers and 200 slots takes about ten seconds and ends within 0.5% of the proven best score.
The search is repeatable. The same input gives the same plan, on any machine. The solver runs its
parallel workers in a fixed order (interleave_search). The search budget is counted in the
solver's own work units, not in seconds. The number of workers is STAFFING_SOLVER_WORKERS. A
different number can pick a different plan among equally good ones.
The reasons in the preview are worked out after the search, from the finished plan. They say what keeps each eligible person out of an open spot now. An organizer needs that to act. The reasons are not a proof that no other plan fills the spot.
The preview states one of two results: the plan is proven to be the best one, or it is the best one found in the time given. A thorough search can improve the second result a little.
Running it from the shell¶
The allocate_staff command does the same as
the allocation page.
Limits¶
Talk.session_chairstill exists in the database and is no longer used. A migration copied every chair into the new tables. The column stays for one release as a way back, and a later migration drops it.- A run is one background thread in the web process. If the process restarts during a run, the run never finishes. The page says so after ten minutes, and you start a new run.
- Only one run per event is computed at a time. A second start leads to the run in progress.
- The application of a plan sends no notification to the volunteers.
- Free time is one answer for all places. "At 13:00 room 1 or room 2, at 15:00 only room 3" is said with levels on the cards of those talks: Never for the ones the volunteer will not do.