Skip to content

Latest commit

 

History

History
252 lines (180 loc) · 10.8 KB

CONTRIBUTING.md

File metadata and controls

252 lines (180 loc) · 10.8 KB
Raw

Polkadot Blockchain Academy Contributors Guide

This guide is to help Academy contributors understand how all materials contained this repository are structured, how to interact with and modify them. Multiple tools are provided for contributors to make slideshows, leader-guided workshops, and self-directed activities.

Table of contents

Content organization

syllabus/
├─ 1-example-module/
│  ├─ 1.1-*/
│  │  ├─ 1.1-Workshops_and_Activities/
│  │  │  ├─ 1.1-*_Activity.md
│  │  │  ├─ 1.1-*_Workshop.md
│  │  ├─ 1.1-*_slides.md
│  ├─ example-module-lesson-plans/
│  |   ├─ 1.1-Lesson_Plan_*_1.md
├  |   ├─ 1.2-Lesson_Plan_*_2.md
├─ 2-another-example-module/
│  ├─ ...

When creating content for your lecture (and exercise) slides, we recommend you:

  1. Start with copying the "Core Ideas to Convey" section of the original lesson plan.
  2. Build out the content slide by slide around those notes.
  3. Add TODOs as markdown comments (<!-- this is a comment -->) to write notes to yourself and to the TAs for adding diagrams or things to get back to later.
  4. Place content for workshops and activities in the appropriate files, cross-referencing lecture and exercise content for reference to be build out around.

Lesson slides with Reveal.js

If this is your first time using reveal.js, we encourage you to explore the official demo to see what sort of things you can do with it! We are creating and customizing slides with reveal-md: a tool built with reveal.js to allow for Markdown only slides, with a few extra syntax items to make your slides look and feel awesome with very little effort.

Quick start

Have nvm and yarn already installed? All you need to do is execute this from the top level directory of the Academy repo:

# Ensure you have the right node
nvm i
# For yarn 3, you need to enable some node features
corepack enable
# Install Dependencies
yarn
# Run a slide server watching for file changes
yarn dev

This should open a new tab with a listing of all slide decks to choose from.

If you are missing node or yarn, please install them as described below. (click to toggle)

Node.js

For all linux and mac users We suggest to use nvm to install and manage multiple node versions. With nvm installed, from the academy top level dir:

nvm install

This will install (if needed) and set the correct version to use for this project set in the .nvmrc file here.

If you choose to not use nvm, you need node of version greater than 16.10. It is likely your package manager has this version for you.

Yarn

Please see the official guide to install for yarn 3. Likely all you need to do is:

corepack enable

The only dependencies we need for this project can now all be installed with:

yarn

Using speaker notes

It's sometimes useful to have speaker notes for your slides. This feature can be accessed when in presentation by pressing s when presenting (you need to unblock popups to have the window open).

To include notes for a slide, use the "Note" keyword inside that slide. For example:

Notes:

This is a note just for you.
All these lines are just seen in speaker view only.

Presenting

Once you've followed the set-up instructions and have the repository running locally, here are the basic ways to navigate through presenting your slides:

  • Use down/up arrow keys to navigate vertical slides.
  • Use left/right arrow keys to navigate horizontal slides.
  • Press Esc or o to see an overview view that your arrow keys can navigate. This allows you to click a slide to open it).
  • Press s to open up speaker view.

Formatting Markdown, TOML, JSON

We enforce the use of a few formatters, the primary one being Prettier that is included in the dev-dependencies for this repository. In package.json we include a handy tool to format all markdown docs easily:

# This will format all `syllabus/*.md` files
yarn fmt

If (and only if) formatting breaks markdown from rendering correctly, you may use <!-- prettier-ignore --> preceding a block in markdown to skip formatting like this:

<!-- prettier-ignore -->
```html
<pba-cols>
<pba-col>

### What's up, yo?

</pba-col>
<pba-col>

- Yo
- Yo
- Yo

</pba-col>
</pba-cols>
```

The above ```html block will not be formatted.

Check embedded links

To ensure all *.md contain no broken links within them, we have included a simple link checker you can run per module of content with:

# Link check a single file (or use regex to match)
yarn links <relative-link-to/the-top-working-dir/file.md>

# Link check all content files
yarn links syllabus/**/*.md

# This will check the files that match the pattern `syllabus/${MOD_NUMBER}*.md`.
yarn mod-links <Module Number>

The same tool is also run by our CI on all files for all pushes to all branches. See .github/workflows/link-check.yml for details. Both use the same config file.

You can ignore the link check for a single line by post-fixing it with:

Some private or intentionally broken link. <!-- TODO Remove this check disable once ... --> <!-- markdown-link-check-disable-line -->

Exercises, workshops and activities

Each lecture may have a set of exercises, workshops and/or activities. Not all lectures must have workshops or activities... but almost all should. The academy is focused on practical application of Web3 concepts we cover, more than simply understanding. Here is how we define these:

  • Exercises: these are short (5-10 minutes) exercises that are included as part of the slide deck and will be completing during the lecture.
  • Workshops: these are step-by-step, longer (30 min to 3 hours) guided in-class material. These are instructor lead, and hand-held to get everyone to the same result.
  • Activities: these are self-directed assignments for individuals and/or small groups that do not "hand-hold" like workshops. Student's completed work is expected to have some variety and a canonical solutions should be produced to review when students submit to compare to.

Solutions should (when possible) be provided in a separate branch of this repository such that material published on the main branch does not include these. For example, skeleton code with code-comments providing instructions in a crate on main should have a solution-modX-lessonY-* branch where a completed reference that fulfills the requirements is available.

The following outline some suggested tools to use for these.

Stand-alone Rust workshops and activities

For non-trivial Rust work, it's best to use a full IDE and cargo properly. For these, please create well documented crates in their own repository that stand alone for each workshop or activity. We will use github classrooms to give each student their own fork of such repositories.

Local IDE

It is very likely that all students will want to run your code locally. We suggest that most users will use VSCode as it's most all-around featureful for academy work more than just Rust itself.

Notice: The build times for you project need to be taken into account! Please time on your build machine as a reference and report this to the TAs so we can all plan around the rough timeline to have students start to build things.

  • We highly suggest sccache that will enable faster builds for almost all academy students! If you want to use it globally, you need to add this with the right path to your ~/.cargo/config.toml file:

    [build]
rustc-wrapper = "<path to where>/.cargo/bin/sccache"

    Use which sccache to find the path.

  • To get more power out of sccache and maybe overall faster linking, install and use the lld linker and while notebooks using EvCxR use this by default if detected, if you want to use it globally, see this post on how to enable it. You need to add something like this to your ~/.cargo/config.toml file:

    [target.x86_64-unknown-linux-gnu]
rustflags = [
  "-C", "link-arg=-fuse-ld=lld",
]

Online IDE

There are some great (but limited) options for anyone lacking the ability to do things locally, or real-time collaboration is needed.

  • REPL.it - This online IDE includes a low-powered machine to compile Rust on, but provides real-time collaboration where multiple users can follow-the-leader and edit simultaneously. It also features github integrations to save and share progress.
  • Substrate Playground - This is a Parity hosted very powerful build machine that anyone can access using a pre-compiled docker image of the base substrate node template to build on top of in an online VSCode-like IDE. The session is limited to 2 hours per user, before all data is cleared. There is no simple way to capture your work though, so this is only to be used in simple examples of substrate to iterate very quickly. Note that it is unclear if 50+ students can access this at the same time, thus please let the TAs know if you plan to use this first!

Conceptual workshops and activities

While most work students are doing should highlight practical applications of the concepts, sometimes code isn't the best way to engage.