From da5744e11d457dd4e81e1f2f68c84d44458dc167 Mon Sep 17 00:00:00 2001 From: Adam Greig Date: Tue, 21 Aug 2018 21:27:08 +0100 Subject: [PATCH 1/3] [RFC] Embedded Rust Showcase --- rfcs/0000-embedded-rust-showcase.md | 101 ++++++++++++++++++++++++++++ 1 file changed, 101 insertions(+) create mode 100644 rfcs/0000-embedded-rust-showcase.md diff --git a/rfcs/0000-embedded-rust-showcase.md b/rfcs/0000-embedded-rust-showcase.md new file mode 100644 index 00000000..87ca9521 --- /dev/null +++ b/rfcs/0000-embedded-rust-showcase.md @@ -0,0 +1,101 @@ +# Summary +[summary]: #summary + +This RFC proposes establishing a new repository for a web page advertising +noteworthy embedded Rust projects. This new resource would go beyond the +existing [awesome-embedded-rust] list by allowing long form +descriptions, photographs, and videos to best demonstrate the projects. + +[awesome-embedded-rust]: https://github.com/rust-embedded/awesome-embedded-rust + +# Motivation +[motivation]: #motivation + +We would like a well-presented list of interesting embedded projects using Rust +to advertise Rust's abilities in this domain. Existing lists are mainly +targeted at embedded Rust developers looking for libraries; this list would +instead be advertising the final projects people have accomplished with Rust, +and so should appeal to potential users who are not already embedded Rust +developers. + +The main embedded Rust website will contain a shortlist of especially notable +projects, but is aimed at presenting a very high-level overview to all users +including non-technical users. This proposed list would be able to present more +projects in more detail, and will require that their source code is publically +available so embedded developers interested in Rust can inspect it. + +# Detailed design +[design]: #detailed-design + +## New Repository + +We create a new repository, `embedded-rust-showcase` (TBC), in the +rust-embedded organisation and under the existing Resources team. It will use +the same underlying technology as the upcoming embedded Rust website to render +Markdown to a web page. + +## New Web Page + +The new web page would live at https://showcase.embedded-rust.org (TBC). + +Each project is listed with a photograph/GIF/video, description, and other +details (see Submission section). + +Additionally, each project has a badge indicating whether it builds on stable +Rust or requires a nightly compiler. + +## Project Requirements + +To be considered for inclusion, projects must: + +* Involve embedded Rust, in other words, use Rust and run on embedded hardware + +* Have publically available source code + +The objective of this list is to showcase Rust code in action; we can't do this +if people can't read the code! There might be space on the main Embedded Rust +website to showcase projects known to use Rust but without public code. We +don't require that the source code is under an open source license; just that +it's available for interested users to read. + +* Have working CI builds + +Since we want people to be able to learn from the code, we require it at least +builds successfully. Working CI also shows what versions of Rust it builds on, +which is useful to establish if a project works on stable Rust. + +* Have at least one photograph/video/GIF of the project in action + +## Project Submission + +Projects are submitted by their authors via pull requests. Submissions must +contain the following information: + +* Project name +* Author name +* Project website/repository +* Project description +* Images, GIFs, or video of the project +* Whether or not the project builds on stable Rust + +After a project is submitted, the resources team will review the PR and +vote on inclusion. They may consult other relevant teams in the process, +but final approval of submissions is at the discretion of the resources team. + +# Alternatives + +* Instead of badges for builds-on-stable projects, the nightly-only projects + could be binned together at the bottom of the page. +* The web page could instead be maintained as part of the main embedded-rust + website, existing as a page in that website. +* We could extend awesome-embedded-rust to permit longer descriptions of + projects. +* We could integrate this concept into the existing awesome-embedded-rust + repository, but still render the projects to a web page. + +# Unresolved Questions +[unresolved]: #unresolved + +* Final name for repository/web page +* The specific technical solution for rendering the repository contents to a + web page From 4177a15e7656aefc0f4a7b7d8b0d6a3919e7b2d7 Mon Sep 17 00:00:00 2001 From: Adam Greig Date: Wed, 22 Aug 2018 14:11:21 +0100 Subject: [PATCH 2/3] Update with feedback from @hannobraun --- rfcs/0000-embedded-rust-showcase.md | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/rfcs/0000-embedded-rust-showcase.md b/rfcs/0000-embedded-rust-showcase.md index 87ca9521..81b3d248 100644 --- a/rfcs/0000-embedded-rust-showcase.md +++ b/rfcs/0000-embedded-rust-showcase.md @@ -29,14 +29,14 @@ available so embedded developers interested in Rust can inspect it. ## New Repository -We create a new repository, `embedded-rust-showcase` (TBC), in the +We create a new repository, `showcase` (TBC), in the rust-embedded organisation and under the existing Resources team. It will use the same underlying technology as the upcoming embedded Rust website to render Markdown to a web page. ## New Web Page -The new web page would live at https://showcase.embedded-rust.org (TBC). +The new web page would live at https://showcase.rust-embedded.org (TBC). Each project is listed with a photograph/GIF/video, description, and other details (see Submission section). @@ -78,9 +78,9 @@ contain the following information: * Images, GIFs, or video of the project * Whether or not the project builds on stable Rust -After a project is submitted, the resources team will review the PR and -vote on inclusion. They may consult other relevant teams in the process, -but final approval of submissions is at the discretion of the resources team. +After a project is submitted, the resources team will review the PR, possibly +consulting the other teams when relevant. Approval can then be granted by any +of the resources team members. # Alternatives @@ -97,5 +97,3 @@ but final approval of submissions is at the discretion of the resources team. [unresolved]: #unresolved * Final name for repository/web page -* The specific technical solution for rendering the repository contents to a - web page From 85487310f67d37acb9b696ece542b42914f2e73e Mon Sep 17 00:00:00 2001 From: Adam Greig Date: Wed, 22 Aug 2018 22:11:33 +0100 Subject: [PATCH 3/3] Update with feedback from @therealprof and @japaric --- rfcs/0000-embedded-rust-showcase.md | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/rfcs/0000-embedded-rust-showcase.md b/rfcs/0000-embedded-rust-showcase.md index 81b3d248..779a433c 100644 --- a/rfcs/0000-embedded-rust-showcase.md +++ b/rfcs/0000-embedded-rust-showcase.md @@ -21,7 +21,7 @@ developers. The main embedded Rust website will contain a shortlist of especially notable projects, but is aimed at presenting a very high-level overview to all users including non-technical users. This proposed list would be able to present more -projects in more detail, and will require that their source code is publically +projects in more detail, and will require that their source code is publicly available so embedded developers interested in Rust can inspect it. # Detailed design @@ -50,13 +50,13 @@ To be considered for inclusion, projects must: * Involve embedded Rust, in other words, use Rust and run on embedded hardware -* Have publically available source code +* Have publicly available source code The objective of this list is to showcase Rust code in action; we can't do this if people can't read the code! There might be space on the main Embedded Rust website to showcase projects known to use Rust but without public code. We -don't require that the source code is under an open source license; just that -it's available for interested users to read. +don't require any specific license; just that it's available for interested +users to read. * Have working CI builds @@ -64,6 +64,14 @@ Since we want people to be able to learn from the code, we require it at least builds successfully. Working CI also shows what versions of Rust it builds on, which is useful to establish if a project works on stable Rust. +* Have build instructions + +These might be as simple as `cargo build` or might document any specific +Rust versions, build oddities, or other steps required to produce the +final firmware. Projects could also document their physical build, for example +whether a particular development board was used, or what custom hardware is +present, but this is not required. + * Have at least one photograph/video/GIF of the project in action ## Project Submission