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

## Помочь легко

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

GitBook - это платформа, которая позволяет отображать репозиторий GitHub в виде книги. Вёрстка ведётся в синтаксисе [Markdown](http://www.diy.ru/info/markdown/), хотя на текущий момент это скорее обратная совместимость, но об этом подробнее в разделе [Style Guide](#style-guide).

То, что отображается в правой колонке со структурой документа (оглавление), задаётся в файле [SUMMARY.md](https://github.com/djvnsk/SDSM/tree/b80a758f7a63c381e6ff27d7f9c674f08e69f143/summary.md). Если редактирование производится в веб-интерфейсе GitBook, SUMMARY.md обновляется автоматически. Однако если правки делаются в текстовом редакторе, нужно сознательно позаботиться и внести изменения в SUMMARY.md вручную.

## Pull Request Guidelines

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

1. Для начала установите Git.\
   В **Debian/Ubuntu** в командной строке необходимо выполнить:\
   `sudo apt-get install git`\
   В **Fedora**:\
   `yum install git-core`\
   В случае другой **\*nix** системы, предполагается что пользователь знает как устанавливать приложения из пакетов, исходников или любым другим способом.\
   В **macOS** можно воспользоваться графическим инсталлятором, либо установить через [MacPorts](http://www.macports.org). Если он уже установлен, в консоли необходимо выполнить команду:\
   `sudo port install git-core +doc +bash_completion +gitweb`\
   Для **Windows** необходимо скачать [exe-файл инсталлятора](http://msysgit.github.com/) со страницы проекта на GitHub'е и запустить его. После установки будет доступна как консольная, так и графическая версии Git.
2. Затем зарегистрируйтесь или вспомните свои логин и пароль на [github.com](https://github.com/join?source=login).
3. Создайте **fork** проекта [SDSM](https://github.com/eucariot/SDSM.git). Для этого нужно зайти на страницу проекта [SDSM](https://github.com/eucariot/SDSM.git) и нажать в правом верхнем углу кнопку "Fork".
4. Подготовьтесь к редактированию.\
   Для редактирования в веб-интерфейсе нужно зарегистрироваться (или войти под учётной записью GitHub) на [gitbook.com](https://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.
5. Редактируйте!\
   Вы можете вносить изменения в проект с помощью любого удобного инструмента:

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

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

6. После внесения изменений нужно закоммитить их в свой репозиторий (**fork** оригинального проекта).\
   В **\*nix**:\
   `git add .` - добавить изменённые файлы, [подробнее](https://git-scm.com/book/ru/v2/Appendix-C%3A-%D0%9A%D0%BE%D0%BC%D0%B0%D0%BD%D0%B4%D1%8B-Git-%D0%9E%D1%81%D0%BD%D0%BE%D0%B2%D0%BD%D1%8B%D0%B5-%D0%BA%D0%BE%D0%BC%D0%B0%D0%BD%D0%B4%D1%8B).\
   `git commit` - закоммитить изменения в репозиторий, либо [сразу с комментарием](https://git-scm.com/book/ru/v2/%D0%9E%D1%81%D0%BD%D0%BE%D0%B2%D1%8B-Git-%D0%97%D0%B0%D0%BF%D0%B8%D1%81%D1%8C-%D0%B8%D0%B7%D0%BC%D0%B5%D0%BD%D0%B5%D0%BD%D0%B8%D0%B9-%D0%B2-%D1%80%D0%B5%D0%BF%D0%BE%D0%B7%D0%B8%D1%82%D0%BE%D1%80%D0%B8%D0%B9):\
   `git commit -m "что, где и зачем было сделано"`\
   `git push origin master` - push в master ветку своего репозитория.\
   [Подробнее](https://guides.github.com/introduction/git-handbook/) о `git push`, ветках и т.п. Ну и в целом, рекомендуется хотя бы пролистать [инструкцию](https://git-scm.com/book/ru/v2) или пройти небольшой интерактивный курс - [раз](https://try.github.io/), [два](https://githowto.com/ru).\
   В **Windows** всё примерно так же.
7. Чтобы изменения стали общественным достоянием, а не пылились в вашем форке, нужно создать pull request в оригинальный репозиторий [SDSM](https://github.com/eucariot/SDSM.git). Сделать это можно разными способами, для простоты лучше зайти на страницу своего репозитория на GitHub, выбрать **New pull request**, в качестве источника выбрать ветку в своём репозитории (если вы не делали лишних движений, то ветка будет одна и это master), в качестве получателя - master проекта eucariot/SDSM.\
   Проверить вносимые изменения, подтвердить создание pull request.\
   В качестве комментария указать какие изменения были внесены, желательно писать человекопонятные комментарии, [подробнее](https://git-scm.com/book/ru/v2/%D0%A0%D0%B0%D1%81%D0%BF%D1%80%D0%B5%D0%B4%D0%B5%D0%BB%D0%B5%D0%BD%D0%BD%D1%8B%D0%B9-Git-Contributing-to-a-Project).

Рекомендуется коммитить и создавать 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 минутный интерактивный курс](https://commonmark.org/help/tutorial/), затем пользоваться [шпаргалкой](https://commonmark.org/help/) или [страницей](https://www.markdownguide.org/cheat-sheet) с ссылками на Basic Syntax и Extended Syntax.

**Важно:** в новой версии GitBook [поменялся подход](https://docs.gitbook.com/v2-changes/important-differences#editing-markdown-source) к рендерингу, редактированию и хранению документов, т.е. хранение в GitHub в синтаксисе Markdown это лишь обратная совместимость. Поэтому для редактирования сложных блоков, структуры книги, вставки изображений и пр. рекомендуется использовать именно веб-интерфейс.\
Так, например, при первом коммите из интерфейса GitBook производится "нормализация" всего содержимого, изменения обычно касаются всех файлов, поэтому коммит получается очень большим. И далеко не всегда изменения не ломают и не затирают что-то, будьте внимательны.

* Используйте относительные, а не абсолютные ссылки на страницы и разделы книги. Чтобы добавить ссылку в веб-интерфейсе, нужно сначала набрать название страницы, затем выбрать либо саму страницу, либо заголовок (это которые h1, h2, h3) на этой странице. Добавить ссылку на файл, не включенный в SUMMARY.md, через веб-интерфейс не получится. Но это можно сделать в текстовом редакторе или непосредственно на GitHub, синтаксис можно посмотреть в исходниках SUMMARY.md;
* Используйте заголовки не более двух уровней вложенности. Если их больше, значит это повод задуматься о разбиении статьи на разделы или подразделы;
* Помещайте код, листинги и результаты выполнения команд в блок `code`;
* Выставляйте выравнивание по центру для объектов, поддерживающих такую функцию (изображения, встраиваемые плееры, таблицы и т.п.);
* Оформляйте списки правильно (примерно как тот, который вы сейчас читаете);
* При использовании текстовых редакторов помните об [экранировании](https://www.markdownguide.org/basic-syntax/#escaping-characters) служебных символов.

## To-Do list

Нужно определиться с местом хранения списка задач - в [To-Do list](https://github.com/djvnsk/SDSM/tree/2a11b2f5445db77992468e0ee336d06eb2619d2d/TODO.md) или в issues, а так же выставить приоритет. В список задач вы так же можете внести правки, добавить новые пункты или ответственно взять задачу на выполнение.