[RFC] Embedded Rust Community Plan

[japaric]

EDIT: Updated by @jamesmunns. See this comment for more details

The following items have been generally discussed over the past few months, and we would like to come up with a plan for how to support the embedded rust community moving forward. This is an initial collection, but we would love your input on the following:

• Would you like to see these components?
• What tools would make sense for these components?
• Are there any alternatives to these components that could be more valuable?
• Any other comments you would like to share

Components

1. NEW: A forum

Set up at https://forum.rust-embedded.org. Perhaps powered by Discourse.

Meant for topics slightly larger than a single blog post or IRC communication, but slightly too ephemeral for a wiki post.

Content driven by the community

2. EXISTING: A Chat Room

We currently have two active chat communities:

• IRC:: #rust-embedded @ irc.mozilla.org.
• Discord:: #wg-embedded @ rust-lang discord server

Chat is meant for direct questions, random chat, technical questions.

NOTE: This RFC does not intend to propose new or different chat systems

3. NEW: A blog

A static site, set up at https://blog.rust-embedded.org. Static site generator TBD, likely hosted on github pages, probably at rust-embedded/blog github space. Covers posts such as the newsletter, calls to action, and technical posts by guest contributors (they can send in posts by filing a PR to the blog project, reviewed by the resources team.

We should have an RSS feed.

Comments still TBD.

Content driven by the resources team and the community

4. NEW: A Wiki

A wiki page driven by github, probably residing in the rust-embedded/wg repository, which would locate it at https://github.com/rust-embedded/wg/wiki. We could add an alias at https://wiki.rust-embedded.org.

The wiki should cover things like "how does this specific chip work", or "working with these sensors", or "how to debug using a JLink debugger and GDB".

Content created and curated by the community. No guarantees on correctness.

5. MOVED: Our Bookshelf

These are static mdbook projects that will be hosted at https://*.rust-embedded.org. Currently we (will) have:

• The Discovery Book (learn embedded through rust)
• The Rust Embedded Book (learn embedded rust)
• The Embedonomicon (learn the low level details of embedded rust)

These resources should cover general knowledge of embedded rust, e.g. nothing specific to a tool, chip/family of chips, sensors, etc. May cover general basics such as interactions with a CPU, peripherals, etc.

This content is written by anyone, and curated for completeness and correctness by the resources team. We should guarantee correctness, at least with a similar level of guarantee that "The Rust Programming Language" book does.

6. NEW: Two Websites

We will have the following two pages accessible to us:

• https://rust-embedded.org
• The WIP new rust site, likely https://rust-lang.org/what/embedded

https://rust-lang.org/what/embedded

I see this as a promotional website. It should have examples and content, however it serves as a landing point for people not currently involved with rust, or embedded rust. We can contribute content here, but we do not "own" this page.

https://rust-embedded.org

I see this as the technical landing page. If someone asks "how do I do embedded rust", this becomes a singular place we can link them to. From here, we can link to all of the spaced I enumerated above, as well our official repositories, and content such as the "Awesome Embedded Rust" list.

This should be a static site, generated similarly with tools similar to above. Would probably live at rust-embedded/website. Hosted at https://rust-embedded.org.

Content here would be written and maintained by members of the whole embedded wg, and maintained by the resources team.

7. EXISTING: Social Media

So far we only have @rustembedded at twitter. Do we need anything else?

More or less reposts everything from the blog, general interactions with the community.

Tooling:

To achieve the items above, we will need the following categories of tools:

1. A static site, including:
   • a generator, e.g. Jekyll, Hugo, Gutenberg
   • a host, e.g. Github Pages, Netlify
   • CI for the static site, e.g. TravisCI, CircleCI, etc.
   • Should generate RSS feeds
   • Optional: Something for comments? No comments?
2. A wiki, e.g. Github Wiki, MoinMoin, MediaWiki, Reddit Wiki
   • Optional: Hosting for the Wiki
3. A Forum, including:
   • Software, e.g. Discord, PHPBB, Subreddit
   • Optional: A Host, either paid subscription, or self hosted
4. Tooling for "books"
   • Will likely use the same CI and host as our other static sites
   • We currently use mdbook for all of our books.

[ryankurte]

I think a blog would be a neat idea! But maybe it'd be better to avoid having comments at all? Seems like the moderation burden could be significant, and that way the blog stuff could remain static.

Another option (that I've been kindof wishing for) could be to pair it with a forum (Discourse or something) for discussion and questions and everything else in a more friendly / index-able way than IRC. Moderation overhead would probably be the same / worse, but it seems like it could become quite a useful resource, and I could spin up an instance if we wanted to try it out.

[jamesmunns]

👍 from me for having a blog. Right now, I use https://www.getgutenberg.io/ for my site at https://jamesmunns.com.

I don't have comments at the moment, but https://utteranc.es/ is something that I have looked at before (comments driven by GitHub issues). If we have a forum or something similar, we can always link out with "Click here to discuss on XYZ" (see below).

I think a discourse could be good, though this may be an attempt at "there are too many places to discuss, lets add another official one!".

I think the current discussion spaces are:

1. internals.rust-lang.org
2. users.rust-lang.org
3. reddit.com/r/rust
4. #rust-embedded IRC
5. @rustembedded twitter

None of the above are embedded focused, outside of the IRC channel and twitter, which is perhaps a little ephemeral for tracking "tribal knowledge"

I'd also like to suggest a wiki, for collecting knowledge. The book should cover all of our knowledge around embedded rust from a language perspective, however I think are lots of chip, family, tooling, sensor, device, etc domain knowledge that doesn't make sense to cover in the book, but would be valuable to the community.

I'm fine using the built in github wiki, perhaps in the rust-embedded/wg repo.

EDIT: Moved my full comment to the top of this RFC

[jamesmunns]

Sorry, that got a little more in detail than I planned. Let me know if you would like me to open a new RFC, or if you are okay with me hijacking this RFC as our whole content plan.

[kjetilkjeka]

@jamesmunns Has gitter been considered for the chat room? If so, what was the reason IRC was chosen?

[jamesmunns]

@kjetilkjeka IRC is chosen in my above proposal as that is what our most active chat is currently. For most of the other items, I am proposing new things that we have not had before.

I'm not 100% against changing our chat situation (to gitter, discord, rocket, etc.), but I have a feeling that there will be strong opinions around that, and would rather have that in a separate RFC.

[levex]

I like the idea of a blog, it's an easily approachable medium that can help spread Rust's support for embedded. It would also help give the newsletter a more prominent place which is a welcome improvement.

Regarding the chat room, I personally find Gitter too distracting (and RAM consuming!). IRC with a publicly available logging service is low-maintenance, and highly-effective IMO. On the other hand, IRC is less attractive to contributors I think, could we explore a bridge maybe?

[japaric]

@kjetilkjeka

We also have an "official" space in Rust discord server (rust-lang): #wg-embedded, which was created at the time the Rust team decided to experiment with alternatives for IRC, though there's less activity there than there is on IRC. I believe is planned to set up bridges between the IRC and discord servers but I don't know the timeline or the details.

---

I have always wanted to have a FAQ section somewhere. That way I can point all the people asking for "Rust on Arduino?", "Rust on ESP8266?", etc. there. I was thinking that it would make sense to put that in the forum as that's where I expect people will go for asking questions and looking for answers, but perhaps the FAQ should go in the wiki?

[jamesmunns]

Unless anyone feels very strongly about chat, I'd like to avoid discussing it in this thread. We can always open up another RFC to discuss :)

@japaric I think the FAQ in a wiki would make sense

[therealprof]

"Rust on Arduino?" makes me chuckle: Arduino what? The IDE? The ecosystem? "The" hardware (which one)? Funny enough Rust should even usable with on a number of Arduino boards, e.g. the 101 using Intel Atom and the ATSAMD ones...

[kjetilkjeka]

@jamesmunns I do not have very strong feelings about the chat but I think it would still be nice to have an "Embedded Rust Communication Plan" issue where things like this could be discussed without the fear of going off-topic.

---

I think being able to navigate between newsletter more easily is a huge advantage. There are currently also a lot of semi-unrelated issues on this repo and moving the newsletter issues/PRs to a blog repo would be an advantage as well. As long as there are people to maintain it and they feel good about the blog medium it sounds like an excellent idea.

[jamesmunns]

Hey, I talked with @japaric, and he gave me the 👍 to change this into an RFC covering our larger community plan. Here is his original RFC content, for historical reasons:

---

So far we have been posting our newsletter and other announcements to {users,internals}.rust-lang.org (because it was the easiest thing to start out with) and punted on the question of having a blog or not. As we approach the 2018 edition I think it's time to revisit that question.

Advantages of having a blog:

• Easier to navigate between newsletters and other announcements
• RSS support. People have asked for this before.
• It looks nicer. (subjective)

Disadvantages:

• It takes work to set it up.
• No out of box support for comments on most static site solutions I'm aware of.

Quetions:

1. do we really want to do this?

2. what should we use here? There are a lot of static site generators out there. I use hugo for my blog; the wasm WG uses jekyll; and there are generators written in Rust as well.

3. where do we put it? rust-embedded.github.io? blog.rust-embedded.org? rust-embedded.org?

cc @rust-embedded/resources (at)andre-richter (at)jamesmunns (at)therealprof

[jamesmunns]

Regarding tools, I have the following thoughts:

Static Site

Generator

I would say our top three options here are Jekyll, Hugo, and Gutenberg.

Regarding Jekyll, this is probably the most widely used static site generator. There are a number of existing themes and templates, as well as instructions for use with Github Pages, etc.

The Rust Community Team even has a boilerplate repo we could use initially.

Regarding Hugo, this is probably the second most widely used static site generator, and also what @japaric uses for his blog. There are a number of templates and guides for use.

Regarding Gutenberg, this is not so widely used, and there are not a ton of templates/themes for usage. It is used by @jamesmunns for his blog. The primary benefit here is that Gutenberg is written in Rust, and it could be nice to support that project.

My vote: Jekyll, with Gutenberg as my second choice.

Hosting

For any hosting, I think there are a few important points, including:

• Cost
• Overhead in managing
• Integrating with our generator

In general, I would suggest GitHub Pages for this part. Has support for SSL. More or less free and unlimited as far as I know. There is lots of material out there for going from a repo to a hosted blog.

CI

I would suggest TravisCI. It is free to use for open source projects, and there is existing material for use with most static sites generators.

Wiki

For the wiki, we should consider the following items:

• Cost of hosting
• Overhead in managing
• User accessibility

For this, I would suggest GitHub wiki. It is free to use and managed by GitHub (e.g. we don't need our own infra). Most if not all embedded rust users likely already have a GitHub account, so I think we can take this as a given.

Forum

Important items to consider here:

• Cost of hosting
• Overhead in managing
• Moderation tools
• User accessibility

For this, rather than hosting our own, I would suggest we use an existing community site, such as Reddit. This has the benefit of being free as well as not managed by us. Reddit has decent tooling for moderation, and a number of existing projects for bots, if we would like to get fancy. As possible downsides, not all users may have/want to have a Reddit account. We also wouldn't "own" our forum, and migration could be difficult if necessary in the future.

Discord is another option, however the managed hosting (where they take care of keeping it up and running) costs $99/mo. We could host ourselves on a VPS such as DigitalOcean for $5-$10 a month, however then we would need a few people to volunteer to manage it, keep backups, respond timely when the server is down, etc.

Overall, I would suggest using a subreddit for our initial forum. I have reserved /r/RustEmbedded just in case.

Bookshelf

I would suggest that we continue to use mdbook, and whatever tooling we decide for the static sites above.