Добавить пункт "Обращение за помощью"

Сюда я и предлагаю поместить этот шаблон и описать это:

При обращении за помощью нужно:

1. Сделать коммит с текущим состоянием кода, где воспроизводится проблема
2. Открыть draft pull request, если еще не открыт
3. Обратиться за помощью заполнив этот шаблон

Форматирование и тп разумеется не принципиальны абсолютно, главное эту инфу донести

Какого рода задача?

Дополнить документацию

Что и где будем менять?

https://github.com/atls/convention/wiki/Отладка-кода

Укажите референс

No response

Материалы

• https://gist.github.com/TFK70/ba62e4fda2d7bdea67d8deb664864d92
• https://github.com/atls/convention/wiki/%D0%9E%D1%81%D0%BD%D0%BE%D0%B2%D0%BD%D1%8B%D0%B5-%D0%BF%D1%80%D0%B8%D0%BD%D1%86%D0%B8%D0%BF%D1%8B
• https://gist.github.com/TFK70/51c0f46a916a3ce71976774b51c66e1d

https://github.com/atls/convention/blob/master/docs/Standards%20of%20%D0%A1ommunication%20and%20Interaction%20in%20the%20Team.md

Нормы общения и взаимодействия в команде

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

Нормы эти простые и встречаются почти везде в повседневной жизни. Скорее всего они прозвучат как «прописные истины», но важно их помнить и важно эти нормы соблюдать.

Как вести обсуждение в Issue, Чатах, Войсчатах

Что бы обсуждение было наиболее эффективным, следует соблюдать несколько простых правил и рекомендаций.

Используй цитирование

В Github не предусмотрена система тредов внутри Issue из-за этого в обсуждениях может происходить путаница.

Что бы не запутаться мы используем инструмент цитирования — ">".

Это позволяет сохранять нить обсуждения и «не распыляться» в обсуждении.

Пиши грамотно

Никто из нас не претендует на звания великих грамотеев и знатоков русского языка и никто не ждёт от тебя такого же. Но соблюдение базовых правил грамотного письма, просто облегчает чтение сообщения.

Если сделал ошибку в своём сообщении и позже её заметил, поправь. В GitHub есть редактирование.

Старайся четко формулировать вопросы и мысли

Важнейшее правило. От этого будет зависеть качество ответа на твой вопрос или качество обсуждения твоей идеи или предложения.

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

Вот некоторые рекомендации по теме:

• Writing the perfect question
• How do I ask a good question? - Stack Overflow
• Книга «Новые правила деловой переписки», Сарычева Людмила
• Книга «Ясно, понятно», Максим Ильяхов

Используй Markdown

В дополнении к предыдущему пункту, советуем освоить Markdown. Он позволит твоей мысли быть четкой, ясной и понятной. Такой текст легче воспринимать, а взаимодействовать с тобой приятней и проще.

Сдерживай себя

Если хочется едко (или как говорят — токсично) пошутить в чей-либо адрес. Либо сделать едкое замечание. Процесс совместной работы тоже труд. А как известно труд нужно уважать. Поэтому едкости и токсичности здесь не место.

Если очень хочется пошутить — это можно сделать в чате или в личном разговоре, GitHub - для дел и работы.

Другие важные рекомендации

Асинхронность в работе

Простой пример из рабочих будней:

• У тебя есть задача: [feature] Bankcard Template — примерное время решения 4-6 часов
• Рядом другая задача: [question] Deploy to GKE — примерное время на поиск ответа до 2 часов

Ответить на вопрос быстрее и он позволит запустить в работу ещё одну задачу и займёт это на порядок меньше времени чем разработка шаблона для банковских карт.

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

Если в твоём плане на день висит несколько задач, постарайся распланировать работу над ними так, чтобы они не блокировали другие задачи и процессы. В противном случае задачи будут копиться, конфликтовать, дублироваться превращая процесс работы в хаос, тем самым нервируя тебя и других участников команды.

Если испытываешь сложности, зови на помощь

Очень часто, попросить помощи в какой-то части работы намного проще, а самое главное быстрее, чем пытаться решить её самостоятельно. Многие новички так делают и это плохо. Намного эффективней попросить помощи и решить проблему быстрее. Ты сэкономишь своё время и как ни странно чужое. Profit!

Не бойся задавать вопросы

Особенно если ты новичок. Или не новичок. Лучше задать вопрос, даже если он кажется глупым (как правило это не так), чем не задать. Один не заданный во время вопрос, может обернуться комом проблем в будущем. Как правило это впустую потраченное время из-за банального недопонимания проблемы или задачи.

Поэтому лучше спросить, а если не уверен переспросить.

Если выполняешь задачу совместно с коллегой

Кооперируйтесь, созванивайтесь, обсуждайте проблемы и задачи. Но самое главное — документируйте итоги своих взаимодействий. Иначе говоря, если вы созвонились и договорились о чём-то, зафиксируйте итог созвона в issue.

Как правило хватает одного списка, описанного тезисно.

Все обсуждения по работе ведутся строго в рабочих инструментах

Github, Discord, Рабочие каналы Telegram. Лучше всего, когда бо́льшая часть информации оседает в Issue.

Отписывайся в дейлик после его создания

Дейлик, он же Daily Standup Meeting — это настроенный репозиторий, в котором каждый день утром создаётся issue. А вечером этот issue закрывается.

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

Дейлик нужен для всеобщего понимания того, кто чем занят сегодня и над какой задачей трудится. А также над отслеживанием сложностей у коллег.

Шаблон того, как надо писать в теле issue дейлика.

Находи время развиваться

Работа разработчика, инженера, дизайнера, менеджера и любого другого человека в IT сфере, не может обходиться без постоянного самообучения. Иначе есть риск «остаться в прошлом». Поэтому находи время развиваться.

Читай тематические каналы и ресурсы. Конечно же у тебя должен быть аккаунт на Хабре :)

Находи время на перерывы

Удалённая работа — это сидение перед экраном часами. Это не очень хорошо для здоровья. Поэтому находи время на перерывы.

https://www.figma.com/file/ONE1UToyz4dHP6nKXLuRaW/Atlantis-Onboarding?node-id=0%3A1

Насчет секции "Локализация проблемы"

Тут скорее к @TorinAsakura

Предлагаю эту секцию либо убрать, либо переписать, чтобы протокол подходил под гораздо большее кол-во кейсов

На данный момент протокол работает только на кейсах, когда ошибка непосредственно в проектном файле. Все что идет извне протокол уже не покрывает, скорее наоборот вводит в заблуждение.

Originally posted by @TFK70 in #25 (comment)

https://github.com/atls-academy/template

Речь о об этой репе: https://github.com/atls-academy/template

Что в итоге надо сделать.

Документы

Вне репозитория

• #19

Wiki

Страницы для Convention Repo.

Общее

• #25
• #34
• #27
• #36

Для Новичков

Для Опытных

• #31
• #29

Issue Templates

• #35

Onboarding Issues

• #23
• #21

Дела

• #39
• #40
• #41
• #38
• #24
• #26 ака Как писать обращение (Просьба о помощи)
• #18

Здесь ссылка на документ.

Насчет шаблонов

Сюда точно нужно добавить md шаблон который люди должны использовать при обращении за помощью. Если этого не делать - первым вопросом человека будет что-то типа: Ну вот у меня кароч в какой-то консоли вот это вывело <какой-то непонятный лог> хз че это я потыкал чет не понял помогите даже если сообщение было опубликовано на гитхабе, в телеге о помощи просят еще хуже

В конечном итоге обращения должны выглядеть примерно так. По идее за пример можно взять любое сообщение из треда или одной из других последних задач в репе Кирилла

Я уже пытался подготовить на этой почве шаблон обращения за помощью, получилось что-то такое (во многом дублирует этот шаблон)

В целом можно использовать и его, если он на твой и @TorinAsakura взгляд валиден, но главное упомянуть, что ни один из пунктов не должен быть проигнорирован, человек должен хотя бы прокомментировать отсутствие того или иного пункта

Originally posted by @TFK70 in #25 (comment)

https://github.com/atls/convention/blob/master/docs/Debugging.md

https://github.com/atls/convention/blob/master/docs/Standards%20of%20%D0%A1ommunication%20and%20Interaction%20in%20the%20Team.md

Правила работы с GitHub

Для более эффективной работы, мы в своей команде используем Github. Для нас GitHub это место где находится вся необходимая информация для работы и место где находится истина — код.

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

В этом кратком руководстве, мы собрали собственные командные практики работы с GitHub. Также здесь есть ссылки на официальные руководства GitHub для расширения кругозора.

Работа с Issues

Issues — это место где мы обсуждаем всю важную работу, от начала (создание issue) и до конца (закрытие issue).

Важно чтобы обсуждение по той или иной задаче/проблеме проходило внутри Issue. Это позволяет отследить историю в случае возникновения такой проблемы, а также даёт возможность просто делиться ссылкой на Issue или конкретный комментарий внутри Issue.

Об Issues на GitHub Docs

Issue Labels

Сам по себе Issue не несёт никакого «смыслового окраса». Для этого, мы применяем лейблы.

Например:

• Issue с лейблом documents — это задача или проблема, которая относится к документации
• Issue с лейблом feature — означает что там лежит какая-то информация о фиче
• Issue с лейблом bug, ну ты понял

Поэтому очень желательно, чтобы Issues не оставались без лейблов. Список доступных лейблов доступен с правой стороны Issue, заголовок Labels:

Управление Лейблами на GitHub Docs

Отдельно про Markdown

Markdown — это облегчённый язык разметки. Эта разметка позволяет сделать текст жирным или наклонным (италик).

Делать удобные для отображения списки:

• Раз
• Два
• Три

А также цитировать своих собеседников:

Привет! Всё готово к релизу, погнали?

Чел, сегодня пятница, какой релиз :|

Весь этот набор разметки, позволяет сделать самое главное: писать красивые и чётко сформулированные мысли в текстовом виде.

Это очень важно для командной работы. Потому что текст в Issues потеряется в самую последнюю очередь. А хорошо сформулированная мысль, позволит быстро донести суть до своих собеседников.

Поэтому важно ознакомиться с Основным синтаксисом письма и форматирования Markdown на GitHub Docs. Там же есть секция с продвинутыми практиками.

Работа с Branches

Стоит ли всё-таки оставлять эту секцию или нет? Мне непонятно.

Работа с Pull Request

Pull Requests позволяют вам сообщить другим об изменениях, которые вы внесли в ветку в репозитории на GitHub. После открытия Pull Request'а вы можете обсудить и просмотреть потенциальные изменения с коллегами и добавить последующие коммиты до того, как ваши изменения будут объединены в базовую ветку.

Из документации к Pull Request'ам на GitHub Docs

Как создавать?

Создание Pull Request'а на Github Docs

Когда создавать?

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

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

В будущем такой подход также помогает при навигации по истории коммитов.

Кого ставить в assignee?

Указываем себя, как автора. Это позволит потом по PR делать фильтрацию и получает предсказуемые результаты.

Кого указывать в ревьюверах?

Лида (ментора) или если таковой отсутствует - @TorinAsakura

Что за статусы проверок?

У проектов могут быть настроены проверки проектов, которые выполняются при создании и обновлении Pull Request'а. В них можно получить всю необходимую информацию о выполнении тестов.

Можно ли форсить ветку? (Нужна ли эта секция? Не слишком всё усложняет на данном этапе?)

Можно, но только если от этого больше пользы, чем вреда. Когда можно:

1. Когда ревью еще не провели.
2. Когда в ветку еще ничего не вливали (обновленный dev)
3. Когда PR на этой ветке еще нет.

Когда нельзя:

1. Когда ревью провели. Комментарии привязываются к хешу коммитов. Если форснуть, то это уже новые коммиты, даже если в них ничего не менялось. Из-за этого весь прогресс ревью тупо слетает. В итоге ревьюверу нужно потратить время, чтобы определиться, где он оставлял ревью, а где нет.
2. Когда форсом можно ненароком ввести в заблуждение. После форса достаточно муторно посмотреть, что же в итоге изменилось. Можно, конечно, выдрать хеши и пойти в diff, чтобы посмотреть, что изменилось.

Лучше пусть будут лишние коммиты (коммиты лишними не бывают), так процесс выглядит более прозрачным и последовательным.

Conventional Commits или Соглашение о коммитах

«Соглашение о коммитах» — простое соглашение о том, как нужно писать сообщения коммитов. Оно описывает простой набор правил для создания понятной истории коммитов, а также позволяет проще разрабатывать инструменты автоматизации, основанные на истории коммитов.

Цитата из официального документа соглашения

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

Важно! Никакой кириллицы ни в коде, ни в комментариях к коммитам, ни в названиях бранчей быть не должно

Post Scriptum

Эффективная работа в GitHub для нас очень важна. Здесь протекает вся рабочая «жизнь» проектов над которыми мы работаем. Поэтому для нас важно, чтобы каждый соблюдал базовые правила работы с этим инструментом.

Вообще, у GitHub довольно обширная и полезная документация, с которой рекомендуется ознакомиться.

Если незнаком или мало опыта с Git, то вот полезный тур на русском языке по нему. Чёрт побери, Git!?! быстрая и понятная подсказка по Git'у. Или Интерактивная визуализация и учебник по Git.

@taqyon еще такой запрос: когда люди прикладывают логи они должны форматировать их должным образом:

Реф как не надо делать

Скриншот на случай если коммент отредачится:

Как надо

• Лог нужно помещать в тег <details></details>, так намного проще ознакамливаться с содержимым
• Сам лог нужно форматировать. Можно помещать в тег ```log<лог>`. Одинарные бэктики лучше не использовать т.к. содержимое лога может испортить форматирование

Пример как нужно прикладывать лог

Лог при попытке запустить проект:

src/index.ts:1:21 - error TS2307: Cannot find module 'fastify' or its corresponding type declarations.

1 import Fastify from 'fastify';
~~~~~~~~~
Found 1 error.

Пример думаю можно прямо в документ положить

Ну и, разумеется, оформи как считаешь нужным, если что могу доп. пояснения дать почему это так необходимо

Что такое Конвенция

Конвенция — это набор, документов, практик, рекомендаций и правил. С конвенцией знаком каждый член команды Atlantis. И каждый член команды соблюдает Конвенцию. Основные документы Конвенции это Нормы общения и взаимодействия в команде и Правила работы с GitHub.

В Wiki репозитория есть полезная информация для опытных кандидатов и для новичков.

О чем этот репозиторий

Этот репозиторий о Конвенции и работе над изменениями Конвенции. В Wiki содержится полезная информация для кандидатов. В папке /docs/ находятся документы для Конвенции и Wiki.

Я хочу внести изменения в документы

Используйте стандартный рабочий флоу: делайте PR для внесения изменений, создайте Issue для обсуждения.

https://github.com/atls/convention/blob/master/docs/How%20to%20ask%20for%20help%20to%20be%20understood%20and%20helped.md

Почему нельзя загружать изображения кода / ошибок, когда задаешь вопрос?

Ты не должен размещать в виде изображения:

• код
• сообщения об ошибках
• исключениях
• файлы журналов
• файлы конфигурации
• файлы проекта
• или что-либо еще, представленное в текстовой форме

Потому что

• Код или примеры данных на изображениях нельзя скопировать и вставить в редактор и скомпилировать, чтобы воспроизвести проблему
• Изображения имеют большой размер и трудночитаемые на мобильных устройствах
• Изображения не могут быть использованы для поиска
• Изображения труднее читать, чем текст
• Постить изображения твоего кода сложнее, чем копировать/вставлять сам код и форматировать его
• Ты просишь помощи с проблемой и должен максимально облегчить задачу помощи
• URL-адреса размещенных изображений часто являются недоступными
• Изображения показывают ограниченное количество строк кода. Для умеренно сложных вопросов невозможно уместить весь необходимый код на одном экране, даже если ты создал самый минимально возможный пример для воспроизведения рассматриваемого вопроса
• Помощник не сможет понять, вызвана ли ошибка в вашем коде, скажем, невидимыми символами или неправильным использованием символов Unicode, которые выглядят одинаково
• Некоторые люди используют темную тему для просмотра сайта. Белый фон изображения может повредить их глазам при просмотре сайта в позднее время. Кроме того, изображение с прозрачным фоном может быть отлично видно в светлой теме, но едва различимо в темной

Нужно еще? :-)

Изображения следует использовать только для иллюстрации проблем, которые не могут быть понятны другим способом, например, для предоставления скриншотов пользовательского интерфейса.

Это переработанная инфа с Stackoverflow

Originally posted by @taqyon in #25 (comment)

Нужно поднять Github pages для .md файла. Содержимое .md файла ниже.

# Требования по окружению

Привет!

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

Как только выполнишь все пункты и твоё окружение будет готово к работе, сообщи своему ментору.

## 1. [email protected]

### Как лучше поставить?

- Второй, либо основной осью
- Следовать только [официальным гайдам по настройке и установке](https://ubuntu.com/tutorials/install-ubuntu-desktop#1-overview)

### Почему [email protected]?

- Линукс в целом необходим для полной совместимости с нашим рабочим окружением. Например, [tools](https://github.com/atls/tools) являющиеся частью нашей инфраструктуры довольно нестабильно работает под виндой
- 20.04 версия предпочтительнее из-за стабильности
- Все члены команды так или иначе работали/работают на Ubuntu. Это значит, что при столкновении с проблемой тебе смогут оперативно оказать помощь

## 2. IDE

Для работы с кодом обязательно потребуется [IDE](https://ru.wikipedia.org/wiki/%D0%98%D0%BD%D1%82%D0%B5%D0%B3%D1%80%D0%B8%D1%80%D0%BE%D0%B2%D0%B0%D0%BD%D0%BD%D0%B0%D1%8F_%D1%81%D1%80%D0%B5%D0%B4%D0%B0_%D1%80%D0%B0%D0%B7%D1%80%D0%B0%D0%B1%D0%BE%D1%82%D0%BA%D0%B8) **WebStorm**.

### Почему WebStorm?

По той же причине, почему Ubuntu - все члены команды используют IDE от JetBrains, поэтому тебе помогут в ней освоиться и настроить под себя.

## 3. node@16+

[Что такое NodeJS](https://habr.com/ru/post/420123/) — там же есть ссылка на очень крутое видео про EventLoop, настоятельно рекомендуется ознакомиться.

**Что за `@16+`?** — это версия ноды.

### Как ставить?

**Через aptitude:**

`apt install nodejs=16`

## 4. yarn

### Что такое yarn?

Yarn — это альтернативный npm-клиент для работы в качестве пакетного менеджера JavaScript, совместно созданный Facebook, Google, Exponent и Tilde. Этот менеджер пакетов ускоряет сборку пакетов и делает её более безопасной.

NPM в файле package.json фиксирует не конкретную версию используемых пакетов, а их диапазон. Таким образом, стратегия стандартного клиента npm может привести к тому, что на основе идентичных файлов package.json в разное время будут установлены различные версии пакетов. Yarn решает эту проблему, так как позволяет точно зафиксировать зависимости в файле yarn.lock

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

По сути, Yarn — отличная замена npm. В своей работе мы используем именно его.

### Как ставить

**Тоже через aptitude:**

`apt install --no-install-recommends yarn`

## 5. Email

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

## Настройка Github

- [Настроить 2FA](https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa) для своего Github аккаунта
- Настроить [проверку подписи коммитов (GPG)](https://docs.github.com/en/authentication/managing-commit-signature-verification)
- Авто подпись коммитов (настраивается в git) `git config --global commit.gpgsign true`
- [Настроить подключение к Github](https://docs.github.com/en/authentication/connecting-to-github-with-ssh) через [SSH](https://ru.wikipedia.org/wiki/SSH)