Event scheduling system

[hedyhli]

With a new design for our events page (#1210), we’ll have to update our events page more often to keep it up-to-date. We need a way to minimize the efforts and friction for this redundant work by automating it in some way.

Note: The problem this proposal tries to solve comes from the design of the new events page, for which PR is not yet merged, but in the event of that feature not ending up getting to production, I believe some ideas presented here can still be useful regardless of what our new events page might look like.

I recommend having a brief scroll through the redesigned events page and the events' README.md file before reading this issue to familiarize yourself with its components which will be mentioned throughout this issue.

The problem

Our new events page will display three components that require fairly frequent updates:

1. The “Scheduled” events list — showing a list of upcoming events lined up for the rest of the year with brief descriptions of what each is about.
2. The “Previous” events list — the same as above, except it's for events that recently happened.
3. The “Current” event box

It’s cumbersome to have to PR to the site repo every time an event is scheduled, or after it has happened. Ideally, we just need the event host to specify the list of events to display and the dates they will happen, once, by whatever means, and the site should automatically display this event as either upcoming, current, or having already happened after its scheduled date has passed, depending on the date of the web request.

The solutions

Here are two possible solutions I thought of.

1. First option A bot command can be used to set up the dates for a new event, say PyWeek — March 17-24th, the bot then sends an API request to the site and the site can reflect these dates for the new event on the events page. When the events page is requested at a time after March 24th, PyWeek 37 then shows up under "Previous events". This removes the chore of having to update the static page whenever an event starts/finishes.

2. Second option Use a markdown/YAML file in the site repo (similar to the branding calendar) to specify all the events and all their dates for the year in one go. The idea is, we update the file only when events are rescheduled or new events are introduced, then have the site pull data from this file and display the event in eitehr scheduled, current, or previous depending on current date. This is easier to implement than the first option as only work on the site needs to be done, but PRs are still required, just much less frequent than how it is in the status quo.

User experience would be best in the first option — all we need is to run a few bot commands — less burden for reviewers and any amendments can be made faster. However, the system would require much more work to implement.

I floated the first idea in #dev-contrib and @janine9vn indicated her interest; so in this issue, I’ll be focusing on the first option — what is required, suggested implementation, and the resulting workflows.

---

• How it could work
• Possible Implementation
  • Bot — Commands
  • Annual events
  • Site — Front-end
  • Site — API
  • Site — schema
• Déjà vu?
• Workflows
• Related
• Other references
• Feedback appreciated!

How it could work

Each event in this context is a standalone instance of perhaps an annually occurring event, for example, PyWeek 37 would be one event, rather than PyWeek in general. One-off events would also apply.

The website needs to know, when the main page is requested, the list of events to be showcased. Whether to put an event in “Scheduled” or “Previous” is determined by the view handler on the site, based on date of the web request.

For each event, the website needs the:

• Name — “PyWeek 37”

  • Should allow updates, such as adding “PyWeek 37: Tube” after theme-voting.

• Type — pyweek/advent-of-code/adhoc

  • A way to specify whether this event is part of a recurring event or is a one-off event. This allows some information to be reused when recurring events are scheduled each year. (More on this later.)

• Brief description

  • Shown when event is in “Scheduled” events list.
  • Can possibly allow markdown.

• Detailed description

  • Shown in “Current” event callout box.
  • Should probably allow markdown. Either way, any HTML will be considered safe and be inserted directly into the template.

• URL (optional)

  • Can either be external (https://pyweek.org/) or one of our own sub-pages (such as for code-jam).
  • Should allow updates - for example, PyWeek 37 was scheduled to for March 17-24th before the website (https://pyweek.org/37/) was live, giving people a heads up for the upcoming event.

• Date

  • Should allow both date ranges (December 1-25th), and a generic month where the event is likely to happen (September, for PyWeek 38).
  • Should allow updates when the exact date is confirmed for an event.

• Assets — banner (optional, fallback to icon if it’s not provided)

  • Shown when this event is promoted as “current event” as a callout at the front page.
  • Optionally with an alternate version for dark mode.

• Assets — icon

  • Shown next to the name in “Scheduled” and “Previous” events lists.

For annual events:

• The banner, icon, date (month + current year), name, and descriptions could have fallbacks, since these events happen every year and their structure and overview might be similar.
• These fields can then be updated when the event specific for this year has been scheduled, and the branding made.
• The URL can use a fallback when the event to be scheduled does not yet have its specific page. Such as setting https://pyweek.org/ for PyWeek before https://pyweek.org/37/ is ready.
• These defaults can be defined through some other means, such as YAML files in the site, or stored in the same way that event-specific data is stored when events are scheduled. More on this later on.

Possible Implementation

Here’s a brief breakdown of the general pipeline of an event before it ends up on the events page:

1. Bot: Bot command to setup all the information
2. Site: The data is sent to a site API
3. Site: The site saves the data in some way, such as using a DB table
4. Site: The page is requested
5. Site: Events to be displayed are fetched from the DB
6. Site: The view handler processes the data into three separate lists - Scheduled/current/previous
7. Site: The three lists are passed into the front page template, which displays them in a similar manner as it’s displayed now

Bot — Commands

For brevity, let’s say we use Sir Robin and the base command is &event . Sub commands of &event:

• create

  • Create a new event.
  • We can decide whether to let this command set this event to be “shown” straightaway, or require a &event show before it’s listed in the “Scheduled” list so the event is only manually set to be shown when all the info is ready.
  • For convenience of supplying command arguments and fuzzy searching of event names we should probably use a slash command here. This way, we can have optional arguments to set other fields like date, URL, assets, description together when the event is created.
  • Output: info subcommand output, which has interaction buttons to edit the individual fields.

• set - set or update each <field> to some <value>

  • Possible alias schedule/reschedule for setting the date.
  • Possible alias rename for setting the name.
  • Output: info subcommand output, which has buttons to edit the individual fields.

• hide / archive

  • Stop showing this event on the website.
  • The event is not deleted.

• show (rename to publicize/publish to avoid confusion with info command?)

  • Show this event on the website.
  • Reuse previously stored data about the event.

• delete

  • Delete the data associated with this event.
  • With confirmation.
  • Must start over using create to create this event again.

• info

  • All the details relating to a specific event.
  • With interaction buttons to edit specific fields for this event.
    • Possibly using a text field as input when clicked.
  • With Hide/Show/Delete interaction buttons.
    • Delete after asking for confirmation.

• calendar / list

  • A tabular overview of all scheduled events for the year.
  • Similar to!branding calendar.
  • This can be displayed as a merged list of “Scheduled”, “Current” and “Previous” events from the website.

Annual events

For recurring events such as Advent of Code and PyWeek, we would want to reuse descriptions and the default branding so we don’t have to specify them each time the event is scheduled. These sort of information would be updated less often, so they could just be defined in the site repo as something like YAML. This data (committed to git) can then be read when the events app is loaded, just like for resources/content apps. An identifier (like a slug) will be defined for each of these events so that when scheduling a yearly occurrence of it through the bot commands, we can refer to this identifier in the “type” field.

For example:

• In site repo, a file (whether that be YAML or other) defines the RoC event, with:

  • Name: “Revival of Code”
  • Identifier/Slug:revivalofcode (this can conform to the slug used for the event webpage)
  • Description: General description for each year’s RoC event
  • Branding URLs: The same branding to be used each year during RoC
  • Date: May (A general date to be shown when this year’s RoC is not yet scheduled)
  • URL, … other fields

• When this year’s RoC is scheduled, issue a bot command to specify the following, eg:

  • Name: “Revival of Code 2024”
  • Type: revivalofcode
  • Date: The decided date for this year’s RoC
  • Branding: Special branding for this year, if any

• So in this example, the 2024 RoC event will reuse the generic description and URLs defined in the site repo, but with the decided date and special branding.

Site — Front-end

How many events or for how long do events stay in the “Previous events”? This can be controlled in the template or view.py to show the event lists.

• It could be manual - all events set to be “shown” will be shown on the page, until we run &events hide <event>.
• It could also be automatic - after X months after the event has passed, this event will no longer be shown at all.
• Or a combination of both! Show all events, except when it’s manually hidden, OR X months has passed after the date.

Site — API

We could have something like a /bot/event endpoint implemented within the events app with the following methods:

• POST
  • Create an event with some initial data
• PATCH
  • Update data for event
  • Update show/hide status
• GET
  • Info for event
  • Calendar
• DELETE
  • Delete an event

Site — schema

Fields

• As described at the very top
• It’s probably not necessary to store the general information for recurring events in the DB

Operations

• Add new event
• Remove event
• Query events by name or date

Déjà vu?

As it happens, we once had a proposal very similar to this one, but for a different purpose:

• https://github.com/python-discord/bot/issues/1172
• https://github.com/python-discord/site/issues/396

Unfortunately, it was eventually abandoned because discord introduced the native events feature that replaced what that proposal tries to implement.

However, Iceman made a really nice diagram which could be very useful for reference in this issue: https://github.com/python-discord/bot/files/5360694/plan.pdf

And they also did some amazing work in these two PRs which was supposed to implement Zig’s issue:

• https://github.com/python-discord/bot/pull/1269
• https://github.com/python-discord/site/pull/410

All of this could be useful as reference when we consider the feasibility of this current issue and during implementation.

Workflows

Now, after writing all that, I started to question whether putting in the work to implement such a thing could save time and hassle in the long run at all. Here’s a comparison of the status quo with what the workflow might look like if this is implemented.

• Initial setup

  Current - N/A

  After the system is implemented:

  • Fill up YAML/markdown files for AoC, PyWeek, RoC, Code Jams with the fallback information and PR to the site. This would only need to be done once.

• New event to be scheduled (whether that be regular or adhoc - so long as we want to display it on the events page)

  Currently, we need to:

  • PR to site to update “Scheduled” events list

  Now, we can just:

  • &events create <type> <name> <date>

• Update info for event - new branding / website has been made / typos / reschedule

  Current

  • PR to site - edit HTML

  New

  • &events set <name> <field> <value>

• Event started

  Current

  • PR to site to change “upcoming” to “ongoing” in the “current event” box

  New - Nothing needs to be done!

• Event finished

  Current

  • PR to site - Update “current event”, move event from “scheduled” to “previous”

  New - Nothing needs to be done!

Related

Small event management system - bot#1603

• Similar - scheduling and storing details
• Different - no notification/subscriptions of any sorts - in the system I’m writing about now, all information is stored so that we can dynamically display it on our website without having to update the site each time

Branding calendar system

• Similar - a rotation of displaying data related to scheduled events, commands to show current and upcoming events
• Different
  • the rotation itself happens on the website rather than in the server
  • updates to the calendar is done via bot commands rather than updating a repo
  • there, data is fetched from repo and saved in bot, in this system data changes are triggered from the bot is saved in site’s DB

Other references

Credits for the original idea goes to @doublevcodes from https://github.com/python-discord/bot/issues/1603#issuecomment-845494380

This probably won't be a priority but it would be cool to have any events scheduled show up on this website (as I currently understand it the whole events section is being redone).

Proposal in #dev-contrib: https://discord.com/channels/267624335836053506/635950537262759947/1219026167571677324

Feedback appreciated!

To be frank, I’m not very familiar of our existing systems to manage events within our server, if any exist at all. I've written this issue from the perspective of someone who hardcoded as HTML those three lists we need to keep up-to-date — and how it might work when connecting with the bot. I would be curious to hear about how well this proposed system could be integrated to our existing workflows in hosting events, as well as any other feedback regarding design decisions mentioned and the user interface proposed.

Do you think the work to be put into this is worth it to make the process easier? Is submitting PRs every time that much of a hassle right now (considering the new redesigned events page)? Could something like this also help with any other parts of the events management workflows in the server, or in the future?

[jchristgit]

I do think that the less manual labor we have with updating the events page, the better. I think the repeated occurrences of the page becoming outdated only for some "batch update" much later to bring it back into the current year showcase the benefits of the API-based solution very well. There is one more problem that I can think of. If we go the database-backed approach, then contributors who set up the site will not have the same events on the events page than the live site has. More, it will become more complicated for them to update any entries of the events page locally. So overall I think we would lift off some convenience from contributors in exchange for being able to keep the page up-to-date more easily - I think it's a worthy tradeoff but we do need to consider it.

[hedyhli]

More, it will become more complicated for them to update any entries of the events page locally.

Hmm, update the entries in what sense? This proposal intends to allow updates to the entry via bot commands, so contributors do not need to do anything in the repo. If those commands are mod/events-lead/admins-only, they can simply mention any changes required over on discord and someone with the perms who sees it can action it immediately.

There is one more problem that I can think of. If we go the database-backed approach, then contributors who set up the site will not have the same events on the events page than the live site has.

That's a good point! I hadn't considered that. But after we have this system in place is it really necessary for contributors to have the same list of events? For any PRs that involves the events page design or changes to the template, yeah having no data would be a little inconvenient. For now, one way I can think of (without running bot simultaneously) is including a file similar to init.sql that prefills some dummy events, so some content can show up on the events page for them to preview any changes to the CSS/HTML they are making.

[jchristgit]

For now, one way I can think of (without running bot simultaneously) is including a file similar to init.sql that prefills some dummy events, so some content can show up on the events page for them to preview any changes to the CSS/HTML they are making.

Yup, I think this would be the way to go if we end up choosing this approach.

[wookie184]

Personally I think I would be in favour of the second option, defining event files using markdown/YAML.

A few benefits I think this has over the first option:

• It's a lot simpler to implement and maintain.
• We'll still need some pages hosted on GitHub for events such as the pages explaining the rules and format of the code jam, so keeping everything on GitHub is more consistent.
• I think Discord commands could end up being a bit fiddly to use and it could be hard to remember how to do different things. With GitHub it should be more obvious, just add a new file, using a template/existing event for reference. It would also be much easier to do things like make edits.
• Having a review can be helpful, and is much easier through the GitHub UI (e.g. with suggesting changes). Regardless, we can still tweak review requirements if we wanted so e.g. we could not require reviews on those files for events team members.
• Non-staff can still contribute to the contents. Whilst it's mostly a staff thing since they have the information to be added, it's still nice to be able to accept contributions from non-staff, even if it's just improving the wording or fixing a typo.

[jb3]

cc @janine9vn as events lead, is this still something we think we need with the frequency that we run events?