Restructure event directories

.github/workflows/event-validation.yml

@@ -0,0 +1,28 @@
+name: Event Validation
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  validate-events:
+
+    name: Validate Events
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v2
+
+      - name: Set up Python
+        uses: actions/setup-python@v2
+        with:
+          python-version: 3.8
+
+      - name: Install dependencies
+        run: python -m pip install -r events/requirements.txt
+
+      - name: Run event validation script
+        run: python events/validation.py

.gitignore

@@ -1 +1,8 @@
+# Apple things
 .DS_Store
+
+# JetBrains stuff
+.idea/
+
+# Contributors may want to generate a local Pipfile for event validation
+Pipfile*

README.md

@@ -21,7 +21,7 @@ If you'd like to link to us, one possible description you could use is below:
 
 The lemoji emotes found in `emotes/lemoji` are adapted from various emoji in [Twitter's Twemoji pack](https://twemoji.twitter.com/). We're using their lemon emoji as the base, and many of the features are taken and adapted from other emojis. These are all licensed under the same license as Twemoji, which is [Creative Commons Attribution 4.0 International License](https://creativecommons.org/licenses/by/4.0/). 
 
-A part of Diwali assets found in `seasonal/diwali` is made by `visnezh` from [freepik](https://www.freepik.com/free-vector/colorful-mandala-with-floral-shapes_974305.htm).
+A part of Diwali assets found in `events/diwali` is made by `visnezh` from [freepik](https://www.freepik.com/free-vector/colorful-mandala-with-floral-shapes_974305.htm).
 
 Our logos are derivatives of the official Python logo. More information on how their assets are licensed can be found on [their trademarks page](https://www.python.org/psf/trademarks/).
 

events/README.md

@@ -0,0 +1,93 @@
+# Events
+
+This directory contains branding for events celebrated by Python Discord. Events are automatically discovered by the [Python](https://github.com/python-discord/bot/) bot and have their assets applied to the Discord guild when active. As such, event directories must follow a specific structure.
+
+## Event directory structure
+
+For an event directory to be valid, it has to contain the following assets.
+
+### `meta.md`
+
+Meta files consist of two sections: a [YAML frontmatter](https://assemble.io/docs/YAML-front-matter.html) with the event's metadata, and a Markdown description.
+
+In the frontmatter of each such file, each event must either be registered as the fallback:
+
+```yaml
+fallback: true
+```
+
+Or have a specified period:
+
+```yaml
+start_date: July 10
+end_date: July 20
+```
+
+There must be exactly 1 fallback event, and 0 or more non-fallback events. Events cannot collide in time, and the end date must either be equal to the start date (1 day event) or chronologically subsequent. Both bounds are inclusive, and the format shown in the example above must be followed.
+
+The markdown section of the meta file then contains the event's description. Descriptions are made available directly in the Discord guild as embeds sent by the Python bot. For formatting, use Discord's watered down Markdown ~ keep in mind that e.g. the `#` symbol does not create a heading.
+
+A description is required to exist, and must be at most 2048 characters in length to fit into a Discord embed.
+
+### `banner.png`
+
+Singular image asset to be used as the guild banner while the event is active.
+
+If you're wondering about the desired dimensions, take a look at existing assets for reference.
+
+### `server_icons`
+
+Directory with 1 or more icon assets. The bot will automatically rotate icons from this directory at a configured frequency. Subdirectories in `server_icons` are simply ignored ~ only icons present directly in `server_icons` are considered.
+
+If an event fails to satisfy these conditions, it will be ignored by Python.
+
+## Reference event
+
+Below is an example of a well configured event:
+
+```
+├── events/
+│ ├── christmas/
+│ │ ├── misc_assets/
+│ │ │ ├── festive.svg
+│ │ ├── server_icons/
+│ │ │ ├── snowing.gif
+│ │ │ ├── festive.png
+│ │ ├── banner.png
+│ │ ├── meta.md
+│ │ ├── reindeer.mp4
+```
+```
+---
+start_date: December 1
+end_date: December 25
+---
+**Christmas!**
+
+I wonder what I'm getting this year!
+```
+
+In this case, on the 1st of December, the bot will:
+* Apply `banner.png`
+* Begin rotating `snowing.gif` and `festive.png`
+* Send a `#changelog` notification with the event description
+
+On the 26th, the transition into the next event takes place.
+
+Files such as `festive.svg` and `reindeer.mp4` are simply ignored. The bot doesn't use them, but doesn't mind them being there.
+
+## Automatic validation
+
+Fortunately, it is not necessary to manually verify that all events are configured properly w.r.t. the requirements explained above. The `validation.py` script contains logic to ascertain correct setup, and will automatically run in CI on pull requests to prevent a broken configuration from reaching the production branch.
+
+Validation happens in two stages. First, all events are checked individually, to ensure that they contain all necessary assets and have a correctly structured `meta.md` file. If all events pass, the second stage verifies that there is exactly 1 fallback event, and that no events collide. In the case of collision, the exact dates and culprit events are printed.
+
+We depend on a minimal set of non-stdlib packages to parse meta files: [python-frontmatter](https://pypi.org/project/python-frontmatter/) wrapping around [pyyaml](https://pypi.org/project/PyYAML/). The exact version pins are provided in `requirements.txt` with the recommended Python version to use.
+
+If you'd prefer to create a virtual environment with Pipenv, it is possible with the following command:
+
+```
+pipenv install -r events/requirements.txt
+```
+
+This will spawn a lockfile that you can sync from. Please make sure that you do not accidentally commit the Pipenv-generated files.

events/black_history_month/meta.md

@@ -0,0 +1,7 @@
+---
+start_date: February 16
+end_date: February 29
+---
+**Black History Month**
+
+[Black History Month](https://en.wikipedia.org/wiki/Black_History_Month) is an annual celebration of the people and historical events of the African diaspora. Historically, its significance lied in an encouragement of teaching the history of Black Americans in public schools. However, the event's importance and popularity have grown over the years, and BHM is now officially recognised and celebrated world-wide.

events/christmas/meta.md

@@ -0,0 +1,7 @@
+---
+start_date: December 1
+end_date: December 25
+---
+**Christmas**
+
+[Christmas](https://en.wikipedia.org/wiki/Christmas) in an annual festival that occurs on December 25, and commemorates the birth of Jesus Christ. It is a very widespread religious and cultural celebration. In the western world, one of the most notable Christmas traditions is the exchange of gifts between family members on the night of the 24th. Another common tradition is decorating a Christmas tree with bells, candles and ornaments.

events/diwali/meta.md

@@ -0,0 +1,7 @@
+---
+start_date: November 1
+end_date: November 7
+---
+**Diwali**
+
+[Diwali](https://en.wikipedia.org/wiki/Diwali) is an annual festival of lights and one of the major festivals celebrated by Hindus, Jains and Sikhs. It usually lasts five days and falls between mid-October and mid-November.

events/easter/meta.md

@@ -0,0 +1,7 @@
+---
+start_date: April 1
+end_date: April 30
+---
+**Easter**
+
+[Easter](https://en.wikipedia.org/wiki/Easter) is a Christian festival and holiday commemorating the resurrection of Jesus from the dead. It is celebrated on the first Sunday following the full moon that occurs on or just after the spring equinox. A common motive appearing in Easter customs are colourful eggs, associated with the themes of new life and birth.

events/evergreen/meta.md

@@ -0,0 +1,6 @@
+---
+fallback: true
+---
+**Evergreen**
+
+When no event is active, [Python Discord](https://pythondiscord.com/) is branded with its official logo.

events/hacktoberfest/meta.md

@@ -0,0 +1,7 @@
+---
+start_date: October 1
+end_date: October 31
+---
+**Hacktoberfest**
+
+[Hacktoberfest](https://hacktoberfest.digitalocean.com/) is an annual celebration of open source culture. The event encourages contributions to open source projects, and rewards participants with various unique prizes alongside an excellent opportunity to gain experience with collaborative software development.

events/new_year/meta.md

@@ -0,0 +1,7 @@
+---
+start_date: December 26
+end_date: December 31
+---
+**New Year**
+
+[New Year](https://en.wikipedia.org/wiki/New_Year) celebrations occur around the end of the calendar year, and the beginning of the next one. The event is associated with a rich variety of traditional and religious customs, often including fireworks, bright lights, and joyous atmosphere. New Year resolutions are a traditional promise of encouraging positive development and working towards personal goals in the upcoming year.

events/pride/meta.md

@@ -0,0 +1,7 @@
+---
+start_date: June 1
+end_date: June 30
+---
+**Pride**
+
+[LGBTQ+ pride](https://en.wikipedia.org/wiki/Gay_pride) is the promotion of the self-affirmation, dignity, equality, visibility, and rights of members of the LGBTQ+ community as a social group. It’s the predominant outlook that fuels a number of rights movements. In the United States, the event serves as a reminder of the [Stonewall riots](https://en.wikipedia.org/wiki/Stonewall_riots) of 1969.

events/requirements.txt

@@ -0,0 +1,3 @@
+# Python: 3.8
+python-frontmatter==1.0.0
+pyyaml==5.4.1

events/st_patricks_day/meta.md

@@ -0,0 +1,7 @@
+---
+start_date: March 10
+end_date: March 18
+---
+**Saint Patrick's Day**
+
+[Saint Patrick's Day](https://en.wikipedia.org/wiki/Saint_Patrick%27s_Day) is an annual event celebrating the culture and heritage of the Irish. On the 17th of March, the members of the Irish diaspora commemorate the death of [Saint Patrick](https://en.wikipedia.org/wiki/Saint_Patrick), the primary patron saint of Ireland. Celebrations commonly include public parades, festivals and traditional music. Parade members often dress in green attire decorated with the shamrock symbol.

events/valentines/meta.md

@@ -0,0 +1,7 @@
+---
+start_date: February 1
+end_date: February 15
+---
+**Valentine's Day**
+
+[Valentine's Day](https://en.wikipedia.org/wiki/Valentine%27s_Day) is an international celebration centered around romantic love. It is traditionally associated with red hearts, romance, flowers, candy or other sweet things, and the exchange of cards or messages, called *valentines*, that express love. It occurs annually on February 14th.