Инструкция для контрибьютеров
В этой инструкции собраны советы и подсказки для желающих сделать вклад в СДСМ. Ниже краткая справка о GitBook, необходимом софте, структуре проекта, рекомендации по оформлению, а также ссылка на список задач для контрибьютеров.
GitBook - это платформа, которая позволяет отображать репозиторий GitHub в виде книги. Вёрстка ведётся в синтаксисе Markdown, хотя на текущий момент это скорее обратная совместимость, но об этом подробнее в разделе Style Guide.
То, что отображается в правой колонке со структурой документа (оглавление), задаётся в файле SUMMARY.md. Если редактирование производится в веб-интерфейсе GitBook, SUMMARY.md обновляется автоматически. Однако если правки делаются в текстовом редакторе, нужно сознательно позаботиться и внести изменения в SUMMARY.md вручную.
Настало время познакомиться с 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.
Подготовьтесь к редактированию. Для редактирования в веб-интерфейсе нужно зарегистрироваться (или войти под учётной записью 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 - список дел.
Общие рекомендации:
Следите за орфографией и пунктуацией, используйте плагин 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 или в issues, а так же выставить приоритет. В список задач вы так же можете внести правки, добавить новые пункты или ответственно взять задачу на выполнение.
