Halaman ini terakhir diperbarui pada s2022-01.

Pertama-tama, baca panduan pengembang baru.

Dasar Panduan Pengembang dan Gaya Coding

Sebagian besar hal berikut seharusnya panduan umum bagi siapa saja yang telah mengerjakan open source atau dalam lingkungan pemrograman komersial. Berikut ini berlaku terutama untuk cabang pengembangan utama i2p.i2p. Pedoman untuk cabang-cabang lain, plugin, dan aplikasi eksternal mungkin secara substansial berbeda; periksa dengan pengembang yang bersangkutan untuk panduan.

Komunitas

  • Please don't just "write code". If you can, participate in other development activities, including: development discussions and support on IRC, i2pforum.i2p; testing; bug reporting and responses; documentation; code reviews; etc.
  • Pengembang aktif harus bisa dihubungi secara berkala di IRC #i2p-dev. Hati-hati dengan siklus rilis saat ini. Patuhi milestone rilis seperti feature freeze, tag freeze, dan checkin deadline untuk rilis.

Siklus Rilis

The normal release cycle is 6-12 weeks. Following are the approximate deadlines within a typical 8-week cycle. Actual deadlines for each release are set by the release manager after consultation with the full team.

  • 1-2 hari setelah rilis sebelumnya: Checkins ke trunk diperbolehkan.
  • 2-3 minggu setelah rilis sebelumnya: tenggat waktu untuk menyebarkan perubahan besar dari cabang lainnya ke trunk.
  • 4-5 minggu sebelum rilis: tenggat waktu untuk permintaan link ke home page baru.
  • 3-4 minggu sebelum rilis: fitur dibekukan. Batas waktu untuk fitur baru.
  • 2-3 minggu sebelum rilis: mengadakan rapat proyek untuk meninjau permintaan link home page baru, jika ada.
  • 10-14 days before release: String freeze. No more changes to translated ("tagged") strings. Push strings to Transifex, announce translation deadline on Transifex.
  • 10-14 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.
  • 3-4 days before release: Checkin deadline. No checkins after this time without the permission of the release builder.
  • Beberapa jam sebelum rilis: tenggang review kode.

Git

  • Have a basic understanding of distributed source control systems, even if you haven't used git before. Ask for help if you need it. Once pushed, checkins are forever, there is no undo. Please be careful. If you have not used git before, start with baby steps. Check in some small changes and see how it goes.
  • Test your changes before checking them in. If you prefer the checkin-before-test development model, use your own development branch and propagate back to i2p.i2p once it is working well. Do not break the build. Do not cause regressions. In case you do (it happens), please do not vanish for a long period after you push your change.
  • Jika perubahan anda non-trivial, atau anda ingin orang lain mengujinya dan perlu laporan tes yang bagus untuk mengetahui apakah perubahan anda sudah diuji atau tidak, tambahkan komentar checkin ke history.txt dan buat build revision di RouterVersion.java.
  • Ensure that you 'git pull' 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.
  • Do not check in major changes into the main i2p.i2p branch late in the release cycle. If a project will take you more than a couple days, create your own branch in git and do the development there so you do not block releases.

Gaya Pengkodean

  • Gaya Pengkodean sepanjang sebagian besar kode adalah 4-spasi untuk indentasi. Jangan gunakan tab. Jangan memformat-ulang kode Jika IDE atau editor anda ingin memformat ulang semuanya, kendalikan itu. Ya, kami tahu 4 spasi tidak enak dilakukan, tapi mungkin anda dapat mengkonfigurasi editor anda. Di beberapa tempat, gaya pengkodean berbeda. Gunakan akal sehat. Ikuti gaya ini dalam file yang anda memodifikasi.
  • Semua kelas umum dan paket-pribadi yang baru dan metode memerlukan Javadocs. Tambahkan @since nomor rilis. Javadocs untuk metode privaye baru lebih disukai.
  • Untuk setiap Javadocs yang ditambahkan, harus tidak ada kesalahan doclint atau peringatan apapun. Jalankan 'ant javadoc' dengan Oracle Java 8 atau lebih tinggi untuk memeriksa. Semua parameter harus memiliki baris @param, semua metode non-void harus memiliki garis-garis @return, semua exceptions yang dideklarasikan harus memiliki garis-garis @throws, dan tidak ada kesalahan HTML.
  • Class di core / (i2p.jar) dan beberapa bagian dari i2ptunnel merupakan bagian dari API resmi kami. Ada beberapa plugin out-of-tree dan aplikasi lainnya yang mengandalkan API ini. Berhati-hatilah untuk tidak membuat perubahan yang merusak kompatibilitas. Jangan menambahkan metode ke API kecuali mereka memiliki utilitas umum. Javadocs untuk metode API harus jelas dan lengkap. Jika anda menambahkan atau mengubah API, juga memperbarui dokumentasi pada website (cabang i2p.www).
  • Tag strings for translation where appropriate, which is true for all UI strings. Don't change existing tagged strings unless really necessary, as it will break existing translations. Do not add or change tagged strings after the "tag freeze" in the release cycle so that translators have a chance to update before the release.
  • Gunakan generik dan concurrent class di mana mungkin digunakan. I2p adalah sebuah aplikasi yang sangat multi-thread.
  • Kenali common pitfalls Java yang tertangkap oleh findbugs. Jlankan 'ant findbugs' untuk mempelajari lebih lanjut.
  • Java 8 is required to build and run I2P as of release 0.9.47. Do not use Java 7 or 8 classes or methods in embedded subsystems: addressbook, core, i2ptunnel.jar (non-UI), mstreaming, router, routerconsole (news only), streaming. These subsystems are used by Android and embedded applications that require only Java 6. All classes must be available in Android API 14. 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.
  • Try-with-resources cannot be used in embedded subsystems as it requires java.lang.AutoCloseable in the runtime, and this is not available until Android API 19 (KitKat 4.4).
  • The java.nio.file package cannot be used in embedded subsystems as it is not available until Android API 26 (Oreo 8).
  • Other than the above limitations, Java 8 classes, methods, and constructs may be used in the following subsystems only: BOB, desktopgui, i2psnark, i2ptunnel.war (UI), jetty-i2p.jar, jsonrpc, routerconsole (except news), SAM, susidns, susimail, systray.
  • Plugin authors may require any minimum Java version via the plugin.config file.
  • Secara eksplisit mengkonversi antara tipe primitif dan kelas; jangan bergantung pada autoboxing/unboxing.
  • Jangan gunakan URL. Gunakan URI.
  • Tidak menangkap Exceptions. Tangkap RuntimeException dan exception diperiksa secara satu per satu.
  • Jangan gunakan String.getBytes() tanpa argumen charset UTF-8. Anda juga dapat menggunakan DataHelper.getUTF8() atau DataHelper.getASCII().
  • Selalu menentukan charset UTF-8 saat membaca atau menulis file. Utility DataHelper dapat membantu.
  • Selalu tentukan locale (misalnya Locale.US) ketika menggunakan String.toLowerCase() atau String.toUpperCase(). Jangan gunakan String.equalsIgnoreCase(), karena locale tidak bisa dispesifikasikan.
  • Jangan gunakan String.split(). Gunakan DataHelper.split().
  • Don't add code to format dates and times. Use DataHelper.formatDate() and formatTime().
  • Pastikan bahwa InputStreams dan OutputStreams ditutup dalam finally blocks.
  • Gunakan {} untuk semua untuk dan while block, bahkan jika hanya satu baris. Jika anda menggunakan {} untuk blok if, else,atau if-else, gunakannya untuk semua blok. tempatkan "} else {" pada satu baris.
  • tentukan field sebagai final sedapat mungkin.
  • Jangan simpan I2PAppContext, RouterContext, Log, atau referensi lain untuk router atau konteks item di static fields.
  • Jangan mulai threads di dalam constructors. Gunakan I2PAppThread, jangan Thread.

Logging

The following guidelines apply to the router, webapps, and all plugins.
  • For any messages not displayed at the default log level (WARN, INFO, and DEBUG), unless the message is a static string (no concatenation), always use log.shouldWarn(), log.shouldInfo(), or log.shouldDebug() before the log call to avoid unnecessary Object churn.
  • Log messages that may be displayed at the default log level (ERROR, CRIT, and logAlways()) should be brief, clear, and understandable to a non-technical user. This includes exception reason text that may also be displayed. Consider translating if the error is likely to happen (for example, on form submission errors). Otherwise, translation is not necessary, but it may be helpful to search for and reuse a string that is already tagged for translation elsewhere.
  • Log messages not displayed at the default log level (WARN, INFO, and DEBUG) are intended for developer use, and do not have the above requirements. However, WARN messages are available in the Android log tab, and may be of assistance to users debugging issues, so use some care with WARN messages as well.
  • INFO and DEBUG log messages should be used sparingly, especially in hot code paths. While useful during development, consider removing them or commenting them out after testing is complete.
  • Do not log to stdout or stderr (wrapper log).

Lisensi

  • Only check in code that you wrote yourself. Before checking in any code or library jars from other sources, justify why it is necessary, verify the license is compatible, and obtain approval from the release manager.
  • Jika anda memperoleh persetujuan untuk menambahkan kode eksternal atau jar, dan binari tersedia dalam paket Debian atau Ubuntu, anda harus menerapkan opsi build dan packaging dengan menggunakan paket eksternal sebagai gantinya. Daftar Periksa file untuk modifikasi: build.properties, build.xml, debian/control, debian/i2p-router.install, debian/i2p-router.links, debian/rules, sub-build.xml
  • Setiap gambar yang diperiksa dari sumber eksternal, adalah tanggung jawab anda untuk pertama-tama memverifikasi lisensi apakah kompatibel. Termasuk informasi lisensi dan sumber dalam komentar Check-in.

Bug

  • Managing issues are everybody's job, please help. Monitor for issues you can help with. Comment on, fix, and close issues if you can.
  • New developers should start by fixing issues. When you have a fix, attach your patch to the issue and add the keyword 'review-needed'. Do not close the issue 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.
  • Close an issue when you think you've fixed it. We don't have a test department to verify and close tickets. If you arent sure you fixed it, close it and add a note saying "I think I fixed it, please test and reopen if it's still broken". Add a comment with the dev build number or revision and set the milestone to the next release.