search

rust-embedded / wg

Coordination repository of the embedded devices Working Group
1.9k stars 99 forks source link

[RFC] Embedded Rust Community Plan #148

Closed japaric closed 5 years ago

japaric commented 6 years ago

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:

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:

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:

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-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 commented 6 years ago

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 commented 6 years ago

:+1: 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 commented 6 years ago

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 commented 6 years ago

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

jamesmunns commented 6 years ago

@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 commented 6 years ago

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 commented 6 years ago

@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 commented 6 years ago

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 commented 6 years ago

"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 commented 6 years ago

@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 commented 6 years ago

Hey, I talked with @japaric, and he gave me the :+1: 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:

Disadvantages:

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 commented 6 years ago

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:

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:

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:

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.

jamesmunns commented 6 years ago

Oh, and if we have a forum, I would suggest no comments on the blog to keep it simple, and instead link to a forum post discussing that article.

steveklabnik commented 6 years ago

FWIW, I always thought that we were going to end up adding the various WG books to the bookshelf on doc.rust-lang.org; if you all would like that, we can do it, but if you don't, we don't have to.

jamesmunns commented 6 years ago

Good call @steveklabnik. That was the original intent.

Discovery and the Embedonomicon are probably ready, or close to ready for inclusion. Any objections @japaric?

IMO, the repos would still live in our organization, but this would remove the need for DNS entries, as well as maybe even setting up GH pages/CI.

steveklabnik commented 6 years ago

Yup! All you'd need to do is have a repo with and mdbook book in it; we submodule it in, and i take care of the rest. you don't even have to update it; I update all the books for each release.

jamesmunns commented 6 years ago

Notes from the meeting:

Blog, generally +1, maybe consider setting up a "planet" for multiple blogs in this space
+1 to forum - perhaps discourse, might be able to get free hosted instance
-3-4 to wiki
+3-4 to no comments on a blog
japaric will ask the Rust team about the possibility of getting a free discourse forum
ryankurte commented 6 years ago

I think it's also important that we have a place to compose institutional knowledge and processes for us, it seems like a lot of things occur in issues/PRs that would be valuable to surface.

I think a wiki would do that reasonably well to compose everything, it's searchable and linking makes sense, and would allow us to slowly build it up as questions arise without creating a huge amount of noise on the wg repo / wherever else we would put it.

If we're dead set against a wiki we could maybe add another set of documentation somewhere for this?

v-thakkar commented 6 years ago

Sorry, I'm probably late for the party but just wanted to add one more point. Loved the idea of blog and other tooling related things. Regarding social media platforms, I was wondering if there is an interest in using Instagram? I believe that along with twitter, Instagram can be used for embedded Rust demos [in the form of videos/pictures/GIFs, Outreaching about embedded projects [again content can be created accordingly] and last but not least embedded Rust Memes. :)

For the things mentioned above, Twitter can be used as well. But i'm not sure if we want to use different sort of social media platforms for different type of content or we want to focus on using one platform to outreach about all sort of embedded Rust related content.

japaric commented 6 years ago

In an effort to move this forward I'd like to propose voting on the parts where there seems to be overall agreement:

With separate issues we can have more focused discussions. It's still good to have this discussion to get a feel for the overall needs of the community though.

I nominate that we vote on those two proposals during tomorrow's meeting.

japaric commented 6 years ago

@nerdyvaishali Interesting proposal. I'm not an instagram user myself (I post pics and videos of my embedded stuff on twitter) but my opinion is that we should have a presence on social sites where there's a "significant" presence of (potential) (embedded) Rust developers, if we have the people to run the account. The Arduino instagram account has 180K followers; in contrast the Rust twitter account only has 30K followers so it seems worthwhile.

Before we venture there though I would like to see a plan that details how we are going to produce content: any existing embedded Rust user that's also posting embedded stuff on instagram and that we can repost content from? Can we get existing e.g. twitter users to also post on instagram? Can we repost twitter content? etc.

notriddle commented 6 years ago

  1. A Forum, including:

    • Software, e.g. Discord, PHPBB, Subreddit

You mean Discourse, not Discord. Discord is a chatroom, Discourse is a forum.

(it's kind of confusing, I admit)

  1. A static site, including:

    • Optional: Something for comments? No comments?

Discourse has a script you can use for that.

thenewwazoo commented 6 years ago

Per today's embedded wg discussion, we identified a need to a place to have discussions about things that aren't well-suited to github issues, or that are broader than a specific crate/repo's mandate.

Some solutions were proposed, along with some pending responses/actions:

v-thakkar commented 6 years ago

@japaric Yes, there are lot of makers on instagram as compare to twitter in my experience. I agree that we should define on what we plan to post, probably some sort of social media guidelines. Do you want me to come with a draft may be? I think cross posting about things over different platforms is good but having clear idea on how we want to target the potential audience and then using the features of both platforms would be more beneficial in evangelizing and for the community.

japaric commented 6 years ago

I had milestoned this because originally this was about only the blog but since that is done I'm going to remove it from the milestone.

@nerdyvaishali yes, opening a separate issue with a draft of social media guidelines or anything similar to start the discussion would be the next step here.

jamesmunns commented 5 years ago

I think we have reached the majority of the goals set out here. I would like to nominate this to be closed.

@nerdyvaishali if you are still interested in opening additional social media accounts, please feel free to get in touch.

jamesmunns commented 5 years ago

I am closing this issue, please feel free to open another issue if you would like this discussed further.