Skip to content
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.

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

[RFC] Embedded Rust Community Plan #148

Closed
japaric opened this issue Aug 2, 2018 · 27 comments
Closed

[RFC] Embedded Rust Community Plan #148

japaric opened this issue Aug 2, 2018 · 27 comments
Assignees
Labels
feb-2019-cleanup These issues are proposed to be closed, as part of a cleanup of issues in February 2019 RFC T-resources

Comments

@japaric
Copy link
Member

japaric commented Aug 2, 2018

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.
@japaric japaric added this to the RC1 milestone Aug 2, 2018
@ryankurte
Copy link
Contributor

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
Copy link
Member

jamesmunns commented Aug 3, 2018

👍 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
Copy link
Member

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
Copy link

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

@jamesmunns
Copy link
Member

@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
Copy link
Contributor

levex commented Aug 3, 2018

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
Copy link
Member Author

japaric commented Aug 3, 2018

@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
Copy link
Member

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
Copy link
Contributor

"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
Copy link

@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 jamesmunns changed the title [RFC] Should we have a blog? [RFC] Embedded Rust Community Plan Aug 4, 2018
@jamesmunns
Copy link
Member

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.

  1. 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
Copy link
Member

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.

@jamesmunns
Copy link
Member

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
Copy link

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
Copy link
Member

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
Copy link

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
Copy link
Member

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
Copy link
Contributor

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
Copy link
Member

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
Copy link
Member Author

japaric commented Aug 20, 2018

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

  • Make a blog w/o comments section. Put it in blog.rust-embedded.org. Use it for
    the newsletters and other announcements like
    [RFC] [breaking-change] change the default linker of the thumbv*m-none-eabi* targets #160 (comment) .
    Implementation details to be determined (but I think we all would agree on
    that it should take markdown as input and output a static site) in a separate
    issue.

  • Make a forum. Put it in forum.rust-embedded.org. Implementation details
    (discourse vs reddit vs ..) and moderation policy to be determined in a
    separate issue.

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
Copy link
Member Author

japaric commented Aug 20, 2018

@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
Copy link
Contributor

notriddle commented Aug 22, 2018

  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.

bors bot added a commit that referenced this issue Aug 26, 2018
191: [RFC] blog.rust-embedded.org r=jamesmunns a=japaric

This a proposal to create and maintain our own blog.

[Rendered version of this proposal](https://github.com/rust-embedded/wg/blob/blog/rfcs/0000-blog.md)

This proposal (PR) needs at least 10 votes (approvals) from @rust-embedded/all
to be accepted. After the proposal has been accepted we'll proceed to implement
it.

@rust-embedded/all please vote on this proposal using [pull request reviews].
Or if you have a concern leave a comment.

[pull request reviews]: https://help.github.com/articles/about-pull-request-reviews/

cc #148

Co-authored-by: Jorge Aparicio <jorge@japaric.io>
@thenewwazoo
Copy link

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:

  • An embedded Discourse instance (as mentioned in the OP), pending a response to @japaric from someone on the Rust team
  • A Category on users.rust-lang.org, pending an inquiry about adding a category there

@v-thakkar
Copy link
Member

@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 japaric removed this from the RC1 milestone Sep 4, 2018
@japaric
Copy link
Member Author

japaric commented Sep 4, 2018

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
Copy link
Member

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 jamesmunns added the feb-2019-cleanup These issues are proposed to be closed, as part of a cleanup of issues in February 2019 label Feb 4, 2019
@jamesmunns
Copy link
Member

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
feb-2019-cleanup These issues are proposed to be closed, as part of a cleanup of issues in February 2019 RFC T-resources
Projects
None yet
Development

No branches or pull requests

10 participants