10 вещей, которые каждый делает неправильно при совершении запросов на вытягивание

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

Прежде чем мы продолжим, позвольте мне подчеркнуть, что это не что-то личное. Эта статья не критикует кого-то конкретного, а непристойный тон только для вашего развлечения для чтения. Я не хочу отговаривать вас от участия вообще ни в нашей работе (например, jOOQ , jOOλ, jOOX и т. Д.), Ни в любом другом продукте. Open Source работает также из- за вашего энтузиазма.

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

В конце концов, будь спортом. Возьми эту статью с юмором и скажи себе …

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

10 заповедей запроса на вытягивание

1. Не переформатируй

О, МОЙ БОГ! Пожалуйста! Никогда не нажимайте эту приятную Ctrl-Shift-F (или любых других клавиш, с которыми ваша IDE связывает эту команду doom). Из этого правила есть только два исключения, и это

• В любом случае, когда есть фиксация хуков в автоматическом формате, если кто-то с большой властью и эго настаивает на таких правилах (и миллионах других чрезвычайно полезных правил кода).
• Если в трекере ошибок есть открытая проблема с надписью «Переформатировать все кодеки»

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

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

2. Ты не должен абсолютно исправлять пробелы

В случае, если вы не получили # 1, вот конкретный случай: пробельные символы. Да, я знаю. У этого ужасного проекта OSS есть смеси "\t" и " " , " " , " " разбросанные повсюду. Он страдает от серьезной нерешительности в отношении "\n" , "\r" (чертовы пользователи Mac) и "\r\n" .

Это сильно страдает от:

Это даже имеет вхождения

Ну и что? Проглоти свою гордость наступи на свою гордость. Не исправляй это. Читается ли в вашем запросе «Внедрение сложного алгоритма для расчета значимости разницы между средним и средним расстоянием между звездами в нашей вселенной» или «Исправить чертовое форматирование»?

Ответ в этой интересной статье здесь: http://blog.jooq.org/2014/07/25/top-10-very-very-very-important-topics-to-discuss/

3. Не реорганизуй

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

Но вы не поддерживаете этот код, и ваш запрос извлечения гласит «Исправить опечатку Javadoc». Так что нет. Вы не пытаетесь внедрить свои превосходные дизайнерские навыки в проект, который вы не поддержите, сразу после того, как ваш умный запрос на тягу.

4. Не двигайся

О, это худший из всех. Зачем даже думать об этом? Почему path.to.MyClass должен быть перемещен в other.path.to.MyClass ? Или, что еще хуже, в other.path.to.BetterClassName ? Если вы понимаете это правильно ( и вам достаточно повезло, что вы полагаетесь на обнаружение перемещения файлов из черной магии git ), то это может не иметь большого значения, но что делать , если вы используете SVN или TFS или какую-то другую систему контроля версий, где перемещаются такое явное действие? Вы испортите всю историю, вы создадите diff-файлы (даже с git), которые сложно просмотреть. Ты просто поможешь всему аду вырваться. Так что не двигайся. Оставь это здесь. Это отстой, да, но … Нет!

5. Не переименовывай

И почему вы хотите это сделать? Хорошо, имя переменной было названо thing и грамматически правильно, оно действительно должно называться things , но на самом деле слово thing еще не полностью описывает, что это за вещь на самом деле, поэтому вы переименовываете ее в objects

Добавленная стоимость? Нуль.

Добавлена ​​история контроля версий? Тонны.

Добавлен риск регрессии? Некоторые. (задумывались ли вы о рефлексии, обратной совместимости, сериализации и т. д. и т. д.)

Это называется шумом, и вы не должны этого делать.

6. Ты должен документ

Это абсолютно понятно. Я написал целый пост об этом одном: http://blog.jooq.org/2013/02/26/the-golden-rules-of-code-documentation/

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

• Нет вообще (что, черт возьми)
• Только документация Javadoc / API
• API doc + множество ссылок на проблемы в коде
• Весь код повторяется как проза
• Весь код повторяется как проза в шекспировско-английском языке.

7. Ты не должен реализовывать больше чем одну вещь в одном коммите

Дело не в том, нужно ли вам иметь один или несколько коммитов на задачу. У тебя должен быть только один.

Речь идет о том, должно ли у вас быть несколько задач в одном коммите. Ты не должен.

Представьте себе процесс проверки кода сопровождающего программного обеспечения, в которое вы вносите свой вклад, при наличии следующих альтернатив:

Хороший:

• Исправлена ​​опечатка Javadoc
• Исправлено форматирование (согласовано с сопровождающим. Клянусь, я проверял)
• Добавлены тесты (примечание <- разработка через тестирование! Сначала тесты!)
• Реализован сложный сложный алгоритм
• Реализован новый API
• Исправлена ​​опечатка

Плохой:

• Вот кодекс (затронуто 5 миллионов файлов)

Вы получаете смысл.

8. Сначала спроси продавца / сообщество

Я знаю, что вам действительно нужна эта и эта функция, и вы точно знаете , как ее реализовать, и ооочень готовы внести свой вклад, чувак, это увлекательно.

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

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

9. Не требуй

Если № 8 выше не резонирует с вами, вот еще одна точка зрения. Вы не требуете, чтобы ваша функция была реализована или чтобы ваш запрос был объединен. Существуют миллионы причин, по которым все так или иначе делается в зрелых, популярных проектах OSS. Вы не понимаете их (пока), и вы основали много дизайнерских решений на своем собственном локальном сценарии использования. Этот вариант использования очень интересен и высоко ценится, но его нужно планировать и тщательно интегрировать, а не в первый проект реализации, который пришел в голову.

Поэтому, если ваш запрос на получение ответа отклонен (шансы высоки), не сердитесь. Возможно, вам просто нужно было рассмотреть # 8 в первую очередь.

10. Вы должны принять условия лицензии

Вот вещь Все проекты / продукты с открытым исходным кодом есть Open Source по причине. Многие из них (например, jOOQ ) являются Open Source только потому, что Open Source позволяет поставщику очень легко распространять свое программное обеспечение, получая большую маркетинговую привлекательность для предложения с повышением цен. В мире SaaS и во многих других мирах эта идея называется Freemium (кто-то на самом деле прошел через создание сайта о «freemium»: http://www.freemium.org ). Другие хотят, чтобы программное обеспечение было бесплатным как на свободе . Опять же, другим просто наплевать и использовать любую найденную лицензию ( часто, по иронии судьбы, неправильную ).

Когда вы вносите свой вклад, вам нужно будет принять лицензионное соглашение или соглашение о передаче прав и прав собственности. Некоторые лицензии считают свой CLA неявным ( например, прочитайте эту статью Red Hat о том, почему CLA не нужны при добавлении в лицензионное программное обеспечение Apache ). У других есть более важные причины, по которым им нужен CLA или соглашение о передаче .

Это важно для сопровождающего программного обеспечения, и оно должно быть важно для вас. Если вы заботитесь о свободе, как о свободе (например), вернитесь к # 8 и спросите поставщика / сопровождающего, можете ли вы сохранить авторские права на ваш вклад, став лицензиаром программного обеспечения. Если вы не выполните № 8 и не предоставите свой запрос на получение разрешения до подписания каких-либо соглашений, тогда просто подпишите это, пожалуйста. Я имею в виду, ваша идеология и догма важны, но опять же, не так важны.

Вывод

К настоящему моменту вы либо посмеялись, либо совсем рассержены на меня и эту статью. Это не должно быть воспринято слишком серьезно. Но вот серьезная часть этого. Открытый исходный код есть везде, и это неизбежно. GitHub дал Open Source еще больший импульс. Вклад (технически) очень прост. В этом есть плюсы и минусы.

Чаще всего приветствуются вклады в проекты, размещенные на GitHub. Но не принимайте вклады как должное. Не принимайте оценку за вашу работу как должное. Не принимайте Open Source как должное. GitHub — это только хостинговая платформа (раньше мы использовали хостинг на SourceForge). Это не идеология. Это не значит, что вы можете делать все, что захотите, с тем, что размещено на GitHub.

TL; DR : не просто отправить запрос на получение. Взаимодействуйте с вашим поставщиком и с сообществом поставщика. Это будет намного более полезным опытом для всех.