/ CONTRIBUTING.md
CONTRIBUTING.md
1 # Инструкция для контрибьютеров 2 3 ## Помочь легко 4 5 В этой инструкции собраны советы и подсказки для желающих сделать вклад в СДСМ. Ниже краткая справка о GitBook, необходимом софте, структуре проекта, рекомендации по оформлению, а также ссылка на список задач для контрибьютеров. 6 7 GitBook - это платформа, которая позволяет отображать репозиторий GitHub в виде книги. Вёрстка ведётся в синтаксисе [Markdown](http://www.diy.ru/info/markdown/), хотя на текущий момент это скорее обратная совместимость, но об этом подробнее в разделе [Style Guide](CONTRIBUTING.md#style-guide). 8 9 То, что отображается в правой колонке со структурой документа (оглавление), задаётся в файле [SUMMARY.md](https://github.com/djvnsk/SDSM/tree/b80a758f7a63c381e6ff27d7f9c674f08e69f143/summary.md). Если редактирование производится в веб-интерфейсе GitBook, SUMMARY.md обновляется автоматически. Однако если правки делаются в текстовом редакторе, нужно сознательно позаботиться и внести изменения в SUMMARY.md вручную. 10 11 ## Pull Request Guidelines 12 13 Настало время познакомиться с Git и выбрать инструменты для редактирования. Опытные пользователи могут пропустить этот раздел. 14 15 1. Для начала установите Git.\ 16 В **Debian/Ubuntu** в командной строке необходимо выполнить:\ 17 `sudo apt-get install git`\ 18 В **Fedora**:\ 19 `yum install git-core`\ 20 В случае другой **\*nix** системы, предполагается что пользователь знает как устанавливать приложения из пакетов, исходников или любым другим способом.\ 21 В **macOS** можно воспользоваться графическим инсталлятором, либо установить через [MacPorts](http://www.macports.org). Если он уже установлен, в консоли необходимо выполнить команду:\ 22 `sudo port install git-core +doc +bash_completion +gitweb`\ 23 Для **Windows** необходимо скачать [exe-файл инсталлятора](http://msysgit.github.com/) со страницы проекта на GitHub'е и запустить его. После установки будет доступна как консольная, так и графическая версии Git. 24 2. Затем зарегистрируйтесь или вспомните свои логин и пароль на [github.com](https://github.com/join?source=login). 25 3. Создайте **fork** проекта [SDSM](https://github.com/eucariot/SDSM.git). Для этого нужно зайти на страницу проекта [SDSM](https://github.com/eucariot/SDSM.git) и нажать в правом верхнем углу кнопку "Fork". 26 4. Подготовьтесь к редактированию.\ 27 Для редактирования в веб-интерфейсе нужно зарегистрироваться (или войти под учётной записью GitHub) на [gitbook.com](https://gitbook.com), создать Workspace и импортировать в него свой fork-репозиторий.\ 28 Для редактирования в текстовом редакторе нужно сделать локальную копию репозитория. Для этого необходимо создать и перейдти в папку, где будет размещаться проект и склонировать репозиторий.\ 29 В **\*nix**:\ 30 `mkdir ~/SDSM cd ~/SDSM git clone https://github.com/eucariot/SDSM.git`\ 31 В этом случае копия репозитория будет сохранена в каталог SDSM в домашней папке пользователя, либо можно указать путь прямо в команде:\ 32 `git clone https://github.com/eucariot/SDSM.git path/to/folder`\ 33 В **Windows** всё делается аналогично, только мышкой в GitHub Desktop. 34 5. Редактируйте!\ 35 Вы можете вносить изменения в проект с помощью любого удобного инструмента: 36 37 * веб-интерфейс gitbook.com; 38 * текстовый редактор (желательно с поддержкой Markdown и Spell Check, попробуйте Atom и Typora) или IDE; 39 * консоль; 40 * some else... 41 42 **Важно:** мы очень рекомендуем править статьи в веб-интерфейсе GitBook. Причин несколько, главная - гитбук автоматически причёсывает синтаксис, следит за оглавлением (SUMMARY.md) и лишь обратно совместим с Markdown и GitHub (например, уже по-другому обрабатывает переносы строк). Так же в данном проекте решено размещать картинки именно на GitBook. Добавляются они простым копипастом и в таком случае становятся масштабируемыми. 43 44 6. После внесения изменений нужно закоммитить их в свой репозиторий (**fork** оригинального проекта).\ 45 В **\*nix**:\ 46 `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).\ 47 `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):\ 48 `git commit -m "что, где и зачем было сделано"`\ 49 `git push origin master` - push в master ветку своего репозитория.\ 50 [Подробнее](https://guides.github.com/introduction/git-handbook/) о `git push`, ветках и т.п. Ну и в целом, рекомендуется хотя бы пролистать [инструкцию](https://git-scm.com/book/ru/v2) или пройти небольшой интерактивный курс - [раз](https://try.github.io/), [два](https://githowto.com/ru).\ 51 В **Windows** всё примерно так же. 52 7. Чтобы изменения стали общественным достоянием, а не пылились в вашем форке, нужно создать pull request в оригинальный репозиторий [SDSM](https://github.com/eucariot/SDSM.git). Сделать это можно разными способами, для простоты лучше зайти на страницу своего репозитория на GitHub, выбрать **New pull request**, в качестве источника выбрать ветку в своём репозитории (если вы не делали лишних движений, то ветка будет одна и это master), в качестве получателя - master проекта eucariot/SDSM.\ 53 Проверить вносимые изменения, подтвердить создание pull request.\ 54 В качестве комментария указать какие изменения были внесены, желательно писать человекопонятные комментарии, [подробнее](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). 55 56 Рекомендуется коммитить и создавать pull request каждый раз, когда выполнена логически завершенная часть изменений (например, изменения в конкретной статье или изменения, затрагивающие однотипные действия, например исправление ссылок). 57 58 **Важно:** делайте `git pull` каждый раз перед началом работы. Иначе можно словить merge конфликт, когда один и тот же документ правили двое и долго этот конфликт разрешать. Соответственно pull request тоже лучше делать почаще. 59 60 ## Структура проекта 61 62 GitBook автоматически превращает каждый раздел в каталог, а страницу в файл, название транслитерируется и переводится в нижний регистр. Поэтому при добавлении или правке вне веб-интерфейса GitBook необходимо соблюдать те же принципы. 63 64 Например: 65 66 * **SDSM** - корень книги. 67 * **14.-packet-life** - раздел книги, каталог с одной статьёй из цикла, число `14` в имени - порядковый номер статьи, `packet-life` - название статьи. 68 * **README.md** - предисловие, текст, который будет отображаться при переходе в этот раздел книги. 69 * **0.-korotko-o-sudbe-i-puti-paketa.md** - логически отделяемый раздел статьи без подразделов, где `0` - номер раздела, `korotko-o-sudbe-i-puti-paketa` - заголовок. 70 * **1.-urovni-i-ploskosti** - следующий логический отделимый раздел статьи, уже с подразделами. 71 * **README.md** - предисловие. 72 * **control-plane.md** - подраздел раздела. 73 * ... 74 * **15.-qos** - раздел книги, каталог с другой статьёй из цикла. 75 * **README.md** - предисловие. 76 * **0.-chem-opredelyaetsya-qos** - раздел с подразделами. 77 * **README.md** - предисловие. 78 * **dzhitter.md** - подраздел раздела. 79 * ... 80 * **README.md** - предисловие книги. 81 * **SUMMARY.md** - оглавление. 82 * **TODO.md** - список дел. 83 84 ## Style guide 85 86 Общие рекомендации: 87 88 * Следите за орфографией и пунктуацией, используйте плагин Spell Check в вашем любимом редакторе или проверяйте получившийся текст в Word, только без маниакальности; 89 * Использование буквы "ё" приветствуется; 90 * Не забывайте про знаки препинания и пробелы (или их отсутствие) вокруг них, корректное оформление улучшает читаемость; 91 * Придерживайтесь одного стиля изложения; 92 * Сохраняйте обращение к читателю на "вы", как к коллеге и товарищу; 93 * Старайтесь минимизировать использование слэнговой лексики; 94 * Сохраняйте терминологию и формулировки хотя бы в рамках одной статьи (роутер, рутер, маршрутизатор). Не используйте перевод или транслитерацию терминов, названий фирм, сервисов и пр. Очевидно есть исключения для слов, вошедших в повседневное и повсеместное употребление. Пользуйтесь словарём [https://lookmeup.linkmeup.ru](https://lookmeup.linkmeup.ru), хотя его работоспособность сейчас под вопросом (как на счёт переноса на GitBook?); 95 * При использовании сокращений и аббревиатур, укажите термин в полном виде при первом упоминании в статье; 96 * Избегайте формулировок, допускающих толкование. 97 * Помните про авторские права при размещении изображений, видео и других материалов, найденных на просторах интернета. 98 99 Рекомендации по оформлению: Для знакомства с Markdown можно пройти [10 минутный интерактивный курс](https://commonmark.org/help/tutorial/), затем пользоваться [шпаргалкой](https://commonmark.org/help/) или [страницей](https://www.markdownguide.org/cheat-sheet) с ссылками на Basic Syntax и Extended Syntax. 100 101 **Важно:** в новой версии GitBook [поменялся подход](https://docs.gitbook.com/v2-changes/important-differences#editing-markdown-source) к рендерингу, редактированию и хранению документов, т.е. хранение в GitHub в синтаксисе Markdown это лишь обратная совместимость. Поэтому для редактирования сложных блоков, структуры книги, вставки изображений и пр. рекомендуется использовать именно веб-интерфейс.\ 102 Так, например, при первом коммите из интерфейса GitBook производится "нормализация" всего содержимого, изменения обычно касаются всех файлов, поэтому коммит получается очень большим. И далеко не всегда изменения не ломают и не затирают что-то, будьте внимательны. 103 104 * Используйте относительные, а не абсолютные ссылки на страницы и разделы книги. Чтобы добавить ссылку в веб-интерфейсе, нужно сначала набрать название страницы, затем выбрать либо саму страницу, либо заголовок (это которые h1, h2, h3) на этой странице. Добавить ссылку на файл, не включенный в SUMMARY.md, через веб-интерфейс не получится. Но это можно сделать в текстовом редакторе или непосредственно на GitHub, синтаксис можно посмотреть в исходниках SUMMARY.md; 105 * Используйте заголовки не более двух уровней вложенности. Если их больше, значит это повод задуматься о разбиении статьи на разделы или подразделы; 106 * Помещайте код, листинги и результаты выполнения команд в блок `code`; 107 * Выставляйте выравнивание по центру для объектов, поддерживающих такую функцию (изображения, встраиваемые плееры, таблицы и т.п.); 108 * Оформляйте списки правильно (примерно как тот, который вы сейчас читаете); 109 * При использовании текстовых редакторов помните об [экранировании](https://www.markdownguide.org/basic-syntax/#escaping-characters) служебных символов. 110 111 ## To-Do list 112 113 Нужно определиться с местом хранения списка задач - в [To-Do list](https://github.com/djvnsk/SDSM/tree/2a11b2f5445db77992468e0ee336d06eb2619d2d/TODO.md) или в issues, а так же выставить приоритет. В список задач вы так же можете внести правки, добавить новые пункты или ответственно взять задачу на выполнение.