Document site architecture and other useful concerns for contributing

The thisweekinbevy site combines multiple disciplines and tools to work. Rust, CSS, HTML, JavaScript, SSR/hydration, "Islands", Dockerfiles, etc. No piece should be taken for granted in the contributing documentation: A person skilled in Rust may not know anything about CSS (and vice-versa). Expectations should be set for how the site works so that people aren't expecting a folder of markdown files.

The following is a brief, potentially incomplete, list of areas that need to be documented for potential contributors.

What/Why is thisweekinbevy

Why does thisweekinbevy exist?
- The Bevy community is very active. This is too much for some people to keep track of and there should be a lower-cadence summary for them. "check thisweekinbevy once a week" vs "read all of the discord messages for all of the relevant topics"
- Discord is great, but many people don't use Discord. New or soon-to-be Bevy users are also more likely to find Bevy and what they can do with Bevy if the great work the community is doing is visible outside of Discord.
- I (Chris) need to keep up to date anyway, so sharing the work that I do to keep up to date means that work doesn't need to be duplicated, if I can summarize it well enough.
What form does thisweekinbevy take?
- website, newsletter, rss feed, video, etc
- multiple formats make the issues more accessible. Video/audio can be good for people who want to keep up to date while performing another activity. Written word can be better for up-to-date and experienced Bevy practitioners to scan through.

Contributing Content

The goal of thisweekinbevy is to be part of the community, not separate, therefore community members should prioritize using official channels. The discord channels for showcases, devlogs, crate releases, etc should be the first option for the bevy community when sharing updates. thisweekinbevy also acknowledges that some members of the community do not use discord, and we should support them as well through being able to submit directly.

Technologies

Where do people go to find out about each piece? MDN, docs links, etc.

Leptos
CSS/Tailwind
sqlx/SQL
HTML
Dockerfiles

Concepts

Why does the site use a database?
- tldr; To be able to render multiple views (web, email, rss, etc)
- Also unlocks search in the future.
What is "islands" and why are we using it?
How do PRs/Issues on the Bevy repo get included in each issue?
[ ] What are GH Actions doing and why
What are Fly and Netlify?

Building/running

[ ] todo: We use mysql, and need a non-production mysql with some data for developing
cargo-leptos is the standard tool for building/testing/developing leptos apps.

This is a bit of a "mega issue" so after the first documentation push I will likely close this and create separate issues for anything left over. In the meantime, questions can be left in the comments here and I'll try to address them.

Why does the site use a database? tldr; To be able to render multiple views (web, email, rss, etc) Also unlocks search in the future.

I would have expected this site to be a static one. Both points above should not be an issue in a static page (see for example the Bevy cheatbook for search). I would agree though that it is a bit tricky with Leptos at the moment. Maybe some day I will get Cinnog to the point that it can help with all that.

Additional benefits would be open content (content is part of the repo) and easier participation through PRs. I could have opened a PR fixing my name in the last weekly Bevy news for example, which was the reason I came here in the first place 😄

A static page would also be simpler (and cheaper; free) to host and would have significantly better loading speed on a CDN for users in other parts of the world compared to a single server running somewhere in Europe.

I considered making it a static site originally, but decided against it considering Leptos' predisposition to running a server at the time I was working on it. I would've either had to build my own static site infrastructure on top, or use Cinnog which appeared around the same time. I was definitely looking at Cinnog when you first released it, but decided against it since it had its first publish around the same time and I wasn't sure if it was something you were thinking about continuing, how it would upgrade to new leptos versions, etc. I do think the Islands + bevy_ecs model is very interesting though. I did the original work a very long time ago that inspired Gatsby's use of GraphQL, so your comment in the README really speaks to me.

I would very much like to be able to use server functions even with Cinnog though. Islands are great for client-interactivity but occasionally submitting a form, even just for say: email subscription, would be very helpful.

I could have opened a PR fixing my name in the last weekly Bevy news for example, which was the reason I came here in the first place 😄

ack, apologies. I believe I've fixed it, if there's still an issue I'm happy to update:

PRs as contribution method for content

Re: PRs as the main form of contribution. I've seen this in other newsletters and it is definitely a major issue from multiple perspectives. The Rust gamedev newsletter (for example) has this soft list of rules summarized from their full contributing guide.

Write in third-person perspective.

Each line must be 80 characters or less, for ease of reviewing/diffing.

Only one image per section is allowed.

The maximum size is 300kb for static images and 2.5mb for GIFs.

The image should come before the text, and must have alt text for accessibility.

Prefer static images to GIFs, to keep the page load times down.

Each section should be under 1000 characters, and under 6 paragraphs.

This only applies to the rendered text, not the markup.

Keep formatting minimal - no bold/italics/etc.

Avoid long/nested bullet point lists - no changelogs!

So no gifs, no videos, and no large assets because it all has to fit in a git repo. Plus the additional overhead of needing to manually verify and optimize images, content structure, phrasing, and more for every PR. If I'm going to have to review and potentially modify every PR anyway, I'd much rather write the content myself to start with.

I think for Bevy specifically, and especially showcases, having short videos and gifs actually makes the site much more enjoyable to view. Its probably unlikely that thisweekinbevy "rehosts" any videos in full length, but small clips are often posted and overviews would be nice.

Also, I would much prefer to direct people towards official channels rather than submitting content PRs. Directing people to share their work in Bevy's #showcase and other similar channels means that everyone gets to benefit from more people sharing their work and the relationship between thisweekinbevy and the Bevy Discord is more symbiotic: thisweekinbevy points people to share their work in Discord or other official channels, and the information for thisweekinbevy comes from those channels (as well as other locations such as mastodon, youtube, individual sites, etc). Having a separate contribution method would enable people who don't use Discord, which is valuable as well, and for that I'd would like to have a website-submission based contribution mechanic instead.

In my mind, It would be far more useful to have a Discord bot that was allowed to scrape these specific channels' top-level posts for review, editing, and inclusion. The alternative of requiring all posters to double-submit to submit PRs is onerous from both the contribution and maintenance perspectives.

Similarly, it would be useful to have a webhook on the Bevy GitHub repo to track issue status and PR merges but I have a small CLI that can do that through the API today. I might expand this to other repos in the future if it makes sense, but the automation is important for sustainability.

[!NOTE]
To be clear, I haven't asked for either of those things (bot or webhooks) from the Bevy team. This is an unofficial newsletter and I'm not hinging anything on having that kind of access. Maybe if I run the newsletter for long enough or it becomes viewed as useful enough something could be worked out.

A static page would also be simpler (and cheaper; free) to host and would have significantly better loading speed on a CDN for users in other parts of the world compared to a single server running somewhere in Europe.

Hosting costs for thisweekinbevy are currently free, aside from database costs since PlanetScale just removed their free tier 😅 . Netlify is used as a CDN for static assets, so gains the benefits you've described here, while the server-compute is running in Fly.io's datacenters. I haven't scaled it out to multiple instances yet, so that server-compute-returned-html does suffer from longer load times across the world than a static file. The biggest cost is actually going to be email for the foreseeable future, which far outstrips compute and CDN costs, and which a static site won't help with.

Thanks for fixing the name :slightly_smiling_face:

I would very much like to be able to use server functions even with Cinnog though. Islands are great for client-interactivity but occasionally submitting a form, even just for say: email subscription, would be very helpful.

I don't see support for that in Cinnog since it is meant for static sites only. However, one could use serverless functions for functionality like this or have an API JAM stack style. That does not provide the nice integration of Leptos functions though.

That's some good points about the contribution method. I can understand your preference to write posts yourself. Having everything in official channels first also sounds great.

The biggest cost is actually going to be email for the foreseeable future, which far outstrips compute and CDN costs, and which a static site won't help with.

This is interesting for me. I never created anything like a newsletter and wasn't aware that sending out email would be more resource-intensive than something like a Leptos server/SQL database.

I really like the newsletter by the way. Thank you for the initiative!

rust-adventure / thisweekinbevy