Как помочь проекту

Курс открытый: исходники текста и примеров лежат на GitHub, в репозитории V-Moskalenko/mojo-ru. Помочь можно по-разному — от сообщения об опечатке до новой главы.

Способы помочь

Сообщить об ошибке. Нашли опечатку, неверный факт или пример, который у вас не работает, — откройте issue. Там есть готовые формы: «Ошибка или неточность в тексте», «Пример кода не работает», «Предложить или запросить главу». Для неработающего примера приложите вывод uv run mojo --version, ОС и полный текст ошибки.

Поправить самому. Внизу каждой страницы есть ссылка «Редактировать страницу». Она открывает файл главы прямо в редакторе GitHub, а GitHub сам предложит сделать форк и pull request. Для опечатки или неудачной фразы больше ничего не нужно.

Поделиться замерами. Цифры скорости в курсе получены на конкретных машинах. Особенно не хватает замеров на видеокартах: запустите bench_mandelbrot из главы «Первое знакомство с GPU» и пришлите вывод вместе с моделью GPU.

Предложить главу. Сначала откройте issue: о чём глава, зачем она читателю и куда встраивается в структуру курса. Так мы договоримся до того, как вы потратите время на текст.

Требования к коду

Главное правило курса: ни одно утверждение о языке не берётся по памяти. Всё, что можно запустить, запускается на настоящем компиляторе, а всё остальное сверяется с официальной документацией и исходниками той версии Mojo, под которую написан курс.

Код пишется на современном Mojo 1.x: def, var, comptime, конвенции mut / var / ref / out, декоратор @fieldwise_init. Никаких fn, let, alias, inout, borrowed, owned, @value — полный список в главе «Устаревшие конструкции».

Где живут примеры

Программа, которую можно запустить, лежит в папке examples/, в подпапке своей главы, а в тексте показывается через импорт файла. Автоматическая проверка курса (npm run examples:check) узнаёт вид примера по имени и содержимому файла:

Файл	Что проверяется
имя.mojo + имя.out	программа запускается, её вывод совпадает с .out
имя.args рядом	программа получает эти аргументы и запускается из своей папки
test_*.mojo	тесты TestSuite проходят с -D ASSERT=all
bench_*.mojo	замер собирается, а с .args — ещё и отрабатывает на маленьких данных
файл без def main	модуль: проверяется через программу, которая его импортирует
модуль расширения Python (PyInit_…)	собирается как разделяемая библиотека
импорт max.gpu	вдобавок собирается под GPU NVIDIA (sm_86) и AMD (gfx1100)
первая строка # ожидается: …	программа обязана упасть именно с этим сообщением

Последняя строка — для справочника ошибок: каждое сообщение на той странице подтверждается такой программой.

Код прямо в тексте главы

Короткие программы можно писать прямо в главе, в блоке кода с пометкой mojo. Проверка их тоже находит:

• блок с def main компилируется и запускается;
• если сразу за ним стоит <Result output={"…"} />, вывод сверяется с ним;
• блок без def main считается фрагментом и должен хотя бы разбираться компилятором.

Вывод в <Result> не набирается руками: запустите программу и скопируйте то, что она напечатала. Если вывод меняется от запуска к запуску, например в замерах, поставьте перед <Result> комментарий {/* вывод-меняется */}. Вывод, который зависит от машины, — ширина SIMD, число ядер, версия Python — сверять нельзя: проверка сама откажется это делать и попросит пометку.

Ещё три правила

• Предупреждение deprecated — это ошибка. Пример, на который компилятор ругается как на устаревший, проверку не пройдёт.
• Ошибки компилятора — дословно. Текст ошибки копируется из терминала целиком и оформляется карточкой <CompilerError>: что значит и как исправить.
• Замеры — честно. Рядом с цифрой указывается процессор, число ядер и методика: лучшее из скольких запусков, какие данные. Код замера лежит в examples/, чтобы его мог повторить любой.

Требования к тексту

• Термины берутся из словаря. Хотите перевести термин иначе — сначала обсуждение в issue, потом правка сразу на всех страницах.
• Первое упоминание термина: русский вариант, а в скобках английский оригинал курсивом: владение (ownership).
• К читателю — на «вы» со строчной буквы.
• Без «просто», «легко», «очевидно». Если бы это было очевидно, читатель бы сюда не пришёл.
• Глава заканчивается блоком «Проверь себя». Вопросы — на понимание, а не на память: почему так, что будет, если.
• Внизу страницы — версия Mojo, на которой проверены примеры: поле mojoVersion в начале файла главы. Меняйте его, когда перепроверили главу на новой версии.

Компоненты для глав

import { Aside, Code } from '@astrojs/starlight/components';
import Result from '../../../components/Result.astro';
import CompilerError from '../../../components/CompilerError.astro';
import PyMojo from '../../../components/PyMojo.astro';
import Quiz from '../../../components/Quiz.astro';
import QuizItem from '../../../components/QuizItem.astro';
import demo from '../../../../examples/раздел/глава/demo.mojo?raw';

<Code code={demo} lang="mojo" title="demo.mojo" />
<Result output={"вывод программы"} />

Как эти блоки выглядят на странице, показано в главе «Как пользоваться курсом».

Отступы в MDX значат многое

Prettier главы не форматирует: он ломает отступы у компонентов внутри списков, а в MDX отступ — часть структуры. Следите за ними вручную и проверяйте результат сборкой.

Как запустить сайт у себя

Нужны Node.js 22 и git.

git clone https://github.com/V-Moskalenko/mojo-ru.git
cd mojo-ru
npm install
npm run dev        # сайт на http://localhost:4321, правки видны сразу
npm run build      # полная сборка: проверяет и внутренние ссылки

Для проверки примеров нужен Mojo — на Linux, macOS или в WSL. Поставьте его в отдельную папку, как в главе «Установка», и укажите путь к компилятору:

MOJO_CMD=/путь/к/проекту/.venv/bin/mojo npm run examples:check

Полная проверка компилирует около трёхсот программ и занимает минуты. Для правки текста без кода её можно не запускать: CI сделает это сам.

Рабочий процесс

git checkout -b правка/короткое-описание
# правки
npm run build
git commit -m "текст: поправил главу про WSL"
git push -u origin правка/короткое-описание

Дальше — pull request. CI соберёт сайт и проверит ссылки, а если менялись главы или примеры — прогонит весь код курса на настоящем компиляторе Mojo. Та же проверка раз в неделю запускается сама, чтобы поймать изменения в новых версиях языка.

Префиксы коммитов: текст:, код:, дизайн:, инфра:, правка:. Строгих требований нет, главное — чтобы было понятно.

Лицензии

Отправляя правку, вы соглашаетесь, что текст публикуется под CC BY-NC-SA 4.0, а код — под Apache 2.0. В проекте действует кодекс поведения.