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

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

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

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

Общество

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

Release Cycle

Our normal release cycle is 6-10 weeks. Following are the approximate deadlines within a typical 8-week cycle. Actual deadlines for each release are set by the lead developer.

  • 1-2 days after previous release: Checkins to trunk are allowed.
  • 2-3 weeks after previous release: Deadline to propagate major changes from other branches to trunk.
  • 4-5 weeks before release: Deadline to request new home page links.
  • 3-4 weeks before release: Feature freeze. Deadline for major new features.
  • 2-3 weeks before release: Hold project meeting to review new home page link requests, if any.
  • 7-10 days before release: String freeze. No more changes to translated ("tagged") strings. Push strings to Transifex, announce translation deadline on Transifex.
  • 7-10 days before release: Feature deadline. Bug fixes only after this time. No more features, refactoring or cleanup.
  • 3-4 days before release: Translation deadline. Pull translations from Transifex and check in.
  • 2-3 days before release: Checkin deadline. No checkins after this time without the permission of the release builder.
  • Hours before release: Code review 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 пробела это та еще головная боль, но, возможно, вы сможете правильно настроить свой редактор. В некоторых местах стиль форматирования может разниться. Руководствуйтесь здравым смыслом. Воспроизводите имеющийся стиль в файле, который вы изменяете.
  • All new public and package-private classes and methods require Javadocs. Add @since release-number. Javadocs for new private methods are desirable.
  • 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 - это сильно мульти-потоковое приложение.
  • Be familiar with common Java pitfalls that are caught by findbugs. Run 'ant findbugs' to learn more.
  • We require Java 7 to build and run I2P. Do not use Java 8 classes or methods anywhere. Do not use Java 7 or 8 classes or methods in embedded subsystems (core, router, mstreaming, streaming, i2ptunnel), as Android and embedded applications require only Java 6. All classes must be available in Android API 9. Java 7 language features are acceptable in these subsystems if supported by the current version of the Android SDK and they compile to Java 6-compatible code.
  • Выполняйте явное преобразование примитивных классов и типов; не полагайтесь на autoboxing/unboxing.
  • Don't use URL. Use URI.
  • Don't catch Exception. Catch RuntimeException and checked exceptions individually.
  • 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.
  • Don't use String.split(). Use 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 на предмет тикетов, к которым вы прикреплены, или по которым вы можете помочь. Назначайте, категоризируйте, комментируйте, испарвляйте или закрывайте тикеты, если можете.
  • New developers should start by fixing a bug. Search for bugs with the 'easy' keyword on trac. When you have a fix, attach your patch to the ticket and add the keyword 'review-needed'. Do not close the ticket until it's been successfully reviewed and you've checked your changes in. Once you've done this smoothly for a couple of tickets, you may follow the normal procedure below.
  • Закройте тикет, если считаете, что исправили его. У нас нет отдела тестирования для верификации и закрытия тикетов. Если вы не уверены, что исправили, закрывайте и добавляйте запись с текстом "Я думаю, я это исправил, пожалуйста, протестируйте и откройте заново если ошибка все еще воспроизводится". Добавляйте комментарий с номером сборки или ревизией, и устанавливайте веху в следующем релизе.