Skip to content

Update the contributing guide #638

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
May 31, 2021
Merged

Update the contributing guide #638

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d4b7e66
Update the contributing guide
17cupsofcoffee May 22, 2021
7ac7707
Fix lint issues
17cupsofcoffee May 22, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
307 changes: 110 additions & 197 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,234 +1,147 @@
# Contributing Guide

## Workflow Overview
Thank you for contributing to the newsletter! 💖

- In the last week of the month, a [coordination issue][coordination]
with an initial outline of this month's news is created by a coordinator.
- [Writing Newsletter Sections](#writing-newsletter-sections)
- [Templates](#templates)
- [Style Guidelines](#style-guidelines)
- [Becoming an Editor](#becoming-an-editor)

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

- During the following few days, contributors take "🆓 **free**" sections
and submit corresponding PRs.
At the end of each month, a [coordination issue] will be created by one of
the newsletter editors. This signals that it's time to start writing and
submitting sections!

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.
The coordination issue will contain the deadlines for submissions, as well
as an initial outline for the newsletter's content. Each item in the outline
will have a marker showing whether it is free for someone to pick up, and a
suggested author.

You aren't required to be a project's author to write about it.
> This outline is just a first draft - feel free to submit sections that
aren't listed!

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.
If you would like to write a section for the newsletter, leave a comment on
the coordination issue stating what you're planning to write about. This
allows the editors to keep track of what's in progress, and prevents
duplicated work.

- Submitted PRs are reviewed, tweaked if needed, and merged.
Next, make your changes to the newsletter's main Markdown file - this is
located in [`/content/news/{N}/index.md`][newsletter-source], where `{N}` is
the newsletter's issue number. You can either do this by forking the repo,
or by using GitHub's built-in editor. If you're picking up a section from
the coordination issue's outline, use the provided links as a starting
point.

Feel free to help with reviews.
> **Please follow the [templates](#templates) and
[style guidelines](#style-guidelines) provided below when writing your
section, for consistency with the rest of the newsletter!**

- After all the contributors' PRs are processed, coordinators
take and write all sections that no one has submitted.
Once your edits are done, send a PR against the `source` branch (not
`master`). Make sure that you mention the coordination issue in the PR
description, and tick the 'Allow edits from maintainers' box to make it
easier for editors to fix any issues.

- In the first week of the next month, the final draft is reviewed and merged.
Upon submitting your PR, a CI build will run, checking that your changes
meet the style guidelines. Please double check that this passes, and watch
your GitHub notifications for any further review comments from the editors.

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

- A draft of the next newsletter is added to the repo.
#### Games, Apps or Libraries

## PRs
```md
### [Game name]

- The current draft is `/posts/newsletter-{N}/index.md`,
where `{N}` is this issue's number.
![alt text](img)
_optional image label_

- Place the sections accordingly to how they're ordered
in the coordination issue.
[Game name] ([GitHub], [Discord], [Twitter]) by [@nickname]
is... {short project description in one sentence}.

- PRs are sent against the `source` branch.
{An overview of the recent updates with links to more details}.

- Mention the coordination issue in the PR's description to link it all together.
_Discussions: [/r/rust_gamedev](link), [Twitter](link), [etc](link)_

- 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 simultaneous PRs
and simplifies the creation of the next PRs.
[Game name]: http://example.com
```

- Make sure that the "Allow edits from maintainers" box is checked
([avoid using org accounts][gh-org] if possible)
\- it makes updating/tweaking the PR easier for the coordinators.
#### Articles, Blog Posts or Videos

- 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 to update the PR right before merging it.
```md
### [Article name]

- Don't worry about cleaning up the PR's commit history
\- we're squashing the PR into one commit before the merge anyway.
![alt text](img)
_optional image label_

[coordination]: https://github.com/rust-gamedev/rust-gamedev.github.io/issues?q=label%3Acoordination
[@rust_gamedev]: https://twitter.com/rust_gamedev
[/r/rust_gamedev]: https://reddit.com/r/rust_gamedev
[gd-discord]: https://discord.gg/yNtPTb2
[gh-org]: https://github.com/isaacs/github/issues/1681

## Style

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

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

```markdown
### [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 become too bloated.
It's not a strict limit, but please try to keep the sections under 200 words.

- Games are 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/optimization),
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](https://moz.com/learn/seo/alt-text)
and [here](https://webaim.org/techniques/alttext/)).

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](https://rust-gamedev.github.io/posts/newsletter-012/#ochre-4k-intro),
[example 2](https://rust-gamedev.github.io/posts/newsletter-012/#rust-n-games-talk).

- Contributions should be written clearly and simply so that
they are accessible to readers for whom English is not their first language.
[@nickname] published an [article] about...
{overview what the resource is about}.

- Keep in mind that more than half of readers consume the newsletter
using mobile devices.
So try to avoid things that don't work well with small screens:
nested lists, long titles, images with important small details,
code blocks with long lines, etc.
_Discussions: [/r/rust_gamedev](link), [Twitter](link), [etc](link)_

- Don't use fourth-level headers.
Divide a section into subsections using a `------` line if needed.
[Article name]: http://example.com
```

- Avoid using bold, italic, etc rich formatting if possible.
### Style Guidelines

- Write from a third-person perspective even if you're writing
about your project's updates.
- Run [MarkdownLint] against your changes with [our config][md-config].
- Most editors have a MarkdownLint plugin available
(e.g. [VS Code][md-vscode], [Sublime Text][md-sublime],
[Vim][md-vim]).
- Write in third-person perspective.
- Lines should be no more than 80 characters long.
- The rendered text should be under 1000 characters, and under 6
paragraphs - this doesn't include markup/links/etc.
- Do not use rich formatting (bold, italics, etc).
- Avoid having multiple/nested bullet points.
- This guideline may be relaxed if your project has multiple parts that
aren't independent enough for their own sections.
- Only include one image (<300kb) or GIF (<2.5mb).
- Images should be placed before text, with an optional caption and
mandatory alternate text for accessibility.
- Unless essential to demonstrating your project, prefer static images
over GIFs, to keep the file size down.
- Use singular 'they' if you’re not sure what someone's pronouns are.
- If a project has been featured in previous newsletters, try to focus on
what's new rather than repeating previous content.
- Donation/sponsorship links are allowed, but should not be the focus of a
section.

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

- If the project was already featured in the newsletter,
use a one-sentence description at the beginning 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 already contain some actual interesting discussions.

[ezgif.com]: https://ezgif.com

## 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 worry 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][vscode-lint], [sublime][sublime-lint], [vim][vim-lint]),
otherwise please check the results of the CI run.

- Insert line breaks ([softbreak]) at 80 chars.

- Use [reference-style links][md-reflinks] and group them into blocks
at the end of the (sub)sections.

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

```markdown
[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.
[coordination issue]: https://github.com/rust-gamedev/rust-gamedev.github.io/issues?q=label%3Acoordination
[@rust_gamedev]: https://twitter.com/rust_gamedev
[/r/rust_gamedev]: https://reddit.com/r/rust_gamedev
[gd-discord]: https://discord.gg/yNtPTb2
[newsletter-source]: https://github.com/rust-gamedev/rust-gamedev.github.io/tree/source/content/news
[markdownlint]: https://github.com/DavidAnson/markdownlint
[md-config]: https://github.com/rust-gamedev/rust-gamedev.github.io/blob/source/.markdownlint.json
[md-vscode]: https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint
[md-sublime]: https://packagecontrol.io/packages/SublimeLinter-contrib-markdownlint
[md-vim]: https://github.com/fannheyward/coc-markdownlint

- Only use inline code formatting ("\`mycrate\`") for crate names
if this helps to avoid confusion.
## Becoming an Editor

- Don't use GitHub shortcodes (like `:tada:`) - they won't be rendered
by normal MD renderers. Use plain Unicode emojis instead.
The newsletter is organized by a small volunteer group of editors. If you
have some time to spare each month and want to help out, please get in
touch, either via the [issue tracker][issues] or the
[gamedev working group's Discord channel][wg-discord]. We'd be happy to have
you!

- Consequent list item lines are indented with two spaces. Example:
Editors have two main responsibilities:

```markdown
- 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).
```
- Gathering news and links over the course of the month
- Reviewing, fixing and merging PRs

- Try to strip unneeded parts of URLs.
For example, remove `www.`, `old.`, and description parts of Reddit links:
Each month, one of the editors will be designated as the 'lead editor'. Their additional
responsibilities are:

- `https://old.reddit.com/r/rust/comments/i7bcwu/introducing_bevy_a_refreshingly_simple_datadriven`
- `https://reddit.com/r/rust/comments/i7bcwu/introducing_bevy`
- Creating and maintaining the coordination issue
- Preparing the final draft
- Publishing the newsletter
- Linking to the newsletter on social media
- Creating the files for next month's newsletter

- Use a consistent list item termination
(don't mix items ending with ";", ",", ".", etc).
The lead editor role rotates every month, to spread the workload fairly, but
you can opt out if you want.

[markdownlint]: https://github.com/DavidAnson/markdownlint
[vscode-lint]: https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint
[sublime-lint]: https://packagecontrol.io/packages/SublimeLinter-contrib-markdownlint
[vim-lint]: https://github.com/fannheyward/coc-markdownlint
[softbreak]: https://spec.commonmark.org/0.29/#soft-line-breaks
[md-reflinks]: https://www.markdownguide.org/basic-syntax/#reference-style-links

Ping the coordinators in the current coordination issue
or WG's Discord channel if there are any questions.
If something in this guide is unclear file an issue
and we'll try to improve it.
[issues]: https://github.com/rust-gamedev/rust-gamedev.github.io/issues
[wg-discord]: https://discord.gg/DACMGKM5en