# Инструкция для контрибьютеров ## Помочь легко В этой инструкции собраны советы и подсказки для желающих сделать вклад в СДСМ. Ниже краткая справка о 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, только без маниакальности; * Использование буквы "ё" приветствуется; * Не забывайте про знаки препинания и пробелы (или их отсутствие) вокруг них, корректное оформление улучшает читаемость; * Придерживайтесь одного стиля изложения; * Сохраняйте обращение к читателю на "вы", как к коллеге и товарищу; * Старайтесь минимизировать использование слэнговой лексики; * Сохраняйте терминологию и формулировки хотя бы в рамках одной статьи (роутер, рутер, маршрутизатор). Не используйте перевод или транслитерацию терминов, названий фирм, сервисов и пр. Очевидно есть исключения для слов, вошедших в повседневное и повсеместное употребление. Пользуйтесь словарём , хотя его работоспособность сейчас под вопросом (как на счёт переноса на 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, а так же выставить приоритет. В список задач вы так же можете внести правки, добавить новые пункты или ответственно взять задачу на выполнение. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://linkmeup.gitbook.io/sdsm/contributing.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.