Эта страница была обновлена January 2017.

Для начала прочтите руководство нового разработчика.

Базовые принципы и стиль форматирования кода

Большинство из ниже следующего должно быть хорошо известно каждому кто участвует в разработке open source или в коммерческой среде разработки. Ниже следующее применимо к большей части основной разработки ветки i2p.i2p. Руководства для других веток, дополнений и внешних приложений может существенно отличаться; для уточнения свяжитесь с соответствующим разработчиком.

Общество

  • Пожалуйста, не нужно просто "писать код". Если вы можете, участвуйте в других мероприятиях, включая: обсуждения разработки и поддержке в IRC, zzz.i2p и на форуме forum.i2p; в тестировании; сообщениях об ошибках и ответах на них; документировании; просматривании кода, и т.д.
  • Активные разработчики должны периодически быть доступны по IRC #i2p-dev. Будьте в курсе текущего цикла выпуска. Придерживайтесь релизных вех, таких как freeze, tag freeze и checkin deadline для релиза.

Релизный цикл

Наш нормальный релизный цикл 6-10 недель. Ниже приведены примерные сроки в пределах типичного 8-недельного цикла . Фактические сроки для каждого релиза устанавливаются ведущим разработчиком.

  • 1-2 дня после предыдущего релиза: Чекины в trunk разрешены.
  • 2-3 недели после предыдущего релиза: Deadline на перенос основных изменений из других веток в trunk.
  • 4-5 недель до релиза: Deadline для запросов новых ссылок домашних страниц.
  • 3-4 недели до релиза: Заморозка возможностей. Deadline для основных новых возможностей.
  • 2-3 недели до релиза: Проводите встречу для просмотра новых запросов ссылок домашних страниц, если есть.
  • 7-10 дней до релиза: Заморозка строк. Больше никаких изменений в переведенных ("tagged") строках. Выгружайте строки на Transifex, объявляйте deadline перевода на Transifex.
  • 7-10 дней до релиза: deadline возможностей. После этого только исправления ошибок. Больше никакого добавления возможностей, рефакторинга или чистки.
  • 3-4 дня до релиза: deadline перевода. Загружайте переводы с Transifex и чекиньте.
  • 2-3 дня до релиза: deadline чекина. Никаких чекинов после без разрешения сборщика релизов.
  • Часы до релиза: deadline просматривания кода

Monotone

  • Получите основные понятия о распределенной системе контроля версий, даже если раньше вы не использовали monotone. Если нужно - попросите помощи. Единожды чекин да пребудет вовеки, никакого отката нет. Пожалуйста, будьте аккуратны. Если раньше вы не использовали monotone - начните с маленьких шагов. Зачекиньте небольшое изменение и посмотрите как пойдет дело.
  • Тестируйте свои изменения до того как зачекинить их. Если вы предпочитаете модель программирования чекин-перед-тестированием, то используйте свою ветку разработки (например i2p.i2p.yourname.test) и переносите изменения в i2p.i2p когда они заработают как надо. Не ломайте сборку. Не провоцируйте регрессию. А если сделали (это случается), пожалуйста, не исчезайте на долго после того как внесли изменения.
  • Если ваши изменения нетривиальны, или вы хотите чтобы люди их протестировали, и вам нужны хорошие отчеты о тестировании, дабы знать протестированы ваши изменения или нет - добавьте чекин-комментарий в history.txt и увеличьте версию сборки в RouterVersion.java.
  • Убедитесь, что у вас есть свежий файл monotonerc в _MTN. Не чекиньте в ненадежные ревизии.
  • Ensure that you 'mtn pull' and 'mtn update' to the latest revision before you check in and push. If you inadvertently diverge, merge and push as soon as possible. Don't routinely make others merge for you. Yes, we know that monotone says you should push and then merge, but in our experience, in-workspace merge works just as well as in-database merge, without creating a merge revision.
  • Не чекиньте важные изменения в главную ветку i2p.i2p на поздних стадиях цикла релиза. Если проект занимает у вас больше нескольких дней, создайте свою ветку в monotone и разрабатывайте в ней, т.о. вы не заблокируете релиз.

Стиль форматирования кода

  • В большинстве кода для отступа используется 4 пробела. Не используйте символ табуляции. Не переформатируйте код. Если ваш IDE или редактор хочет отформатировать все, возьмите его под контроль. Да, мы знаем, что 4 пробела это та еще головная боль, но, возможно, вы сможете правильно настроить свой редактор. В некоторых местах стиль форматирования может разниться. Руководствуйтесь здравым смыслом. Воспроизводите имеющийся стиль в файле, который вы изменяете.
  • Все новые классы и методы с модификатором public и package-private требуют Javadocs. Добавьте @since номер_релиза. Javadocs очень желетелен для новых методов с модификатором private.
  • For any Javadocs added, there must not be any doclint errors or warnings. Run 'ant javadoc' with Oracle Java 8 or higher to check. All params must have @param lines, all non-void methods must have @return lines, all exceptions declared thrown must have @throws lines, and no HTML errors.
  • Классы в core/ (i2p.jar) и куски i2ptunnel - это части нашего официального API. Есть несколько out-of-tree плагинов и других приложений, которые основаны на этом API. Будьте осторожны при их изменении, чтобы не поломать совместимость. Добавляйте методы в API, только если они полезны для всех. Javadocs для методов API должны быть просты и полны. Если вы вносите изменения в API, обновите также документацию на веб-сайте (i2p.www branch).
  • Делайте заметки к строкам для переводов где следует. Изменяйте существующие отмеченные строки, только если это действительно необходимо, т.к. это нарушает существующий перевод. Не добавляйте и не изменяйте отмеченные строки после "tag freeze" в цикле релиза, тогда у переводчиков будет шанс обновиться до релиза.
  • По возможности используйте дженерики и конкурентные классы. I2P - это сильно мульти-потоковое приложение.
  • Ознакомьтесь с распространненными "подводными камнями" в Java, которые найдены findbugs. Выполните 'ant findbugs', чтобы узнать больше.
  • Мы требуем, чтобы Java 7 собирал выполнял I2P. Не используйте нигде Java 8 классы или методы . Не используйте Java 7 или 8 классы или методы во встроенных подсистемах (ядро, маршрутизатор, mstreaming, потоковая передача, i2ptunnel), поскольку Android и встраиваемые приложения требуют только Java 6. Все классы должны быть доступными в Android API 9. Функции Java 7 языка приемлемы в этих подсистемах, если они поддерживаются текущей версией из SDK Android и компилируются в Java совместимый с 6 код.
  • Выполняйте явное преобразование примитивных классов и типов; не полагайтесь на autoboxing/unboxing.
  • Не используйте URL. Используйте URI.
  • Не ловите Exception. Поймайте RuntimeException и проверьте исключения индивидуально.
  • Don't use String.getBytes() without a UTF-8 charset argument. You may also use DataHelper.getUTF8() or DataHelper.getASCII().
  • Always specify a UTF-8 charset when reading or writing files. The DataHelper utilities may be helpful.
  • Always specify a locale (for example Locale.US) when using String.toLowerCase() or String.toUpperCase(). Do not use String.equalsIgnoreCase(), as a locale cannot be specified.
  • Не используйте String.split(). Используйте DataHelper.split().
  • Ensure that InputStreams and OutputStreams are closed in finally blocks.
  • Use {} for all for and while blocks, even if only one line. If you use {} for either the if, else, or if-else block, use it for all blocks. Put "} else {" on a single line.
  • Specify fields as final wherever possible.
  • Don't store I2PAppContext, RouterContext, Log, or any other references to router or context items in static fields.
  • Don't start threads in constructors. Use I2PAppThread instead of Thread.

Лицензии

  • Чекиньте только тот код, который вы написали сами. Перед тем как зачекинить любой код или библиотеку jar из других источников, объясните почему это необходимо, убедитесь что лицензия совместима, и получите подтверждение от главного разработчика.
  • If you do obtain approval to add external code or jars, and binaries are available in any Debian or Ubuntu package, you must implement build and packaging options to use the external package instead. Checklist of files to modify: build.properties, build.xml, debian/control, debian/i2p-router.install, debian/i2p-router.links, debian/rules, sub-build.xml
  • Для любых image зачекиненых из внешних источников, вашей ответственностью является проверка совместимости лицензии. Включите лицензию и информацию об источнике в комментарий к чекину.

Ошибки

  • Управление потоком тикетов это общая работа, пожалуйста, помогайте. Просматривайте trac.i2p2.de на предмет тикетов, к которым вы прикреплены, или по которым вы можете помочь. Назначайте, категоризируйте, комментируйте, испарвляйте или закрывайте тикеты, если можете.
  • Новые разработчики должны начать работу с исправления ошибок. Поищите ошибки с ключевым словом 'easy' на trac. Когда Вы исправите ошибку, присоедините Ваш патч к тикету и добавьте ключевое слово 'review-needed'. Не закрывайте тикет, пока он не был рассмотрен и подтвержден другими разработчиками, и Вы проверили еще раз внесенные вами изменения. Как только Вы сделали это без проблем для нескольких тикетов, Вы можете следовать обычной процедуре в дальнейшем.
  • Закройте тикет, если считаете, что исправили его. У нас нет отдела тестирования для верификации и закрытия тикетов. Если вы не уверены, что исправили, закрывайте и добавляйте запись с текстом "Я думаю, я это исправил, пожалуйста, протестируйте и откройте заново если ошибка все еще воспроизводится". Добавляйте комментарий с номером сборки или ревизией, и устанавливайте веху в следующем релизе.