Перейти к содержанию

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

IST - это открытый проект, который развивается усилиями энтузиастов. Сейчас нам особенно нужны люди, готовые писать программы под архитектуру i48 и поддерживать документацию в актуальном состоянии.

Если тебе интересна эта тема - здесь ты найдёшь, чем можно заняться и как подключиться.

Кого мы ищем

Разработчики под i48

Мы ищем людей, готовых писать программы и системный код под процессоры i48:

  • Прикладные программы - утилиты, игры, демо, инструменты командной строки.
  • Системный код - драйверы устройств (диск, видео, клавиатура, мышь, PSG, FPU).
  • Компоненты ОС - загрузчик, ядро, файловая система, оболочка.
  • Библиотеки - общие функции для вывода, ввода, работы с памятью, строками.
  • Примеры и туториалы - код, который помогает новичкам разобраться.

Не обязательно быть экспертом в ассемблере. Если у тебя есть опыт в C, C++ или Python и желание разобраться в архитектуре - этого достаточно. Документация по процессору и инструментам уже написана.

Технические писатели

Мы ищем людей, готовых поддерживать и развивать документацию:

  • Обновлять существующие разделы при изменениях в архитектуре и инструментах.
  • Дописывать недостающие страницы
  • Проверять корректность - сверять .md файлы со спецификацией и кодом.
  • Улучшать читаемость - добавлять примеры, схемы, таблицы, уточнения.
  • Переводить - если хочешь помочь с версией на английском.

Документация написана в Markdown и собирается через MkDocs + Material. Достаточно уметь писать понятные тексты, со сборкой поможем.

Как начать

1. Познакомься с проектом

Прочитай разделы:

2. Выбери задачу

Открой issues и посмотри, что сейчас в работе. Если ничего не подходит - создай свой issue с описанием того, что хочешь сделать.

Если не знаешь, с чего начать - напиши в issue, что готов помочь, и мы предложим задачу под твой уровень.

3. Сделай pull request

После того как задача сделана:

  1. Форкни репозиторий.
  2. Создай ветку с осмысленным именем: 
    git checkout -b feature/hello-world
git checkout -b docs/bios-standards
  3. Внеси изменения - код или текст.
  4. Проверь себя:
  5. Для кода - программа должна собираться и запускаться.
  6. Для документации - mkdocs serve должен собираться без ошибок.
  7. Отправь PR с описанием: что сделано, зачем, как проверить.

Правила оформления

Код на ассемблере

  • Комментарии - каждая нетривиальная строка должна быть объяснена.
  • Стиль - придерживайся примеров из CASM148.
  • Метки - говорящие имена (main, print_string, ps_done), а не l1, l2.
  • Константы - выноси адреса устройств и magic numbers в .DATA или комментарии.
  • Структура - разделяй код на функции, не пиши всё в main.

Пример хорошего стиля:

.ORG 0x00060000
.TEXT
main:
sign: .dw 0xB007AB1E                ; загрузочная сигнатура
stub: .dw 0x00000000                ; подпись диска

        LDI.DW SP, 0x00080000       ; указатель стека
        LDI.DW IX, msg              ; адрес строки
        CALL print_string
        HALT

print_string:
        LOD.B XL1, [IX]             ; читаем байт
        CMP.B XL1, 0                ; конец строки?
        JMP.EQ ps_done
        STR.B XL1, [0x00020018]     ; TERM_OUT
        INC IX
        JMA print_string
ps_done:
        RET

.DATA
msg:    .db "Hello, World!", 0

Документация

  • Markdown - стандартный синтаксис, 4 пробела для отступов.
  • Структура - заголовок, краткое введение, основная часть, примеры, ссылки.
  • Примеры - обязательно с выводом или пояснением.
  • Ссылки - используй относительные пути (../processors/i80148/index.md).
  • Стиль - обращение на «ты», без канцелярита.

Чего мы не принимаем

  • Код без комментариев - читаемость важнее краткости.
  • Программы без объяснения - PR должен содержать описание, что и зачем.
  • Документацию без ссылок - каждое утверждение должно быть проверяемо.
  • Изменения без обсуждения - крупные фичи сначала обсуждаются в issue.
  • Плагиат - код и тексты должны быть написаны тобой.

Контакты

По любым вопросам открывай issue - публичное обсуждение полезнее личных сообщений.

Лицензия

Весь код проекта распространяется под GPL-3.0-or-later. Отправляя pull request, ты соглашаешься на распространение своего вклада под той же лицензией.

Спасибо, что дочитал до конца. Даже небольшая помощь - исправленная опечатка, добавленный пример, написанная утилита - делает проект лучше. Не бойся начинать с малого.