Skip to content

Latest commit

 

History

History
265 lines (155 loc) · 14.7 KB

CONTRIBUTING.md

File metadata and controls

265 lines (155 loc) · 14.7 KB

Инструкция по работе с репозиторием

В этом репозитории мы собираем информацию о выступлениях наших сотрудников на публичных мероприятиях: описания, слайды, ссылки на записи и прочие важные штуки. Чтобы облегчить работу с репозиторием в будущем, в этом файле описано, каких правил мы придерживаемся при его оформлении.

Воркфлоу работы с репозиторием

  1. Прочитайте этот файл до конца и настройте всё, что необходимо.

  2. Создайте новую ветку с названием вида feature/meetup-name, bugfix/typos и т. п.

  3. Закоммитьте в неё все свои правки. Коммиты должны быть написаны по-русски (смотрите историю репозитория для примера).

  4. Создайте PR из своей ветки в master. Из названия PR должно быть понятно, о чём он (смотрите историю смерженных PR для примера).

Если вы всё сделали, как описано выше, то после проверки и обсуждений ответственный за репозиторий смержит правки.

Обсуждение в PR, как и вообще всё в этом репозитории, — на русском.

Git LFS

Eсли вам нужно добавить, изменить или удалить PDF-файл какого-то выступления, то сперва необходимо установить Git LFS:

  1. Перейти на git-lfs.github.com.

  2. Скачать и установить версию Git LFS для своей ОС.

  3. В консоли выполнить git lfs install.

  4. Склонировать этот репозиторий.

  5. Проверить, что хуки для LFS в репозитории автоматически установились:

$ cat .git/hooks/post-commit
#!/bin/sh
command -v git-lfs >/dev/null 2>&1 || { echo >&2 "\nThis repository is configured for Git LFS but 'git-lfs' was not found on your path. If you no longer wish to use Git LFS, remove this hook by deleting .git/hooks/post-commit.\n"; exit 2; }
git lfs post-commit "$@"

Если всё прошло успешно, то все PDF-файлы будут автоматически загружаться в LFS.

Файловая структура

Информация о каждом выступлении находится в двух местах: в корневом README.md и в папке с митапом.

Путь до папки каждого выступления выглядит так: ./meetups/YYYY-MM-DD-SHORT_MEETUP_NAME/XX-SHORT_TALK_NAME. Здесь:

  • YYYY, MM, DD — год, месяц и день, когда проходил митап. Числами. Месяц и день — с ведущим нулём. Если вдруг митап проходит несколько дней, то можно или разбить его на части, и для каждого дня создать отдельную папку, или же указать в качестве даты первый день.

  • SHORT_MEETUP_NAME — краткое название митапа на латинице. Слова вроде «митап», «конференция» и пр. из названия нужно убирать, т. к. и так понятно, о чём речь.

  • XX — номер доклада по порядку, с ведущим нулём. Считаются только доклады наших сотрудников. Так, если всего на митапе было десять докладов, из них только три — наши, то номера будут: 01, 02, 03.

  • SHORT_TALK_NAME — краткое название доклада на латинице. Совсем уж сокращать не стоит, из названия папки должно быть понятно, о чём речь.

Внутри папки каждого выступления обычно должно быть как минимум два файла:

  • README.md — файл с описанием доклада.

  • SHORT_TALK_NAME.pdf — файл со слайдами. Здесь SHORT_TALK_NAME — то же самое имя, что используется в названии папки.

Описание митапа на главной странице

В корневом README.md все митапы перечисляются в обратном хронологическом порядке (новые — вверху), и разбиваются по годам.

В общем случае, шаблон этого файла примерно такой:

## YYYY

### FULL_MEETUP_NAME, D MMMM

- **[FULL_TALK_NAME](/meetups/YYYY-MM-DD-SHORT_MEETUP_NAME/XX-SHORT_TALK_NAME/)**, SPEAKER_NAME<br>
  SHORT_TALK_DESCRIPTION
  
- **[FULL_TALK_NAME](/meetups/YYYY-MM-DD-SHORT_MEETUP_NAME/XX-SHORT_TALK_NAME/)**, SPEAKER_NAME<br>
  SHORT_TALK_DESCRIPTION


### FULL_MEETUP_NAME, D MMMM

- **[FULL_TALK_NAME](/meetups/YYYY-MM-DD-SHORT_MEETUP_NAME/XX-SHORT_TALK_NAME/)**, SPEAKER_NAME<br>
  SHORT_TALK_DESCRIPTION
  
- **[FULL_TALK_NAME](/meetups/YYYY-MM-DD-SHORT_MEETUP_NAME/XX-SHORT_TALK_NAME/)**, SPEAKER_NAME<br>
  SHORT_TALK_DESCRIPTION

----

## YYYY

### FULL_MEETUP_NAME, D MMMM

- **[FULL_TALK_NAME](/meetups/YYYY-MM-DD-SHORT_MEETUP_NAME/XX-SHORT_TALK_NAME/)**, SPEAKER_NAME<br>
  SHORT_TALK_DESCRIPTION
  
- **[FULL_TALK_NAME](/meetups/YYYY-MM-DD-SHORT_MEETUP_NAME/XX-SHORT_TALK_NAME/)**, SPEAKER_NAME<br>
  SHORT_TALK_DESCRIPTION


### FULL_MEETUP_NAME, D MMMM

- **[FULL_TALK_NAME](/meetups/YYYY-MM-DD-SHORT_MEETUP_NAME/XX-SHORT_TALK_NAME/)**, SPEAKER_NAME<br>
  SHORT_TALK_DESCRIPTION
  
- **[FULL_TALK_NAME](/meetups/YYYY-MM-DD-SHORT_MEETUP_NAME/XX-SHORT_TALK_NAME/)**, SPEAKER_NAME<br>
  SHORT_TALK_DESCRIPTION
Пример оформленного по этому шаблону README.md 
## 2020

### Innopolis Ruby Meetup, 1 октября

- **[Автоматизируем синхронизацию HTTP API и документации](/meetups/2020-10-01-innopolis-ruby/01-api-docs-sync/)**, Дмитрий Ефимов<br>
  Про конфликт документации по API и её реализации, и про способы его разрешения.


### Open DDD Meetup, 22 сентября

- **[Старт в новой предметной области на примере RCS](/meetups/2020-09-22-open-ddd/01-rcs/)**, Александр Лукашкин<br>
  Про практики и принципы DDD, которые использует команда RCS для старта разработки в новой предметной области.

----

## 2019

### Митап фронтенда, 3 сентября

- **[Svelte. Лёгкий — не значит быстрый](/meetups/2020-09-03-frontend/01-svelte/)**, Евгений Пономарёв<br>
  Про сравнение производительности Svelte и React.

- **[Интересные решения в webpack](/meetups/2020-09-03-frontend/02-webpack/)**, Егор Баранов<br>
  Про экосистему вокруг webpack.

- **[Создаем реалистичную 3D графику в браузере](/meetups/2020-09-03-frontend/03-3d-graphics/)**, Ирина Романова<br>
  Про 2D/3D-графику в браузере с Three.js и Cannon.js.

- **[Знакомство с CSS Grid](/meetups/2020-09-03-frontend/04-css-grid/)**, Галина Григорьева<br>
  Про технологию CSS Grid, IE11 и сравнение с Flexbox.

- **[Legacy. Иллюзия контроля](/meetups/2020-09-03-frontend/05-legacy/)**, Заурбек Будтуев<br>
  Про легаси в контексте тестов, требований, документации и кода.


### IT Analyst Meetup, 27 августа

- **[Аналитика на длинной дистанции: как ничего не забыть и потом не переделывать](/meetups/2020-08-27-it-analyst/01-solution-analytics/)**, Яна Тодорович<br>
  Про структуру документации, приоритизацию аналитических задач, важность нейминга фич и их проработки, согласование документации с заказчиком и командой.

Здесь:

  • FULL_MEETUP_NAME — полное название митапа, на русском языке. Тут слова «митап», «конференция» и пр. уже не опускаем. Используем официально объявленные организаторами названия.

  • D, MMMM — число и месяц даты митапа, где число без ведущего нуля, а месяц — по-русски и с маленькой буквы.

  • FULL_TALK_NAME — полное название доклада, на русском языке.

  • SPEAKER_NAME — имя выступающего.

  • SHORT_TALK_DESCRIPTION — краткое описание доклада. Стоит придерживаться формата, отвечающего на вопрос: «А про что доклад?». «Про ...».

  • Все остальные переменные такие же, как и описанные ранее.

NB: Не забудьте про <br> после имени выступающего!

Описание доклада на странице доклада

В README.md внутри папки с докладом стоит придерживаться следующего шаблона:

# FULL_TALK_NAME

_SPEAKER_NAME, SPEAKER_POSITION_

FULL_TALK_DESCRIPTION

**[Слайды в PDF](SHORT_TALK_NAME.pdf)**

**[Посмотреть на Ютубе](YOUTUBE_LINK)**

Здесь:

  • SPEAKER_POSITION — должность выступающего в компании.

  • FULL_TALK_DESCRIPTION — полное описание доклада.

  • YOUTUBE_LINK — ссылка на запись на Ютубе, если таковая имеется.

  • Все остальные переменные такие же, как и описанные ранее.

Полное описание доклада

Обычно оно состоит из двух абзацев. В первом поясняется о чём идёт речь, а во втором — кому доклад будет полезен.

Первый абзац удобнее всего начинать с имени автора и глагола в настоящем времени:

Андрей рассказывает о...

Виктор исследует проблему того, что...

Сергей поясняет, как...

Второй обычно короткий и перечисляет «типы» заинтересованных лиц:

Доклад будет полезен начинающим разработчикам и тестировщикам.

Выступление будет полезно аналитикам и проектным менеджерам.

Ссылка на запись

По-хорошему у каждого выступления должна быть запись в виде отдельного видео. Но иногда бывает так, что записи или вовсе нет (и тогда ссылка просто не добавляется), или же она есть, но в ней сразу все доклады. В таком случае ссылка должна быть с таймкодом, чтобы пользователю было удобнее. Нажал — и смотришь.

Дополнительные материалы

Иногда в докладах бывают ещё какие-то сопутствующие материалы. Например, документ с чеклистом. В таком случае нужно этот документ положить в папку с докладом, а ссылку на него оформить аналогично ссылке на слайды и Ютуб (пример).

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

Частые вопросы

Почему слайды в PDF?

Практика показывает, что PDF-файлы весят куда меньше, чем PPT, Keynote и пр.

Плюс, PDF доступен всем, и посмотреть его можно прямо на Гитхабе. В то время как иные форматы зависят от ОС, наличия ПО у пользователя и пр.

Можно было бы добавлять сразу несколько версий слайдов, но не понятно, зачем. Ведь есть PDF!

Я закоммитил, и только после этого вспомнил про Git LFS. Что делать?

В такой ситуации всё равно надо сперва установить Git LFS, как описано в разделе Git LFS. А затем в ветке с коммитами запустить:

git lfs migrate import --include="*.pdf"

Команда найдёт все PDF-файлы в текущей ветке и загрузит их в LFS. Если на сервер до этого пушились данные, то нужно будет перепушить с форсом:

git push --force

В случае возникновения иных проблем с Git LFS, см. Git LFS Tutorial.