Contributing

Danger

We do not allow any AI to be used in development of these docs. If we suspect that your contributions were created with AI, they will be rejected.

Thank you for your interest in contributing to Learn! We welcome every addition, no matter how small.

If you have any suggestions, or if you’ve found any mistakes, please create an issue on our Github repo (following our style guide below).

Setup

It is recommended to use an IDE such as VSCode, however it is not required. You will need to have NodeJS installed on your computer to build the project. You will also need to have Git set up and configured.

Learn runs with Astro Starlight.

Style Guide

Tip

We aspire to keep a consistent style throughout the documentation, and as this is a new project, this section will likely be constantly growing and changing as we figure out the best style for both contributors and readers.

Caution

If you are creating a lesson or a guide, you must have enough knowledge about the subject to effectively write about them. If you submit a PR that contains half-baked material, we will give you one opportunity to fix it before rejecting the PR.

File Headers

At the top of each .mdx file, you must include the following block of metadata. A PR which contains .mdx files without it will be rejected.

---
title: Example title
description: A really cool and descriptive blurb
author: You!
last-editor: A real person
created-on: yy/mm/dd
last-edited: yy/mm/dd
---

When modifying existing files, remember to update the last-edited sections.

File Naming

Lessons

The format for naming lessons is XXX-kebab-case-name.mdx, where the the first 3 characters represent the number ID of the lesson, and the rest is in kebab-case.

For example, should you have a lesson named 1.15 - Example lesson, then the final name would be 115-example-lesson.mdx

More examples:

"1.2 - Kebab Roasting" -> "102-kebab-roasting.mdx"
"4.9 - Burger Flipping" -> "409-burger-flipping.mdx"
"2.22 - Factual Statements" -> "222-factual-statements.mdx"

Guides

The format for guide names is kebab-case-name.

Images

Image files should be named with the format XX-kebab-case-name, and the unique (within a lesson/guide) ID of the image.

Image files should be stored within the src/assets/ directory of the site. If a lesson or guide contains an image, that image should be stored within the src/assets directory, in the same subfolder as their corresponding lesson is to the src/content/docs/ folder.

For lesson images, put the 3 digits of the lesson numberin the title. For guides, simply put them into a subfolder with the name of the guide underneath the src/assets/guides/ folder.

For example, if there were 2 images in a lesson at src/assets/content/docs/lessons/u1-intro/101-kebab-eating.mdx, some image files could be:

src/assets/lessons/u1-intro/101-01-grill-photo.png
src/assets/lessons/u1-intro/101-02-propane-tank.png

In general, the title of a file should match the transformed version of the title inside the metadata.

If renaming a file, provide a good reason in your PR, otherwise we may ask you about it before approving.

Lessons

When writing lessons, make each lesson easy to digest and interactive. Go step by step, but still treat the reader like an adult, and leave them challenges to accomplish with their newly aqcuired skills. Language in general must be formal. However, you may use terms such as “we, us, you” (but never ‘I’), in your writings.

At the end of lessons, include more advanced tips if applicable.

Minimums

• All lessons must contain instructions for Windows and Linux (if possible).
• All programming lessons must be in at least C++ and have VSCode setup instructions.
• All CAD lessons must be in at least Solidworks. However, contributors are free to include additional systems, as long as they remain consistent across the lesson and lessons linking to it.
• Electrical lessons should contain one of proper circuit schematics OR breadboard diagrams (preferably both) when referencing a circuit.

Guides

Guides are step-by-step instructions to accomplishing a specific task. Do not give the reader challenges to test their learning until the end of the guide.

Guides should be self-contained in one file, and they have the same minimums as lessons.

Starlight components

Astro Starlight provides numerous extremely useful components for creating guides. It is highly encouraged that you read their docs, as we may withhold PR acceptances should using their components result in a cleaner and easier to use UI than what is implemented.

Github Issues

Issues should be concise and specific in scope. They should not have multiple different items all in one. We encourage you to solve issues yourself.

Commits

When writing a commit message, follow Conventionalal Commits AND include the lesson number (if modfying lessons) AND filename (if creating a lesson or guide) For example:

feat: created contributing file
fix: removed line comment in lesson 4.1
feat: created lesson 1.0 - Chapter Overview

This is not 100% required, however it makes everyone’s lives easier, and if it causes an issue or not enough commits are formatted properly, it will become required.

Pull Requests

Pull requests must have a specific purpose in mind and stick to it. We will not accept pull requests which modify half or even an eighth of the files in the codebase. The title must follow Conventional commits just like the commits, and the description must briefly and concisely explain what it added as well as any unorthodox decisions.

We may ask contributors to be more concise and edit your title or description before accepting a PR.

Development

1. Start by creating a fork of the repository via github or the github command line tool.

   # via command line
   gh repo fork mech-mania/learn
   git clone https://github.com/<your-username>/learn

2. Use npm commands to run dev enviroments and to build/preview.

   #install dependencies
   npm install
   
   # dev environment for live updates
   npm run dev
   
   # build then preview for mock production
   npm run build
   npm run preview

3. If you have a feature request, or are adding a feature yourself, please create a Github Issue on our repository detailing it.

4. Then write guides, lessons, and technical docs according to the style guide above. Feel free to also suggest miscellaneous improvements to the docs website as well.

5. Open a PR on Github to our repo, then link it to the issue you created, and neatly explain what was added, where it will be reviewed by our team.

6. If your PR gets rejected, take a look at the feedback. Most of the time we still want your contributions, you just need to tweak a few small things for it to be good enough.