Merge #6

6: Add evaluation guidelines and instructions on how to submit a project r=adamgreig a=japaric

The guidelines include all I can think of at the moment. We'll probably come up
with more of them once start reviewing user submissions. And, maybe, in the
future these guidelines could become a document on "good practices for
structuring embedded applications".

Q: Is there any additional information we'll like to request from the submitter,
apart from the information in `data.yml` (see #5)? This information would be
provided in the description of the pull request. If not then we don't need a
pull request template as I suggested in #3.

r? @rust-embedded/resources

closes #3
closes #4

Co-authored-by: Jorge Aparicio <[email protected]>

Author: bors[bot]

EVAL.md

@@ -0,0 +1,49 @@
+# Evaluation guidelines
+
+These are the guidelines used by the Resources team to evaluate project
+submissions.
+
+## Hard requirements
+
+The project must fulfill these requirements or it will be rejected.
+
+- The main logic of the application must be written in Rust.
+
+- The source code must be public. Licensing terms are unimportant.
+
+## Bonus points
+
+> N.B. A project repository may contain more than one crate. In those cases, one
+> (binary) crate will be the application, and the other crates will be libraries
+> and / or tools. In the review consider only the crates that are compiled for
+> the target device. One of these crates will be the application ("application
+> code") and the rest will be libraries ("support code").
+
+Award points if
+
+- The project is unlike the projects currently on display.
+
+- The documentation includes instructions on how to build the program, or the
+  firmware can be built with just `cargo build`.
+
+- The repository has a CI setup.
+
+- The application compiles on stable.
+
+- The application code is free from `unsafe` code and all `unsafe` code has been
+  pushed to libraries that only expose a safe API.
+
+- Code that's not target specific, if any, has unit tests.
+
+- Support code, if any, is documented.
+
+## Penalties
+
+Subtract points if
+
+- The application contains potential soundness issues. For example, using
+  `mem::transmute`, unchecked creation of singletons and unchecked use of
+  `static mut` variables are huge red flags.
+
+- Explicit panicking (e.g. `unwrap`) is used instead of proper error handling.
+  However, note that `unreachable!` is OK if properly used.

README.md

@@ -4,6 +4,25 @@ Awesome embedded projects by the Rust community!
 
 This project is developed and maintained by the [Resources team][team].
 
+## Submit your project
+
+First, read the [evaluation guidelines](./EVAL.md). The resources team will use
+these guidelines to evaluate your project, but you can also use the guidelines
+to improve your code and the structure of your project!
+
+When you are ready send a pull-request that
+
+- Adds information about your project at the end of `data.yml`. The file
+  contains comments that will help you fill in the information; and
+
+- Adds an image or videos of your project, if not using URLs, to the `assets`
+  folder.
+
+The resources team will review your submission and let you know if it has been
+accepted or not. If it doesn't get accepted this time but meets the hard
+requirements, we'll let you know how it can be improved so you can resubmit at a
+later date.
+
 ## License
 
 This project is distributed under the following licenses:
@@ -40,7 +59,6 @@ Copies of the licenses used by this project may also be found here:
 [Apache License v2.0 Hosted]: http://www.apache.org/licenses/LICENSE-2.0
 [CC-BY-SA v4.0 Hosted]: https://creativecommons.org/licenses/by-sa/4.0/legalcode
 
-
 ### Contribution
 
 Unless you explicitly state otherwise, any contribution intentionally submitted

data.yml

@@ -1,37 +1,44 @@
-  # Project name
+# NOTE If submitting a new project add it to the end of the list, before the template
+
+# Dummy entry
 - name: Lorem Ipsum
+  website: https://example.org
+  author: Alice
+  author_website:  https://github.com/ghost
+  description: "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec eu pharetra purus. Sed laoreet lectus ut convallis molestie. Etiam suscipit vitae ante a finibus. Fusce aliquet viverra efficitur. Curabitur sit amet tellus risus."
+  image: https://via.placeholder.com/900x675
 
-  # Project website
+# Another dummy entry
+- name: Ipsum Lorem
   website: https://example.org
+  author: Bob
+  author_website:  https://github.com/ghost
+  description: "Vivamus varius cursus aliquam. Praesent scelerisque, neque efficitur luctus pharetra, augue urna tempus lectus, at ullamcorper sem purus et enim. Nam urna eros, ornare quis mi posuere, aliquam egestas turpis. Suspendisse quis mi viverra, malesuada justo ullamcorper, blandit risus"
+  image: https://via.placeholder.com/900x675
+
+# Template for new entries
+
+  # Project name
+# - name: Lorem Ipsum
+
+  # Project website
+  # website: https://example.org
 
   # Author name or username
-  author: Alice
+  # author: Alice
 
   # Author's GitHub / Twitter profile or personal website
-  author_website:  https://github.com/ghost
+  # author_website:  https://github.com/ghost
 
   # SHORT description of the project (max 280 characters)
-  description: "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec eu pharetra purus. Sed laoreet lectus ut convallis molestie. Etiam suscipit vitae ante a finibus. Fusce aliquet viverra efficitur. Curabitur sit amet tellus risus."
+  # description: "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec eu pharetra purus. Sed laoreet lectus ut convallis molestie. Etiam suscipit vitae ante a finibus. Fusce aliquet viverra efficitur. Curabitur sit amet tellus risus."
 
   # Image of the project
   # if not a URL, place the file in the `assets` folder
-  image: https://via.placeholder.com/900x675
+  # image: https://via.placeholder.com/900x675
 
   # OR a video of the project
   # multiple video formats can be supplied
   # if not a URL, place the file in the `assets` folder
   # video:
     # - ipsum.mp4
-
-- name: Ipsum Lorem
-
-  website: https://example.org
-
-  author: Bob
-
-  author_website:  https://github.com/ghost
-
-  description: "Vivamus varius cursus aliquam. Praesent scelerisque, neque efficitur luctus pharetra, augue urna tempus lectus, at ullamcorper sem purus et enim. Nam urna eros, ornare quis mi posuere, aliquam egestas turpis. Suspendisse quis mi viverra, malesuada justo ullamcorper, blandit risus"
-
-  # if not a URL, place the file in the `assets` folder
-  image: https://via.placeholder.com/900x675