Skip to content

Latest commit

 

History

History
119 lines (89 loc) · 16.9 KB

contributing.md

File metadata and controls

119 lines (89 loc) · 16.9 KB

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

Помочь легко

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

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

То, что отображается в правой колонке со структурой документа (оглавление), задаётся в файле 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. Если он уже установлен, в консоли необходимо выполнить команду:
    sudo port install git-core +doc +bash_completion +gitweb
    Для Windows необходимо скачать exe-файл инсталлятора со страницы проекта на GitHub'е и запустить его. После установки будет доступна как консольная, так и графическая версии Git.

  2. Затем зарегистрируйтесь или вспомните свои логин и пароль на github.com.

  3. Создайте fork проекта SDSM. Для этого нужно зайти на страницу проекта SDSM и нажать в правом верхнем углу кнопку "Fork".

  4. Подготовьтесь к редактированию.
    Для редактирования в веб-интерфейсе нужно зарегистрироваться (или войти под учётной записью 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.

  5. Редактируйте!
    Вы можете вносить изменения в проект с помощью любого удобного инструмента:

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

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

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

  2. Чтобы изменения стали общественным достоянием, а не пылились в вашем форке, нужно создать 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, а так же выставить приоритет. В список задач вы так же можете внести правки, добавить новые пункты или ответственно взять задачу на выполнение.