Contributing Guide

Thank you for investing your time in contributing to the Academy! ✨.

Read our Code of Conduct to keep our community approachable and respectable.

Quick Start

This book is a monorepo for all public content used in the Academy, omitting Rust source code in a few other repositories linked to in the book. There are git submodules included, most notably of which is the embedded slides source and associated tooling to build them.

You may opt out of cargo make described below, but minimally will need to have an installation of mdBook to read and contribute to the book itself.

Serve the book offline with:

# Run from the working dir of this repo
mdbook serve --open

Installation and Development

The Academy is Rust heavy and as such, you need to install rust before anything else here.

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.

Development Workflow

To view and edit slides:

makers install # Get all the deps needed for the book
makers serve # serve the existing submodule build artifacts in the book in watching mode for the book only

To work on both the embedded slides and the book in tandem:

makers install-all # Get all the deps needed for the book and submodules
makers serve-slides # Serve the embedded slides in watching mode not included in the book, yet!

# ....Make changes to the book and/or the slides...

makers serve-updated # Build the slides (clobbering those tracked by the book repo in `./slides`), embed in the book, view the updated book.

# git commit into the submodules *first* and make a PR on those repos
# *Then* commit into the book as a companion to submodule repos to finally a PR to the book.

💫 In your PRs to this book, please do be sure to add yourself to our illustrious contributors showcase 👨‍🎤

Refactoring Considerations

We opt out of the handy helper to create missing files if linked in SUMMARY.md, as this indicates something is likely amis in our translation of slides -> stub pages mapping correctly.

This is useful to turn back on when radically updating the slides path structure and/or file names as _those changes must be manually applied to link to the correct new location in /slides/.../*-slides.html

You can opt in by editing book.toml:

[build]
- create-missing = false # do not create missing pages
+ create-missing = true # create missing pages

CI

Using simple raw example