polkadot-blockchain-academy / pba-book

The materials used in the Polkadot Blockchain Academy

Course Materials Book

This book is the home of the majority of materials used within the Core Developer Track of the Polkadot Blockchain Academy.

Read the Book

We suggest the online version for general use, but cloning, installing, and building this book offline is a great option on-the-go.

Hosted Online

The latest version is hosted at: https://polkadot-blockchain-academy.github.io/pba-book/

Build Offline

The Core Developer Track of the Academy is Rust heavy and as such, you need to install rust before you can continue.

In order to make your life easy 😉, there is a set of tasks that use cargo make.

With cargo make installed, you can list all tasks included to facilitate further installation, building, serving, formatting, and more with:

# Run from the top-level working dir of this repo
makers --list-all-steps

The tasks should be self-explanatory, if they are not - please file an issue to help us make them better.

License and Use Policies

All materials found within this repository are licensed under Mozilla Public License Version 2.0 - See the License for details.

In addition to the license, we ask you read and respect the Academy's Code of Conduct and help us foster a healthy and scholarly community of high academic integrity.

Learn more about and apply for the next Academy today!

pba-book's Issues

Enable translations

Enable contributors to translate to multiple languages, here is the inspiration from Comprehensive Rust repo: https://github.com/google/comprehensive-rust/blob/main/TRANSLATIONS.md#translations-of-comprehensive-rust-

Add missed public repos

Missed in first cut of the Book post UCB, now opened up as public repos:

• https://github.com/Polkadot-Blockchain-Academy/pba-zombienet
• https://github.com/Polkadot-Blockchain-Academy/formal-verification-kani-scale-codec
• https://github.com/Polkadot-Blockchain-Academy/frame-testing-exercise

CI isn't deploying Pages

Example: https://github.com/Polkadot-Blockchain-Academy/pba-book/actions/runs/6204872842

Reported upstream:

• actions/deploy-pages#222
• Asking for community help: https://github.com/orgs/community/discussions/66706#discussion-5613026

The error:

Error: Deployment failed, Please ensure that the file permissions are correct.

Thus this might be due to #2 having bun write static files with bad permissions, and rsync picks them up... unclear.

Using webp format to reduce repository size

Allowing any type of image format could lead to a heavy repository. I would suggest converting all images to webp (considering the repository data is consumed as a website/slides). A webp images can be as minimum 25% less heavy than a PNG or JPEG (Study).

There is already a File Size comparison section, maybe we could add here the recommendation of using webp. In the same way, maybe adding a makers img-conv command that convert all images non-webp to webp can be a good idea. This can be done with the cwebp package.

As example, in my latest PR I was able to reduce size of some PNG from 10 mb to 900kb.

Preprocessor to remove `yml` header for slides in book pages

The raw slides.md file is placed in the page.md file when rendered, although this leads the the yml header of that file to be dumped there too, and it's not useful in that form to the reader. There may be an easy fix to add an mdbook preprocessor to remove that: https://github.com/dvogt23/mdbook-yml-header/tree/main

Considerations

This should work as the slides are rendered first and apart from the book at this time, note that if the reveal tooling is brought into a mdbook preprocessor or something like this, it could be this other yml header remover would remove it before the slides were processsed (and the slides do benefit from it, and need it in cases that custom settings are passed)

--v appearing

Is there an easy fix to solve this --v appearing (see below)?

Random Colored Artifacts Showing Up

See:

These colored blocks show up when I navigate to this page:

https://polkadot-blockchain-academy.github.io/pba-book/substrate/wasm/page.html?highlight=wasm%20export#workshop-inspecting-wasm-code

They stay fixed on screen as you scroll.

Define a CLA and impliment a mechanism to sign it

Something akin to https://cla.parity.io/ that is used for contributors to the Polkadot SDK would be ideal IMHO. As it stands, the license is all that describes rights of contributors as, that may be enough. But a CLA should likely be considered in addition to it.

Move to more legible non-header Font

Ran into https://fonts.google.com/specimen/Atkinson+Hyperlegible via https://www.dedp.online/introduction.html and IMHO it is a much more legible (true to it's name!) font face than we use at the moment (work sans, vendored not a CDN). I would think keeping Unbounded (The official & treasury funded Polkadot's ecosystem font) as a header font and perhaps emphasis option is a good idea.

If this were adopted for the book, there should be no issue I would expect, but in the slides there may be some minor visual bugs as this would change the fixed pixel width we have been relying on with the present font (neither of these are monospace... perhaps mono would be a good option moving forward if there is a desire to update fonts over time)

Update how-to on jump-to-top

1. you can click any header
2. your URL (on refresh / share etc.) jumps to that location again on refresh
3. hit the top banner to quick scroll up to the top of the page ✨

So getting back to slides is easier. Perhaps this would also remove the hacked in bottom right #top button we have now to do that.

Rectanlges appearing in section 4.2 Substrate Wasm Meta-Protocol

Some rectangles are appearing and shouldn't be there(see below):

Move to faster and more feature rich link checker

See paritytech/polkadot-sdk#1875 as reference, https://github.com/lycheeverse/lychee is far more feature rich that mlc and likely faster to boot.

Move from Cargo Make to Just

While cargo make is nice, seeing https://github.com/casey/just far more commonly, and TBH it's far more legible and succinct IMHO even though it is an DSL... Thus a move to a simpler make system should help contributors be able to clearly see what each task/job is doing and how to modify it very easily.

The migration should be rather trivial, just need to ensure the CI is updated. As a nice followup or in closing this, using the just file instead of CI being independent would make this repo more DRY too. see https://github.com/casey/just#github-actions

Automated PR deployment prereviews

It would be great to have each PR have an up-to-date rendering of the book to accelerate reviews.

We have used fleek before to host slides (IPFS hosted too 🌟) very easily. We use Github pages for the main deployment at his time, but an alternative web3 first host,, we could go back to using fleek. Notably, they allow PR development previews very easily too: https://docs.fleek.co/internet-computer-hosting/site-deployment/#previewing-a-deployment that looks like a good fit for this purpose. Of course, there are other avenues to getting a deployment preview too we could consider.

makers serve command not working for me

I am trying to build the book for offline use. makers install and makers build both worked fine, but when I run makers serve I get an error (sh: line 1: type: mlc: not found) and the suggested fix is to run makers install-dev, but that gives the error shown below (and the suggested fix for that is the same command I was running (so it is recursive lol):

error[E0635]: unknown feature proc_macro_span_shrink
--> /Users/rogerbos/.cargo/registry/src/index.crates.io-6f17d22bba15001f/proc-macro2-1.0.47/src/lib.rs:92:30
|
92 | feature(proc_macro_span, proc_macro_span_shrink)
| ^^^^^^^^^^^^^^^^^^^^^^

Compiling futures-io v0.3.21
For more information about this error, try rustc --explain E0635.
error: could not compile proc-macro2 (lib) due to previous error
warning: build failed, waiting for other jobs to finish...
error: failed to compile mlc v0.16.2, intermediate artifacts can be found at /var/folders/_f/jx8_bq5j6z156s5v4_hwx4xc0000gp/T/cargo-installZOWg04.
To reuse those artifacts with a future compilation, set the environment variable CARGO_TARGET_DIR to that path.
[cargo-make][1] ERROR - Error while executing command, exit code: 101
[cargo-make][1] WARN - Build Failed.
[cargo-make] INFO - Running Task: catch-error
sh: line 1: type: mlc: not found
-e ❌ You may need to install the dev tooling. Run:

makers install-dev

Any suggested fix or workaround would be welcomed. Thanks in advance.