|
| 1 | +# Contributing Guide |
| 2 | + |
| 3 | +## Workflow Overview |
| 4 | + |
| 5 | +- In the last week of the month, a [coordination issue][coordination] |
| 6 | + with an initial outline of this month's news is created by a coordinator. |
| 7 | + |
| 8 | + News are mostly collected from [/r/rust_gamedev], [@rust_gamedev] on Twitter, |
| 9 | + and the "\#showcase-only" [Rust GameDev channel on Discord][gd-discord]. |
| 10 | + Feel free to suggest sections if something cool isn't listed. |
| 11 | + |
| 12 | +- During the following few days, contributors take "🆓 **free**" sections |
| 13 | + and submit corresponding PRs. |
| 14 | + |
| 15 | + Leave a comment like "Taking {section\_name\_1} and {section\_name\_2}" |
| 16 | + in the coordination issue to claim free sections you are interested in. |
| 17 | + Claimed sections are marked as "🚧 WIP by @nickname" in the plan. |
| 18 | + This is done to avoid work duplication. |
| 19 | + |
| 20 | + You aren't required to be a project's author to write about it. |
| 21 | + |
| 22 | + Some free sections have a nickname with a question mark in brackets |
| 23 | + (like "🆓 **free** (@nickname?)") - |
| 24 | + it's just an invitation to write the corresponding section if you want, |
| 25 | + but anyone is free to take it. |
| 26 | + |
| 27 | +- Submitted PRs are reviewed, tweaked if needed, and merged. |
| 28 | + |
| 29 | + Feel free to help with reviews. |
| 30 | + |
| 31 | +- After all the contributors' PRs are processed, coordinators |
| 32 | + take and write all sections that no one has submitted. |
| 33 | + |
| 34 | +- In the first week of the next month, the final draft is reviewed and merged. |
| 35 | + |
| 36 | +- A small PR that adds links to discussions |
| 37 | + (see the comment at the bottom of the draft) is made. |
| 38 | + |
| 39 | +- A draft of the next newsletter is added to the repo. |
| 40 | + |
| 41 | +## PRs |
| 42 | + |
| 43 | +- The current draft is `/posts/newsletter-{N}/index.md`, |
| 44 | + where `{N}` is this issue's number. |
| 45 | + |
| 46 | +- Place the sections accordingly to how they're ordered |
| 47 | + in the coordination issue. |
| 48 | + |
| 49 | +- PRs are sent against the `source` branch. |
| 50 | + |
| 51 | +- Mention the coordination issue in the PR's description to link it all together. |
| 52 | + |
| 53 | +- Don't send PRs from your main branch, create a unique branch |
| 54 | + (named like `n14_zemeroth`, `n12_veloren`, etc) for each PR. |
| 55 | + This allows sending multiple simultaneous PRs |
| 56 | + and simplifies the creation of the next PRs. |
| 57 | + |
| 58 | +- Make sure that the "Allow edits from maintainers" box is checked |
| 59 | + ([avoid using org accounts][gh-org] if possible) |
| 60 | + \- it makes updating/tweaking the PR easier for the coordinators. |
| 61 | + |
| 62 | +- Don't bother resolving merge conflicts in your PR |
| 63 | + as they will likely to re-appear after yet another PR is merged. |
| 64 | + It easier for a coordinator to update the PR right before merging it. |
| 65 | + |
| 66 | +- Don't worry about cleaning up the PR's commit history |
| 67 | + \- we're squashing the PR into one commit before the merge anyway. |
| 68 | + |
| 69 | +[coordination]: https://github.com/rust-gamedev/rust-gamedev.github.io/issues?q=label%3Acoordination |
| 70 | +[@rust_gamedev]: https://twitter.com/rust_gamedev |
| 71 | +[/r/rust_gamedev]: https://reddit.com/r/rust_gamedev |
| 72 | +[gd-discord]: https://discord.gg/yNtPTb2 |
| 73 | +[gh-org]: https://github.com/isaacs/github/issues/1681 |
| 74 | + |
| 75 | +## Style |
| 76 | + |
| 77 | +Please, try to maintain a consistent style with the rest of the newsletter. |
| 78 | + |
| 79 | +- In general, the sections are expected to have this structure: |
| 80 | + |
| 81 | + ```markdown |
| 82 | + ### [Project] |
| 83 | + |
| 84 | +  |
| 85 | + _image caption_ |
| 86 | + |
| 87 | + [Project] by [@Author] is an awesome Rust project. |
| 88 | + |
| 89 | + A paragraph or two with a summary and [useful links][other-link]. |
| 90 | + |
| 91 | + _Discussions: |
| 92 | + [/r/rust](https://reddit.com/r/rust/123456), |
| 93 | + [twitter](https://twitter.com/todo/status/123456)_ |
| 94 | + |
| 95 | + [Project]: https://first.link |
| 96 | + [@Author]: https://author.link |
| 97 | + [other-link]: https://other.link |
| 98 | + ``` |
| 99 | + |
| 100 | + It was decided to use an image + short TLDR-overview section scheme |
| 101 | + because people, in general, don't follow the links in digests. |
| 102 | + This way readers should get a general idea of what's going on |
| 103 | + just by scrolling through the issue. |
| 104 | + |
| 105 | + But please don't make the sections too long/detailed, |
| 106 | + otherwise, the newsletter as a whole will become too bloated. |
| 107 | + It's not a strict limit, but please try to keep the sections under 200 words. |
| 108 | + |
| 109 | +- Games are quite visual-oriented media |
| 110 | + so the default section structure includes one image before the text. |
| 111 | + One image is preferred, two images are usually the max. |
| 112 | + |
| 113 | + Keep the file size in mind: GIFs should be <2MB in size |
| 114 | + ([ezgif.com] is a nice online tool for quick editing/optimization), |
| 115 | + static images should be optimized too |
| 116 | + (prefer jpeg to png for complex screenshots, etc). |
| 117 | + |
| 118 | + All images should have a short but meaningful and descriptive alt text |
| 119 | + (more info about alt text [here](https://moz.com/learn/seo/alt-text) |
| 120 | + and [here](https://webaim.org/techniques/alttext/)). |
| 121 | + |
| 122 | + Image files should be placed in the same folder as the post |
| 123 | + and be named using "\-" to split the words, not "\_". |
| 124 | + |
| 125 | +- Markdown doesn't natively support videos, |
| 126 | + so the usual workaround is to include a clickable screenshot of the video: |
| 127 | + [example 1](https://rust-gamedev.github.io/posts/newsletter-012/#ochre-4k-intro), |
| 128 | + [example 2](https://rust-gamedev.github.io/posts/newsletter-012/#rust-n-games-talk). |
| 129 | + |
| 130 | +- Contributions should be written clearly and simply so that |
| 131 | + they are accessible to readers for whom English is not their first language. |
| 132 | + |
| 133 | +- Keep in mind that more than half of readers consume the newsletter |
| 134 | + using mobile devices. |
| 135 | + So try to avoid things that don't work well with small screens: |
| 136 | + nested lists, long titles, images with important small details, |
| 137 | + code blocks with long lines, etc. |
| 138 | + |
| 139 | +- Don't use fourth-level headers. |
| 140 | + Divide a section into subsections using a `------` line if needed. |
| 141 | + |
| 142 | +- Avoid using bold, italic, etc rich formatting if possible. |
| 143 | + |
| 144 | +- Write from a third-person perspective even if you're writing |
| 145 | + about your project's updates. |
| 146 | + |
| 147 | +- Use singular "they" if you're not sure what the person's pronouns are. |
| 148 | + |
| 149 | +- If the project was already featured in the newsletter, |
| 150 | + use a one-sentence description at the beginning of the section |
| 151 | + as a reminder for readers |
| 152 | + and describe only the updates next. |
| 153 | + |
| 154 | +- It's ok to add a donation/sponsorship link, |
| 155 | + but avoid making it a central point of your section. |
| 156 | + |
| 157 | +- Discussion links should be added at the end of the (sub)section only if |
| 158 | + they already contain some actual interesting discussions. |
| 159 | + |
| 160 | +[ezgif.com]: https://ezgif.com |
| 161 | + |
| 162 | +## Formatting |
| 163 | + |
| 164 | +As with the style, keeping the MD formatting consistent over the newsletter |
| 165 | +is important too. |
| 166 | +So, please, try to follow the formatting guidelines |
| 167 | +but don't worry too much about them: |
| 168 | +they are easier to fix for coordinators than issues with the content itself. |
| 169 | + |
| 170 | +- Some of the basic formatting rules are enforced on CI using [markdownlint]. |
| 171 | + |
| 172 | + If you're working on your PR locally, consider installing |
| 173 | + one of the markdownlint extensions for your editor |
| 174 | + ([vscode][vscode-lint], [sublime][sublime-lint], [vim][vim-lint]), |
| 175 | + otherwise please check the results of the CI run. |
| 176 | + |
| 177 | +- Insert line breaks ([softbreak]) at 80 chars. |
| 178 | + |
| 179 | +- Use [reference-style links][md-reflinks] and group them into blocks |
| 180 | + at the end of the (sub)sections. |
| 181 | + |
| 182 | + URLs in these references block can break the 80 chars rule: |
| 183 | + |
| 184 | + ```markdown |
| 185 | + [Rapier][rapier], a new pure-rust physics engine, |
| 186 | + released an [official Bevy plugin][bevy-rapier]. |
| 187 | + |
| 188 | + [rapier]: https://rapier.rs |
| 189 | + [bevy-rapier]: https://www.dimforge.com/blog/2020/08/25/announcing-the-rapier-physics-engine/#reaching-out-to-other-communities-bevy-and-javascript |
| 190 | + ``` |
| 191 | + |
| 192 | +- Use only dashes (`-`) for list items, `**` for bold, and `_` for italic. |
| 193 | + |
| 194 | +- Don't use double linebreaks and trailing whitespaces. |
| 195 | + |
| 196 | +- Only use inline code formatting ("\`mycrate\`") for crate names |
| 197 | + if this helps to avoid confusion. |
| 198 | + |
| 199 | +- Don't use GitHub shortcodes (like `:tada:`) - they won't be rendered |
| 200 | + by normal MD renderers. Use plain Unicode emojis instead. |
| 201 | + |
| 202 | +- Consequent list item lines are indented with two spaces. Example: |
| 203 | + |
| 204 | + ```markdown |
| 205 | + - Aaaaaaaa aaaaaaa aaaaaaaaaa (Aaaaaaa) aaaaaaaa aaaa |
| 206 | + aaaaaa aaaa. Aaaaaa aaaa aa'a aaaaaaaa aaaaaa aaa aaaaaaa. |
| 207 | + aaaaa aaaaa aa aaaaaaaaa, aaaaaaa. |
| 208 | + - Aaaaaaaaaaaaa aaaaaaaaaaa aaa aaaaaaa aaaaa. |
| 209 | + - Aaaaaaaaaaaaaa aaaaaaa aaaaaaaa AaaAA aaaa aaa aaa'a |
| 210 | + aaaa aaaaa aaaaa `aaa_aaaaa` aaaa, aaaa `aaaa_aaaaa_aaa`, |
| 211 | + aaaaa. |
| 212 | + - Aaaaaaa aaaaa aaaaaa (aaaaaaa aaaaaaa). |
| 213 | + ``` |
| 214 | + |
| 215 | +- Try to strip unneeded parts of URLs. |
| 216 | + For example, remove `www.`, `old.`, and description parts of Reddit links: |
| 217 | + |
| 218 | + - `https://old.reddit.com/r/rust/comments/i7bcwu/introducing_bevy_a_refreshingly_simple_datadriven` |
| 219 | + - `https://reddit.com/r/rust/comments/i7bcwu/introducing_bevy` |
| 220 | + |
| 221 | +- Use a consistent list item termination |
| 222 | + (don't mix items ending with ";", ",", ".", etc). |
| 223 | + |
| 224 | +[markdownlint]: https://github.com/DavidAnson/markdownlint |
| 225 | +[vscode-lint]: https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint |
| 226 | +[sublime-lint]: https://packagecontrol.io/packages/SublimeLinter-contrib-markdownlint |
| 227 | +[vim-lint]: https://github.com/fannheyward/coc-markdownlint |
| 228 | +[softbreak]: https://spec.commonmark.org/0.29/#soft-line-breaks |
| 229 | +[md-reflinks]: https://www.markdownguide.org/basic-syntax/#reference-style-links |
| 230 | + |
| 231 | +Ping the coordinators in the current coordination issue |
| 232 | +or WG's Discord channel if there are any questions. |
| 233 | +If something in this guide is unclear file an issue |
| 234 | +and we'll try to improve it. |
0 commit comments