Rework seasonal branding structure

[ks129]

The current setup we have for seasonal branding is out of date. Even the name doesn't work anymore. In order to work well with python-discord/bot#1431, we need to reorganize these assets and standardize on a single approach.

Wait, what's this for?

Read python-discord/bot#1431 before you read this. Basically we want every PyDis event (or maybe we should call it something else? Holiday? Doodle?) to contain all the information needed in order for the bot to automatically manage branding assets.

So, it's Valentines day, and the bot changes the icon, changes the discord banner, and posts a message into #changelog with a short explanation about what the icon represents. That's the end product.

Okay, so what changes do we need to make?

Well, currently we have the seasonal folder, and we've got the events folder. These two should be merged into a single folder, and we should get rid of anything that doesn't fit our new structure.

For each event, we'll need a structure roughly like this:

├── events/
│ ├── valentines/
│ │ ├── server_icons/
│ │ │ ├── love_heart.gif
│ │ │ ├── beating_heart.gif
│ │ │ ├── valentines.png
│ │ ├── misc/
│ │ │ ├── anything_can_be_in_here.txt
│ │ │ ├── the_bot_will_ignore_it.png
│ │ │ ├── could_be_useful_for_major_events.zip
│ │ ├── banner.png
│ │ ├── meta.md

This is pretty similar to how the seasonal folders were organized back in #46, with the exception of the meta.md file.

So how would the meta.md look?

Here's an example of how it might look, although you're free to iterate on this as you see fit.

---
start_date: 2021-12-01
end_date: 2021-12-25
repeats: annually  # For one-time events, we could put 'never'.
---
**Advent of Code**
The server icon and banner have been changed to the **Advent of Code** branding. You can learn more about Advent of Code [on their website](https://adventofcode.com).

What about all the stuff we're currently missing?

Since we do not have banners for all the stuff inside events, and we don't have meta.md for any of the events, this additional material should be created in this PR. If that's not feasible, we should just get rid of the event, and we can reimplement it with a fully compatible PR later on.

How do we test and validate submissions?

It would be fantastic if we were able to validate the contents of a PR into this folder using CI, but I think this should probably be a separate issue that we can tackle later. I imagine a piece of CI that would ensure dates were valid, ensure the dates didn't conflict with another event, and ensure that all the required files were there.

edited by lemonsaurus

[kwzrd]

I really like the idea of using the frontloaded YAML for the meta file. Assuming the #changelog notif will be sent as an embed, we will basically have a tag with some extra meta information (not to digress, but could Python's tag system also benefit from this?).

However, I think we need to decide on how to define the time periods. The proposed example is a little different to what I imagined, which was to have year-agnostic dates, e.g.:

period: 24/12  # Active on the 24th of December
period: 24/12-30/12  # Active from the 24th to the 30th of December

Does the day go before the month in this case? I'd say yes, but it may be a regional preference.

This assumes that most events will repeat annually (do they not?). If an event shouldn't repeat, making a commit to null the value, remove the key, or the whole meta file, or invalidate the event in some other way seems fine to me.

I'm also thinking about whether we would want to allow overlapping events. I'm thinking probably not, but if we want to verify this, it makes a strong case for some kind of CI validation script, as you mention (it would also check that the dates are correctly formatted, and that there's a banner and at least one icon).

Regarding the stuff that is currently missing - adding the meta files in this PR makes sense to me, but I'm not sure whether it'll be feasible to also provide all the banners. In the case that we leave that for later, what should happen with the existing assets? Should they be moved elsewhere, or can they live in an event directory in an "invalid" state (the lack of a meta.md in the directory could simply make Python ignore it).

These are my thought so far. Thanks for taking the time to write a detailed issue!

EDIT: Oh, I think there also ought to be some way to register an event as default i.e. fallback for when no other event is active - the evergreen season. This event won't have a start and end date (it would collide with others).

[kwzrd]

For the date formats, we agree with @jb3 that using the month name may be the best option, especially since we can still parse it with datetime:

>>> datetime.strptime("January 5", "%B %d")
datetime.datetime(1900, 1, 5, 0, 0)

So the config file could look like:

start_date: January 5
end_date: March 12

This remains easy to parse both programmatically and humanly.

[whispersofthedawn]

I have a quick suggestion. Maybe add a branding command (eg. !branding) that anyone would be able to use to see what the current branding is, what it means, and why it's there.

This could help with certain events like international holidays such as the Diwali ones where many people may not known what it means. This is just a rough idea, but maybe something like:

---

Branding
Right now, PyDis's current branding is for Saint Patrick's Day.

Goes on to elaborate about the day.

Thumbnail: Server Icon
Picture at the Bottom: Server Banner

---

That would make it simple and easy for people to understand the latest changes, and what it means. I saw how you proposed the changelog idea (which is a very good idea), this is just a possible alternative.

When it's the default, it could just say that it's the default PyDis icon.

I could assist in the development of any of this if needed.

[lemonsaurus]

@kwzrd
I think your suggestion is fine, provided that we accept an optional years parameter for non-recurring events, like we discussed in the community.

@dawnofmidnight
I don't necessarily mind having a !branding command, but I'm not sure if it's necessary if that information is always going to be available in #changelog. Either way, it'd have to be implemented after we're done with these initial changes, as I'm hesitant to expand the scope of this task further.

If you're keen to implement this, I suppose you can create an issue on bot and make it clear that the issue is blocked by the botside implementation of these changes, and should be tackled afterwards. I'm happy to let you handle it when these changes have been merged.

[kwzrd]

Okay, sounds like I can start moving things around. It quickly became apparent to me that I will be writing some sort of validation script for my own self anyway, to be safe that all event directories are setup correctly. So we'll see, maybe I'll include it in the PR.

I'm interested what kind of CI setup we'd come up with. Since it'll depend on something (python-frontmatter works well, although it hasn't had a commit since late 2019, but it's lightweight and perhaps simply mature), I'm thinking that we would include a Pipfile and a validation.py script in the repo, sync an env in CI and run the script. It will look for errors, and if it finds any, print out a nicely formatted message and exit with a non-0 code. Does that sound ok? Any CI people have thoughts on this? I think there may also be the option of failing the pipeline / workflow if anything gets written to stderr.

Ideally the definition of what a "valid" configuration looks like would be dictated by the Python repo, but I cannot think of a solution to do that that isn't impractical or overcomplicated. So if the requirements change Python-side, the validation here will have to be updated separately, but I suppose we can live with that.

[kwzrd]

For a quick update: my more-or-less finished implementation Python-side is using python-frontmatter, but I'm still looking for input regarding the CI setup.