Skip to content

Latest commit

 

History

History
81 lines (47 loc) · 6.82 KB

CONTRIBUTING_RU.md

File metadata and controls

81 lines (47 loc) · 6.82 KB
Raw
title version
Вклад в документацию XOD
1.0.0

Вклад в документацию XOD

Если вы хотите улучшить документацию XOD, то мы заранее благодарны! Предложение ваших правок не является наукой о ракетостроении, хотя и требует некоторых усилий, чтобы освоиться, особенно если вы никогда раньше не вносили свой вклад в проект с открытым исходным кодом.

Цикл изменений

  1. Сделать ответвление этого репозитория
  2. Внести изменения
  3. Создать запрос на слияние (Pull Request)
  4. Ждать визирование изменений
  5. Исправить указанные ошибки
  6. Любоваться изменениями на https://xod.io/docs/

Есть два пути для выполнения первых трёх шагов

Быстрый. Если нужно исправить опечатку или очень мелкую правку, то можно просто использовать веб версию GitHub без установки дополнительных инструментов. Чтобы научиться это делать прочтите руководство по внесению изменений в чужие репозитарии. Использование веб интерфейса для внесения больших изменений не приветствуется, так как такими правками очень тяжело управлять, проверять их, обновлять и визировать.

Полный. Сделать клон своего ответвления, создать ветку, внести изменения с помощью своего любимого редактора текста, отправить и создать запрос на внесение. Читайте руководство по ветвлению проектов.

Как только вы создадите запрос на внесение, мы завизируем изменения как можно быстрее. Обычно это происходит в течении одного дня. Мы может попросить внести некоторые правки. В этом случае вносите правки в этот же запрос на внесение (PR), и всё, не нужно закрывать и вновь открывать существующий PR.

Когда PR принят и объединён с master веткой, ваши изменения очень скоро появятся на боевом сервере.

Подготовка к публикации

Если вы делаете не тривиальные изменения, убедитесь, что запустили Prettier для приведения форматирования файлов к единому стилю оформления.

Для запуска у вас должны быть установлены в системе: командная строка, NodeJS и Yarn. Откройте командную строку в папке своего репозитария и выполните команду:

$ yarn
# Установит Prettier. Достаточно запустить один всего раз

$ yarn prettier ./docs/path/to/your/FILE.md
# Переформатирует и сохранит указанный файл

Названия для веток и сообщения фиксации изменений

В этом репозитарии нет строгих правил именования веток и сообщений коммитов. Давайте им простые и понятные названия, без фанатизма.

Все фиксации в запросе на внесении будут объединены в единый коммит и при необходимости перефразированы перед слиянием в master.

Основные сценарии

Исправления опечаток или грамматики

Используйте быстрый путь.

Найдите Markdown файл содержащий ошибку и нажмите кнопку "Edit this page" в веб интерфейсе. Исправьте ошибки используя браузер. Увеличьте номер патча в поле version вводной части.

Если поле version не указано, то добавьте это поле с значением 1.0.1.

Для фиксации изменений нажмите внизу страницы "Propose file change" и создайте запрос на слияние кнопкой "Pull request".

Перевод статей

Используйте полный путь. Форкните, клонируйте, создайте ветку.

Создайте новый файл рядом с README.md с именем, отражающим целевой язык (DE.md, IT.md, PT.md, FR.md, ES.md, UA.md, JA.md, KO.md, CN.md).

Запишите в этом файле перевод содержимого из README.md. Используйте разметку Markdown, а идентификаторы XOD заключайте в обратные кавычки.

Отправьте изменения (git push) и откройте запрос на слияние (pull request)

Предпочтительно отправлять по одной статье в каждом запросе на слияние, это ускорит процесс проверки и принятия изменений.

Добавление проекта на витрину

Используйте полный путь, потому что вам нужно будет добавить изображение. Форкните, клонируйте, создайте ветку.

Добавьте миниатюру вашего проекта в ./docs/__img__. Отдавайте предпочтение фотографиям, а не коллажам и JPG вместо PNG.

Добавьте новую карту проекта в ./docs/showcase.yaml. Всегда добавляйте карты в самое начало списка: новые проекты всегда первые.

Отправьте изменения (git push) и откройте запрос на слияние (pull request)