Our timeline was added following our 100K members milestone in PR #381. @ks129suggested that we should dynamically load the timeline with YAML/Markdown files instead of using raw HTML, however it looks like we went ahead with the latter due to time constraints.
@ichard26 lead the project which updated the timeline most recently (#1065). I reached out to see what they think of using YAML/Markdown instead, and they mentioned that updating the timeline again in the future would be a lot easier if it weren't in raw HTML. I propose that we should consider switching to a system similar to our content and resources app for the timeline.
Here's a general idea of how it could look like. Use the pydis_site/apps/home/timeline directory to store markdown files with YAML frontmatter, each file representing a timeline item. The first two could look like this:
2023-07-11_new-paste-service.md
---
date: 2023-07-11
icon: fa fa-comments
icon_color: pastel-pink
---
# Switch to new paste service
We migrate over to [pinnwand](https://github.com/supakeen/pinnwand) as the
service that powers our paste bin over at <https://paste.pythondiscord.com/>.
We made the switch as it comes with native light/dark modes, support for
multi-file pastes, additional support for text highlighting languages, and
plus, it's written in Python!
2023-01-30_retirement-of-joe-and-sebastiaan.md
---
date: 2023-01-30
icon: pydis
---
# Retirement of Joe and Sebastiaan
Having been at the helm of Python Discord for over 5 and 3 years respectively,
Joe and Sebastiaan retire and step down. They gain the **@Founders** role and
continue as advisors to the **@Directors**, the new name of the original
**@Owners** role.
At the same time, Mina and Zig join Leon as co-directors.
The file names can be completely arbitrary, because the view would only be looking at the YAML frontmatter and the markdown content when rendering the timeline. The above just shows an example of a file name convention we could adopt, which helps chronological ordering in directory listings.
For the Advent of Code 2020 item's special date format, we could include a key something like date_label: December 1st - 25th, 2020. If it's not specified (the case for all other entries) we can use strftime with date key.
The files can be read on startup and stored into a data structure that would sort the entries reverse-chronologically. In the view, we pass in the entries as context to a new template file for the timeline. Finally the template would fill in all the entries in HTML.
There are good references for how this can be done in our content and resources apps.
The CSS
I tried finding any form of discussion regarding the initial timeline implementation, but failed, maybe it was in core dev channels? I did however notice that the CSS seems to be copied from this tutorial. Despite Joe and other contributors having done some major improvements, there are still quite a number of issues with the CSS that bugs me a lot, most notably:
Is 3000+ lines of CSS really needed just for this timeline page? We're carrying a 70+ kB baggage of a resource around for this page as extra CSS in addition to the compulsory Bulma and FontAwesome resources.
Border radius, box shadows, background color are all inconsistent with the rest of the site.
The CSS isn't really very well written and there are numerous redundant rules and CSS variables just lying around everywhere. It was quite a frustrating experience working with the file. Considering our code quality standards for our other repos, I believe that a similar amount of rigor can be expected from this project.
I understand that we were under time constraints during the initial implementation. But IMO, now's a good opportunity to make this timeline our own and do a serious refactor of it all before the next time someone comes around and have to do all the hard work updating the timeline in the future.
(note: the proposal was born out of a frustrating experience from working with this timeline for my dark theme PR. perhaps others don't see too much of a problem with it currently, but I hope to make life easier for whoever that might touch it later)
The entries
Our timeline was added following our 100K members milestone in PR #381. @ ks129 suggested that we should dynamically load the timeline with YAML/Markdown files instead of using raw HTML, however it looks like we went ahead with the latter due to time constraints.
@ichard26 lead the project which updated the timeline most recently (#1065). I reached out to see what they think of using YAML/Markdown instead, and they mentioned that updating the timeline again in the future would be a lot easier if it weren't in raw HTML. I propose that we should consider switching to a system similar to our
content
andresources
app for the timeline.Here's a general idea of how it could look like. Use the
pydis_site/apps/home/timeline
directory to store markdown files with YAML frontmatter, each file representing a timeline item. The first two could look like this:2023-07-11_new-paste-service.md
2023-01-30_retirement-of-joe-and-sebastiaan.md
The file names can be completely arbitrary, because the view would only be looking at the YAML frontmatter and the markdown content when rendering the timeline. The above just shows an example of a file name convention we could adopt, which helps chronological ordering in directory listings.
For the Advent of Code 2020 item's special date format, we could include a key something like
date_label: December 1st - 25th, 2020
. If it's not specified (the case for all other entries) we can use strftime withdate
key.The files can be read on startup and stored into a data structure that would sort the entries reverse-chronologically. In the view, we pass in the entries as context to a new template file for the timeline. Finally the template would fill in all the entries in HTML.
There are good references for how this can be done in our
content
andresources
apps.The CSS
I tried finding any form of discussion regarding the initial timeline implementation, but failed, maybe it was in core dev channels? I did however notice that the CSS seems to be copied from this tutorial. Despite Joe and other contributors having done some major improvements, there are still quite a number of issues with the CSS that bugs me a lot, most notably:
I understand that we were under time constraints during the initial implementation. But IMO, now's a good opportunity to make this timeline our own and do a serious refactor of it all before the next time someone comes around and have to do all the hard work updating the timeline in the future.
(note: the proposal was born out of a frustrating experience from working with this timeline for my dark theme PR. perhaps others don't see too much of a problem with it currently, but I hope to make life easier for whoever that might touch it later)