Инструкция для контрибьютеров

Помочь легко

В этой инструкции собраны советы и подсказки для желающих сделать вклад в СДСМ. Ниже краткая справка о GitBook, необходимом софте, структуре проекта, рекомендации по оформлению, а также ссылка на список задач для контрибьютеров.

GitBook - это платформа, которая позволяет отображать репозиторий GitHub в виде книги. Вёрстка ведётся в синтаксисе Markdown, хотя на текущий момент это скорее обратная совместимость, но об этом подробнее в разделе Style Guide.

То, что отображается в правой колонке со структурой документа (оглавление), задаётся в файле SUMMARY.md. Если редактирование производится в веб-интерфейсе GitBook, SUMMARY.md обновляется автоматически. Однако если правки делаются в текстовом редакторе, нужно сознательно позаботиться и внести изменения в SUMMARY.md вручную.

Pull Request Guidelines

Настало время познакомиться с Git и выбрать инструменты для редактирования. Опытные пользователи могут пропустить этот раздел.

Для начала установите Git. В Debian/Ubuntu в командной строке необходимо выполнить: sudo apt-get install git В Fedora: yum install git-core В случае другой *nix системы, предполагается что пользователь знает как устанавливать приложения из пакетов, исходников или любым другим способом. В macOS можно воспользоваться графическим инсталлятором, либо установить через MacPorts. Если он уже установлен, в консоли необходимо выполнить команду: sudo port install git-core +doc +bash_completion +gitweb Для Windows необходимо скачать exe-файл инсталлятора со страницы проекта на GitHub'е и запустить его. После установки будет доступна как консольная, так и графическая версии Git.
Затем зарегистрируйтесь или вспомните свои логин и пароль на github.com.
Создайте fork проекта SDSM. Для этого нужно зайти на страницу проекта SDSM и нажать в правом верхнем углу кнопку "Fork".
Подготовьтесь к редактированию. Для редактирования в веб-интерфейсе нужно зарегистрироваться (или войти под учётной записью GitHub) на gitbook.com, создать Workspace и импортировать в него свой fork-репозиторий. Для редактирования в текстовом редакторе нужно сделать локальную копию репозитория. Для этого необходимо создать и перейдти в папку, где будет размещаться проект и склонировать репозиторий. В *nix: mkdir ~/SDSM cd ~/SDSM git clone https://github.com/eucariot/SDSM.git В этом случае копия репозитория будет сохранена в каталог SDSM в домашней папке пользователя, либо можно указать путь прямо в команде: git clone https://github.com/eucariot/SDSM.git path/to/folder В Windows всё делается аналогично, только мышкой в GitHub Desktop.
Редактируйте! Вы можете вносить изменения в проект с помощью любого удобного инструмента:

веб-интерфейс gitbook.com;
текстовый редактор (желательно с поддержкой Markdown и Spell Check, попробуйте Atom и Typora) или IDE;
консоль;
some else...

Важно: мы очень рекомендуем править статьи в веб-интерфейсе GitBook. Причин несколько, главная - гитбук автоматически причёсывает синтаксис, следит за оглавлением (SUMMARY.md) и лишь обратно совместим с Markdown и GitHub (например, уже по-другому обрабатывает переносы строк). Так же в данном проекте решено размещать картинки именно на GitBook. Добавляются они простым копипастом и в таком случае становятся масштабируемыми.

После внесения изменений нужно закоммитить их в свой репозиторий (fork оригинального проекта). В *nix: git add . - добавить изменённые файлы, подробнее. git commit - закоммитить изменения в репозиторий, либо сразу с комментарием: git commit -m "что, где и зачем было сделано" git push origin master - push в master ветку своего репозитория. Подробнее о git push, ветках и т.п. Ну и в целом, рекомендуется хотя бы пролистать инструкцию или пройти небольшой интерактивный курс - раз, два. В Windows всё примерно так же.
Чтобы изменения стали общественным достоянием, а не пылились в вашем форке, нужно создать pull request в оригинальный репозиторий SDSM. Сделать это можно разными способами, для простоты лучше зайти на страницу своего репозитория на GitHub, выбрать New pull request, в качестве источника выбрать ветку в своём репозитории (если вы не делали лишних движений, то ветка будет одна и это master), в качестве получателя - master проекта eucariot/SDSM. Проверить вносимые изменения, подтвердить создание pull request. В качестве комментария указать какие изменения были внесены, желательно писать человекопонятные комментарии, подробнее.

Рекомендуется коммитить и создавать pull request каждый раз, когда выполнена логически завершенная часть изменений (например, изменения в конкретной статье или изменения, затрагивающие однотипные действия, например исправление ссылок).

Важно: делайте git pull каждый раз перед началом работы. Иначе можно словить merge конфликт, когда один и тот же документ правили двое и долго этот конфликт разрешать. Соответственно pull request тоже лучше делать почаще.

Структура проекта

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

Например:

SDSM - корень книги.
- 14.-packet-life - раздел книги, каталог с одной статьёй из цикла, число 14 в имени - порядковый номер статьи, packet-life - название статьи.
  - README.md - предисловие, текст, который будет отображаться при переходе в этот раздел книги.
  - 0.-korotko-o-sudbe-i-puti-paketa.md - логически отделяемый раздел статьи без подразделов, где 0 - номер раздела, korotko-o-sudbe-i-puti-paketa - заголовок.
  - 1.-urovni-i-ploskosti - следующий логический отделимый раздел статьи, уже с подразделами.
    README.md - предисловие.
    control-plane.md - подраздел раздела.
    ...
- 15.-qos - раздел книги, каталог с другой статьёй из цикла.
  - README.md - предисловие.
  - 0.-chem-opredelyaetsya-qos - раздел с подразделами.
    README.md - предисловие.
    dzhitter.md - подраздел раздела.
    ...
- README.md - предисловие книги.
- SUMMARY.md - оглавление.
- TODO.md - список дел.

Style guide

Общие рекомендации:

Следите за орфографией и пунктуацией, используйте плагин Spell Check в вашем любимом редакторе или проверяйте получившийся текст в Word, только без маниакальности;
Использование буквы "ё" приветствуется;
Не забывайте про знаки препинания и пробелы (или их отсутствие) вокруг них, корректное оформление улучшает читаемость;
Придерживайтесь одного стиля изложения;
Сохраняйте обращение к читателю на "вы", как к коллеге и товарищу;
Старайтесь минимизировать использование слэнговой лексики;
Сохраняйте терминологию и формулировки хотя бы в рамках одной статьи (роутер, рутер, маршрутизатор). Не используйте перевод или транслитерацию терминов, названий фирм, сервисов и пр. Очевидно есть исключения для слов, вошедших в повседневное и повсеместное употребление. Пользуйтесь словарём https://lookmeup.linkmeup.ru, хотя его работоспособность сейчас под вопросом (как на счёт переноса на GitBook?);
При использовании сокращений и аббревиатур, укажите термин в полном виде при первом упоминании в статье;
Избегайте формулировок, допускающих толкование.
Помните про авторские права при размещении изображений, видео и других материалов, найденных на просторах интернета.

Рекомендации по оформлению: Для знакомства с Markdown можно пройти 10 минутный интерактивный курс, затем пользоваться шпаргалкой или страницей с ссылками на Basic Syntax и Extended Syntax.

Важно: в новой версии GitBook поменялся подход к рендерингу, редактированию и хранению документов, т.е. хранение в GitHub в синтаксисе Markdown это лишь обратная совместимость. Поэтому для редактирования сложных блоков, структуры книги, вставки изображений и пр. рекомендуется использовать именно веб-интерфейс. Так, например, при первом коммите из интерфейса GitBook производится "нормализация" всего содержимого, изменения обычно касаются всех файлов, поэтому коммит получается очень большим. И далеко не всегда изменения не ломают и не затирают что-то, будьте внимательны.

Используйте относительные, а не абсолютные ссылки на страницы и разделы книги. Чтобы добавить ссылку в веб-интерфейсе, нужно сначала набрать название страницы, затем выбрать либо саму страницу, либо заголовок (это которые h1, h2, h3) на этой странице. Добавить ссылку на файл, не включенный в SUMMARY.md, через веб-интерфейс не получится. Но это можно сделать в текстовом редакторе или непосредственно на GitHub, синтаксис можно посмотреть в исходниках SUMMARY.md;
Используйте заголовки не более двух уровней вложенности. Если их больше, значит это повод задуматься о разбиении статьи на разделы или подразделы;
Помещайте код, листинги и результаты выполнения команд в блок code;
Выставляйте выравнивание по центру для объектов, поддерживающих такую функцию (изображения, встраиваемые плееры, таблицы и т.п.);
Оформляйте списки правильно (примерно как тот, который вы сейчас читаете);
При использовании текстовых редакторов помните об экранировании служебных символов.

To-Do list

Нужно определиться с местом хранения списка задач - в To-Do list или в issues, а так же выставить приоритет. В список задач вы так же можете внести правки, добавить новые пункты или ответственно взять задачу на выполнение.

PreviousСпасибы

Last updated 1 year ago