WIP of https://github.com/rust-gamedev/rust-gamedev.github.io/issues/269

rust-gd-news-guide.draft.md

Contributing Guide

Workflow Overview

• In the last week of the month a coordination issue with an initial outline of this month's news is created by a coordinator.

  News are mostly collected from /r/rust_gamedev, @rust_gamedev on Twitter, and the "#showcase-only" Rust GameDev channel on Discord. Feel free to suggest sections if something cool isn't listed.

• During the following few days contributors take "🆓 free" sections and submit corresponding PRs.

  Leave a comment like "Taking {section_name_1} and {section_name_2}" in the coordination issue to claim free sections you are interested in. Claimed sections are marked as "🚧 WIP by @nickname" in the plan. This is done to avoid work duplication.

  You aren't required to be a project's author to write about it.

  Some free sections have a nickname with a question mark in brackets (like "🆓 free (@nickname?)") - it's just an invitation to write the corresponding section if you want, but anyone is free to take it.

• Submitted PRs are reviewed, tweaked if needed, and merged.

  Feel free to help with reviews.

• After all the contributors' PRs are processed, coordinators take and write all sections that no one have submitted.

• On the first week of the next month, the final draft is reviwed and merged.

• A small PR that adds links to discussions (see the comment at the bottom of the draft) is made.

• A draft of the next newsletter is added to the repo.

PRs

• The current draft is /posts/newsletter-{N}/index.md, where {N} is this issue's number.

• Place the sections accordingly to how they're ordered in the coodination issue.

• PRs are sent against the source branch.

• Mention the coordintion issue in the PR's description to link it all together.

• Don't send PRs from your main branch, create a unique branch (named like n14_zemeroth, n12_veloren, etc) for each PR. This allows sending multiple similtaneous PRs and simplifies the creation of the next PRs.

• Make sure that the "Allow edits from maintainers" box is checked (avoid using org accounts if possible) - it makes updating/tweaking the PR easier for the coordinators.

• Don't bother resolving merge conflicts in your PR as they will likely to re-appear after yet another PR is merged. It easier for a coordinator do the PR right before merging it.

• Don't worry about cleaning up the PR's commit history - we're squashing the PR into one commit before the merge anyway.

Style

Please, try to maintain a consistent style with the rest of the newsletter.

• In general, the sections are expected to have this structure:

  ### [Project]
  
  ![alt image description](image.jpeg)
  _image caption_
  
  [Project] by [@Author] is an awesome Rust project.
  
  A paragraph or two with a summary and [useful links][other-link].
  
  _Discussions:
  [/r/rust](https://reddit.com/r/rust/123456),
  [twitter](https://twitter.com/todo/status/123456)_
  
  [Project]: https://first.link
  [@Author]: https://author.link
  [other-link]: https://other.link

  It was decided to use an image + short TLDR-overview section scheme because people in general don't follow the links in digests. This way readers should get a general idea of what's going on just by scrolling through the issue.

  But please don't make the sections too long/detailed, otherwise the newsletter as a whole will too bloated. It's not a strict limit, but please try to keep the sections under 200 words.

• Games are a quite visual-oriented media so the default section structure includes one image before the text. One image is preferred, two images are usually the max.

  Keep the file size in mind: GIFs should be <2MB in size (ezgif.com is a nice online tool for quick editing/optimizaton), static images should be optimized too (prefer jpeg to png for complex screenshots, etc).

  All images should have a short but meaningful and descriptive alt text (more info about alt text here and here).

  Image files should be placed in the same folder as the post and be named using "-" to split the words, not "_".

• Markdown doesn't natively support videos, so the usual workaround is to include a clickable screenshot of the video: example 1, example 2.

• Contributions should be written clearly and simply so that they are accessible to readers for whom English is not their first language.

• Keep in mind that more than a half of readers consume the newsletter using mobile devices. So try to avoid things that doesn't work well with small screens: nested lists, long titles, images with important small details, code blocks with long lines, etc.

• Don't use fourth-level headers. Divide a section into subsections using a ------ line if needed.

• Avoid using blold, italic, etc rich formatting if possible.

• Write from a third-person perspecive even if you're writing about your project's updates.

• Use singular "they" if you're not sure what are the person's pronouns.

• If the project was already featured in the newsletter, use a one-sentence description in the begining of the section as a reminder for readers and describe only the updates next.

• It's ok to add a donation/sponsorship link, but avoid making it a central point of your section.

• Discussion links should be added at the end of the (sub)section only if they alredy contain some actual interesting discussions.

Formatting

As with the style, keeping the MD formatting consistent over the newsletter is important too. So, please, try to follow the formatting guidelines but don't warry too much about them: they are easier to fix for coordinators than issues with the content itself.

• Some of the basic formatting rules are enforced on CI using markdownlint.

  If you're working on your PR locally, consider installing one of the markdownlint extensions for your editor (vscode, sublime, vim), otherwise please check the results of the CI run.

• Insert line breaks (softbreak) at 80 chars.

• Use reference-style links and group them into blocks at the end of the (sub)sections.

  URLs in these references block can break the 80 chars rule:

  [Rapier][rapier], a new pure-rust physics engine,
  released an [official Bevy plugin][bevy-rapier].
  
  [rapier]: https://rapier.rs
  [bevy-rapier]: https://www.dimforge.com/blog/2020/08/25/announcing-the-rapier-physics-engine/#reaching-out-to-other-communities-bevy-and-javascript

• Use only dashes (-) for list items, ** for bold, and _ for italic.

• Don't use double linebreaks and trailing whitespaces.

• Only use inline code formatting ("`mycrate`") for crate names if this helps to avoid confusion.

• Don't use GitHub shortcodes (like :tada:) - they won't be rendered by normal MD renderers. Use plain unicode emojis instead.

• Consequent list item lines are indented with two spaces. Example:

  - Aaaaaaaa aaaaaaa aaaaaaaaaa (Aaaaaaa) aaaaaaaa aaaa
    aaaaaa aaaa. Aaaaaa aaaa aa'a aaaaaaaa aaaaaa aaa aaaaaaa.
    aaaaa aaaaa aa aaaaaaaaa, aaaaaaa.
  - Aaaaaaaaaaaaa aaaaaaaaaaa aaa aaaaaaa aaaaa.
    - Aaaaaaaaaaaaaa aaaaaaa aaaaaaaa AaaAA aaaa aaa aaa'a
      aaaa aaaaa aaaaa `aaa_aaaaa` aaaa, aaaa `aaaa_aaaaa_aaa`,
      aaaaa.
    - Aaaaaaa aaaaa aaaaaa (aaaaaaa aaaaaaa).

• Try to strip unneeded parts of URLs. For example, remove www., old., and description parts of Reddit links:

  • https://old.reddit.com/r/rust/comments/i7bcwu/introducing_bevy_a_refreshingly_simple_datadriven
  • https://reddit.com/r/rust/comments/i7bcwu/introducing_bevy

• Use a consistent list item termination (don't mix items ending with ";", ",", ".", etc).

Ping the coordinators in the current coordination issue or WG's Discord channel if there're any questions. If something in this guide in unclear file an issue and we'll try to improve it.