Инструкция по вкладу

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

Чтобы узнать способы участия без написания кода, обратитесь к нашим рекомендациям по тому, как можно поддерживать проект Zulip.

Изучение документов

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

Эта страница поможет вам пройти следующие шаги:

1. Начальный этап
2. Поиск задачи для выполнения
3. Получение помощи при работе над первым запросом на слияние
4. Узнайте что делает отличного участника Zulip
5. Подача запроса на слияние
6. Продолжение после первой задачи

Каждый раз, когда вы чувствуете себя запутанным, вернитесь к этой инструкции. Требуемая информация скорее всего находится где-то на этой странице (возможно, в списке часто задаваемых вопросов), либо в одном из многих указателей, на которые она ссылается.

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

Начальный этап

Изучение использования Git (Zulip-способ)

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

Если вы уже знакомы с Git, вам всё равно стоит взглянуть на наши специфичные для Zulip инструменты Git.

Настройка среды разработки и погружение в работу

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

Сервер и веб-приложение

1. Установите среду разработки.
2. Ознакомьтесь с использованием среды разработки.
3. Пройдите через руководство по новому приложению чтобы ознакомиться с организацией кодовой базы Zulip и способами поиска кода внутри неё.

Мобильное приложение на основе Flutter

1. Установите среду разработки, следуя инструкциям в README проекта.
2. Начните просматривать недавние коммиты, чтобы видеть код, который мы пишем. Используйте графический просмотрщик Git, такой как gitk, или git log -p с «тайным» методом чтения его вывода.
3. Выберите часть кода, которая кажется интересной среди этих коммитов. Используйте вашу IDE для перехода к этому коду и связанным с ним частями кода, чтобы прочитать и понять, как он работает и как организован кодовый архив.

Десктопное приложение

Следуйте этому руководству для установки среды разработки для Zulip Desktop.

Приложение для терминалов

Следуйте этому руководству для установки среды разработки для Zulip Terminal.

Поиск задачи для выполнения

Где искать задачу

Теперь вы готовы выбрать свою первую задачу! У Zulip есть несколько репозиториев, которые вы можете проверить, в зависимости от ваших интересов. Одних только открытых задач в основном репозитории сервера и веб-приложения Zulip сотни.

Вы можете просмотреть задачи, помеченные меткой «help wanted», которая используется для обозначения задач, доступных для вклада. Вы сможете взяться за невыполненные задачи, которые вы найдете с помощью фильтра no:assignee в GitHub. Также вы можете взяться за задачи, которые были назначены, но больше не работают над ними.

Некоторые репозитории используют метку «good first issue», чтобы отметить задачи, особенно подходящие для новых участников.

Вот некоторые полезные ссылки для задач, которые стоит рассмотреть:

• Сервер и веб-приложение
• Мобильные приложения: нет метки «help wanted», но см. панель проекта для будущего мобильного приложения на основе Flutter. Ищите задачи до «Launch» милистоуна, которые еще не назначены.
• Десктопное приложение
• Приложение для терминалов
• Python API bindings и боты

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

Мы рекомендуем следующий процесс для выбора задачи для выполнения:

1. Найдите задачу, помеченную меткой «help wanted», которая либо не назначена, либо выглядит заброшенной.
2. Прочитайте описание задачи и удостоверьтесь, что вы её понимаете.
3. Если задача кажется перспективной, проведите исследование продукта (на chat.zulip.org или в среде разработки) до тех пор, пока вы не узнаете, как описываемая часть входит в общую картину. Если после исследования описание кажется запутанным или двусмысленным, задайте вопрос на GitHub, так как это может быть полезно для других.
4. Когда вы найдете задачу, которую хотите выполнить, попробуйте начать работу над ней. Попытайтесь найти ту часть кода, которую вам нужно изменить (git grep — ваш лучший друг!), и получите представление о том, как вы собираетесь решать проблему.
5. Если вы чувствуете себя запутанным, это нормально! Повторите эти шаги с другой задачей. Есть множество задач для выполнения, и исследование, которое вы проводите, поможет вам лучше узнать о проекте.

Задача, назначенная другому человеку, может считаться заброшенной, если:

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

Обратите внимание, что вы не заявляете задачу во время выполнения шагов Yöntem 1-4. Перед тем как заявить задачу, вы должны быть уверены, что сможете эффективно справиться с ней.

Дополнительные советы для основного репозитория сервера и веб-приложения:

• Особенно рекомендуется просматривать недавно открытые задачи, так как среди них больше всего простых для выполнения.
• Посмотрите задачи с меткой «good first issue», так как они особенно доступны для новых участников. Однако вы, возможно, найдете задачи без этой метки, которые тоже будут доступны.
• Все задачи разделены на области, такие как админ, композ, эмодзи, гортоксы, локализация, обучение, поиск и т.д. Посмотрите наш список меток, и кликните на некоторых метках area: для просмотра всех задач, связанных с вашими областями интереса.
• Избегайте задач с меткой «сложная», если вы не понимаете, почему она сложная и не уверены, что сможете правильно и полностью её решить.

Заявление задачи

В основном репозитории сервера/веб-приложения и репозитории Zulip Terminal

Основной репозиторий сервера/веб-приложения Zulip (zulip/zulip) и репозиторий Zulip Terminal (zulip/zulip-terminal) настроены с использованием GitHub-бота по управлению задачами и запросами на слияние, называемого Zulipbot, который управляет задачами и запросами на слияние для создания более удобного рабочего процесса для участников Zulip.

Чтобы заявить задачу в этих репозиториях, просто оставьте комментарий, содержащий @zulipbot claim в потоке задачи. Если задача помечена меткой «help wanted» и не назначена никому другому, Zulipbot немедленно назначит задачу вам.Примечание: новые вкладчики могут заявить только одну задачу до того, как их первое pull-request будет объединено. Это делается для поощрения людей завершить текущую работу перед началом новой. Если вы хотите взяться за новую задачу, пока ждете проверки почти готового pull-request, вы можете оставить комментарий с этим замечанием на странице задачи, которая вас интересует.

В других репозиториях Zulip

Нет бота для других репозиториев Zulip (zulip/zulip-flutter, и т.д.). Если вы заинтересованы в том, чтобы взяться за задачу в одном из этих репозиториев, просто оставьте комментарий на странице задачи, указывая, что вы начали работать над задачей и хотели бы её взять себе. В вашем комментарии опишите ту часть кода, которую вы модифицируете, а также план подхода к решению проблемы, основываясь на информации, полученную в шагах 1–4 выше.

Не обязательно упоминать создателя задачи в своем комментарии. Также нет необходимости отправлять ту же информацию в нескольких местах, например, в канале чата вместе с GitHub задачей.

Пожалуйста, следуйте тем же правилам, что указаны выше: найдите задачу, помеченную меткой "help wanted", и беритесь за одну задачу за раз.

Получение помощи

Вы можете иметь вопросы при работе над своим pull-request. Например, вам может быть непонятно некоторые детали требований или у вас могут возникнуть вопросы относительно вашего подхода к реализации. Поддерживатели Zulip рады ответить на продуманные вопросы и обсудить любые трудности, которые могут возникнуть во время работы над вашим PR.

Если вы еще этого не сделали, сейчас самое время присоединиться к разработческому сообществу Zulip. Если вы хотите, представьтесь в канале #новые_участники, используя свое имя как тему.

Вы можете получить помощь в публичных каналах сообщества:

1. Пересмотрите правила поведения в разработческом сообществе Zulip.1. Определите место для публикации вопроса. Если есть обсуждаемый поток, связанный с задачей, над которой вы работаете, это обычно лучшее место для публикации ваших уточняющих вопросов. В противном случае, следуйте этим правилам, чтобы понять, где лучше всего отправить свой вопрос. Не беспокойтесь слишком сильно о выборе правильного места, если вы не уверены, так как модераторы могут переместить ваш вопрос в другой канал, если это необходимо.

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

3. Пересмотрите своё сообщение перед отправкой. Будет ли ваш вопрос понятен человеку, знакомому с Zulip, но не имеющему свежих знаний о том, над чем вы работаете?

Хорошие вопросы обычно получают ответ в течение 1-2 рабочих дней. Нет необходимости упоминать кого-либо при отправке вопроса, так как поддерживатели внимательно следят за всеми активными обсуждениями.

Что делает отличного вкладчика Zulip?

Когда вы работаете над своей первой вкладкой, вот несколько лучших практик, которые стоит учесть.

• Задайте отличные вопросы. Очень сложно ответить на общие вопросы типа "Как мне выполнить эту задачу?". Когда просите помощи, объясните свою текущую понимание, включая то, что вы уже сделали или попробовали, и где вы застряли. Прикрепите трассировки ошибок или другие сообщения об ошибках, если это необходимо. Для более подробной информации, обратитесь к нашему руководству!
• Учитесь и практикуйтесь в дисциплине коммитов Git.
• Отправляйте тщательно протестированное кодирование. Посмотрите наш детальный гайд по тому, как проводить рецензию кода (вашего или другого человека).
• Опубликуйте скриншоты или GIF для изменений фронтэнда.
• Работайте над тем, чтобы ваши pull-requests были легко проверяемыми.
• Ясно описывайте, что вы реализовали и почему. Например, если ваша реализация отличается от описания задачи или является частичным шагом к требованиям, укажите эти различия.
• Быть отзывчивым к обратной связи на pull-requests. Это значит, что вы должны внедрять или отвечать на все предлагаемые изменения, и оставлять заметку, если вы не сможете исправить это в течение нескольких дней.
• Быть полезным и дружелюбным в разработческом сообществе Zulip.

Отправка pull-request

Увидеть руководство по отправке pull-request для подробных инструкций по тому, как представить свои предложения по изменениям Zulip.

Руководство по процессу рецензирования pull-request объясняет этапы рецензирования вашего PR и предлагает советы по тому, как помочь процессу рецензирования двигаться вперед.

Если ваш первый проект займет некоторое время — это нормально! Вы сможете работать намного быстрее, когда наберетесь опыта.

За рамками первого проекта

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

Часто задаваемые вопросы

• Что делать, если кто-то уже работает над задачей, которую я хочу взять? Есть много задач для выполнения! Если кто-то ещё активно работает над задачей, вы можете найти другую, или помочь с рецензией их работы.
• Что делать, если кто-то другой взял задачу, пока я решаю, работать ли над ней? Не волнуйтесь! Вы можете внести свой вклад, предоставляя обратную связь на их pull-request. Если вы добились значительного прогресса в понимании части кодовой базы, вы также можете найти другую "help wanted" задачу в той же области.
• Что делать, если уже существует pull-request для задачи, над которой я хочу работать? Смотрите наш гайд по продолжению незавершенной работы.
• Что делать, если я спрашиваю, работает ли кто-то над задачей, и они не отвечают? Если вы не получили ответа в течение 2-3 дней, смело оставьте комментарий, что вы работаете над задачей, и отправьте pull-request. Если оригинальный назначенный человек закончил свой pull-request раньше, ничего страшного! Вы можете помочь, предоставив обратную связь на их работу, или отправить свой собственный PR, если считаете, что нужен другой подход (как описано выше).
• Могу ли я работать над старой задачей? Конечно! Открытые задачи, помеченные как "help wanted", обычно доступны для выполнения. Если вы обнаруживаете, что контекст вокруг задачи изменился (например, интерфейс выглядит по-другому), сделайте всё возможное, чтобы применить текущие шаблоны, и отметьте любые различия со спецификациями в описании своего pull-request.Если вы берётесь за исправление ошибки, начните с проверки возможности воспроизведения её. Если она больше не воспроизводится, оставьте комментарий на странице задачи, объясняя, как вы тестировали поведение, и что видели, с приложенными скриншотами, если это необходимо. А если вы можете воспроизвести её, исправление её — отличная идея!

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

• Могу ли я придумать свою идею для новой функции и поработать над ней? Мы приветствуем предложения новых функций или других улучшений, которые вы считаете ценными. Если у вас есть идея для новой функции, которую вы хотите реализовать, начните обсуждение в нашем сообществе разработчиков, объясняя вашу идею и проблему, которую вы планируете решить.
• Я жду следующего этапа проверки моего запроса на вливание (PR). Можно ли взяться за другую задачу в это время? Первый запрос на вливание от нового участника часто требует значительной доработки, поэтому убедитесь, что ваш запрос на вливание готов к проверке готовность вашего запроса на вливание и пройдите хотя бы один круг обратной связи до того, как возьмётесь за вторую задачу. После этого — конечно! Если Zulipbot не позволяет вам заняться другой задачей, вы можете оставить комментарий, описывающий текущее состояние вашей работы над интересующей вас задачей (включая ссылки на все открытые запросы на вливание), и попросить назначить эту задачу вам. Обратите внимание, что исправление отзывов по поводу в процессе выполнения вашего запроса на вливание всегда должно иметь приоритет перед началом нового запроса на вливание.
• Я считаю, что мой запрос на вливание завершён, но он ещё не был влитым. В чём дело?
  1. Убедитесь, что вы учли все отзывы, в том числе любые замечания относительно дисциплины коммитов Git.
  2. Если вы учли все отзывы, оставили ли вы комментарий, объясняющий, что вы сделали это, и просьбу о повторной проверке? Если нет, может быть не очевидно для поддерживаемых проектом лиц или рецензентов, что ваш запрос на вливание готов к повторной проверке.
  3. Может быть пауза между первоначальной проверкой вашего запроса на вливание и окончательной проверкой со стороны поддерживаемого проектом лица. Это нормально, и мы рекомендуем вам работать над другими задачами во время ожидания.
  4. Если вы уверены, что ваш запрос на вливание готов, а обновлений не было несколько недель, полезно будет оставить ещё один комментарий. Подведите итог общего состояния процесса проверки и вашей работы, и укажите, что вы ожидаете проверки.
  5. Наконец, участники проекта Zulip тоже люди! Они могут быть заняты другими делами, и иногда они даже берут отпуск. ;)) Иногда может потребоваться несколько недель для завершения последней стадии проверки запроса на вливание.

Программы поощрения участников

Проект Zulip регулярно участвует в Google Summer of Code (GSoC) и Outreachy. Мы были менторской организацией GSoC с 2016 года, и принимаем 15-20 участников GSoC каждый летний сезон. В прошлом мы также участвовали в Google Code-In и принимали летних стажёров из Гарварда, Массачусетского технологического института и Стэнфордского университета.

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