225 lines
9.2 KiB
HTML
225 lines
9.2 KiB
HTML
{% extends "global/layout.html" %}
|
|
{% block title %}{{ _('Developer Guidelines and Coding Style') }}{% endblock %}
|
|
{% block lastupdated %}{% trans %}January 2016{% endtrans %}{% endblock %}
|
|
{% block content %}
|
|
<p>{% trans newdevs=site_url('get-involved/guides/new-developers') -%}
|
|
Read the <a href="{{ newdevs }}">new developers guide</a> first.
|
|
{%- endtrans %}</p>
|
|
|
|
<h2>{{ _('Basic Guidelines and Coding Style') }}</h2>
|
|
|
|
<p>{% trans -%}
|
|
Most of the following should be common sense for anybody who has worked on open source or in a commercial
|
|
programming envrionment.
|
|
The following applies mostly to the main development branch i2p.i2p.
|
|
Guidelines for other branches, plugins, and external apps may be substantially different;
|
|
check with the appropriate developer for guidance.
|
|
{%- endtrans %}</p>
|
|
|
|
<h3>{{ _('Community') }}</h3>
|
|
<ul>
|
|
<li>{% trans -%}
|
|
Please don't just "write code". If you can, participate in other development activities, including:
|
|
development discussions and support on IRC, zzz.i2p, and forum.i2p; testing;
|
|
bug reporting and responses; documentation; code reviews; etc.
|
|
{%- endtrans %}</li>
|
|
<li>{% trans -%}
|
|
Active devs should be available periodically on IRC #i2p-dev.
|
|
Be aware of the current release cycle.
|
|
Adhere to release milestones such as feature freeze, tag freeze, and
|
|
the checkin deadline for a release.
|
|
{%- endtrans %}</li>
|
|
</ul>
|
|
|
|
|
|
<h3>{{ _('Release Cycle') }}</h3>
|
|
<p>{% trans -%}
|
|
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.
|
|
{%- endtrans %}</p>
|
|
|
|
<ul>
|
|
<li>{% trans -%}
|
|
1-2 days after previous release: Checkins to trunk are allowed.
|
|
{%- endtrans %}</li>
|
|
<li>{% trans -%}
|
|
2-3 weeks after previous release: Deadline to propagate major changes from other branches to trunk.
|
|
{%- endtrans %}</li>
|
|
<li>{% trans -%}
|
|
4-5 weeks before release: Deadline to request new home page links.
|
|
{%- endtrans %}</li>
|
|
<li>{% trans -%}
|
|
3-4 weeks before release: Feature freeze. Deadline for major new features.
|
|
{%- endtrans %}</li>
|
|
<li>{% trans -%}
|
|
2-3 weeks before release: Hold project meeting to review new home page link requests, if any.
|
|
{%- endtrans %}</li>
|
|
<li>{% trans -%}
|
|
7-10 days before release: String freeze. No more changes to translated ("tagged") strings.
|
|
Push strings to Transifex, announce translation deadline on Transifex.
|
|
{%- endtrans %}</li>
|
|
<li>{% trans -%}
|
|
7-10 days before release: Feature deadline. Bug fixes only after this time. No more features, refactoring or cleanup.
|
|
{%- endtrans %}</li>
|
|
<li>{% trans -%}
|
|
3-4 days before release: Translation deadline. Pull translations from Transifex and check in.
|
|
{%- endtrans %}</li>
|
|
<li>{% trans -%}
|
|
2-3 days before release: Checkin deadline. No checkins after this time without the permission of the release builder.
|
|
{%- endtrans %}</li>
|
|
<li>{% trans -%}
|
|
Hours before release: Code review deadline.
|
|
{%- endtrans %}</li>
|
|
</ul>
|
|
|
|
|
|
|
|
<h3>Monotone</h3>
|
|
<ul>
|
|
<li>{% trans -%}
|
|
Have a basic understanding of distributed source control systems, even if you haven't
|
|
used monotone 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 monotone before, start with baby steps.
|
|
Check in some small changes and see how it goes.
|
|
{%- endtrans %}</li>
|
|
<li>{% trans -%}
|
|
Test your changes before checking them in.
|
|
If you prefer the checkin-before-test development model,
|
|
use your own development branch (e.g. i2p.i2p.yourname.test)
|
|
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.
|
|
{%- endtrans %}</li>
|
|
<li>{% trans -%}
|
|
If your change is non-trivial, or you want people to test it and need good test reports
|
|
to know whether your change was tested or not, add a checkin comment to history.txt
|
|
and increment the build revision in RouterVersion.java.
|
|
{%- endtrans %}</li>
|
|
<li>{% trans -%}
|
|
Ensure that you have the latest monotonerc file in _MTN.
|
|
Do not check in on top of untrusted revisions.
|
|
{%- endtrans %}</li>
|
|
<li>{% trans -%}
|
|
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.
|
|
{%- endtrans %}</li>
|
|
<li>{% trans -%}
|
|
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 monotone
|
|
and do the development there so you do not block releases.
|
|
{%- endtrans %}</li>
|
|
</ul>
|
|
|
|
<h3>{{ _('Coding Style') }}</h3>
|
|
<ul>
|
|
<li>{% trans -%}
|
|
Coding style throughout most of the code is 4-spaces for indentation. Do not use tabs.
|
|
Do not reformat code. If your IDE or editor wants to reformat everything, get control of it.
|
|
Yes, we know 4 spaces is a pain, but perhaps you can configure your editor appropriately.
|
|
In some places, the coding style is different.
|
|
Use common sense. Emulate the style in the file you are modifying.
|
|
{%- endtrans %}</li>
|
|
<li>{% trans -%}
|
|
All new public and package-private classes and methods require Javadocs. Add @since release-number.
|
|
Javadocs for new private methods are desirable.
|
|
{%- endtrans %}</li>
|
|
<li>{% trans -%}
|
|
Classes in core/ (i2p.jar) and portions of i2ptunnel are part of our official API.
|
|
There are several out-of-tree plugins and other applications that rely on this API.
|
|
Be careful not to make any changes that break compatibility.
|
|
Don't add methods to the API unless they are of general utility.
|
|
Javadocs for API methods should be clear and complete.
|
|
If you add or change the API, also update the documentation on the website (i2p.www branch).
|
|
{%- endtrans %}</li>
|
|
<li>{% trans -%}
|
|
Tag strings for translation where appropriate.
|
|
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.
|
|
{%- endtrans %}</li>
|
|
<li>{% trans -%}
|
|
Use generics and concurrent classes where possible. I2P is a highly multi-threaded application.
|
|
{%- endtrans %}</li>
|
|
<li>{% trans -%}
|
|
Be familiar with common Java pitfalls that are caught by findbugs.
|
|
Run 'ant findbugs' to learn more.
|
|
{%- endtrans %}</li>
|
|
<li>{% trans -%}
|
|
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.
|
|
{%- endtrans %}</li>
|
|
<li>{% trans -%}
|
|
Explicitly convert between primitive types and classes;
|
|
don't rely on autoboxing/unboxing.
|
|
{%- endtrans %}</li>
|
|
<li>{% trans -%}
|
|
Don't use URL. Use URI.
|
|
{%- endtrans %}</li>
|
|
<li>{% trans -%}
|
|
Don't catch Exception. Catch RuntimeException and checked exceptions individually.
|
|
{%- endtrans %}</li>
|
|
<li>{% trans -%}
|
|
Don't use String.getBytes(). Use DataHelper.getUTF8() or DataHelper.getASCII().
|
|
{%- endtrans %}</li>
|
|
<li>{% trans -%}
|
|
Don't use String.split(). Use DataHelper.split().
|
|
{%- endtrans %}</li>
|
|
<li>{% trans -%}
|
|
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.
|
|
{%- endtrans %}</li>
|
|
</ul>
|
|
|
|
<h3>{{ _('Licenses') }}</h3>
|
|
<ul>
|
|
<li>{% trans -%}
|
|
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 lead developer.
|
|
{%- endtrans %}</li>
|
|
<li>{% trans -%}
|
|
For any images checked in from external sources,
|
|
it is your responsibility to first verify the license is compatible.
|
|
Include the license and source information in the checkin comment.
|
|
{%- endtrans %}</li>
|
|
</ul>
|
|
|
|
<h3>{{ _('Bugs') }}</h3>
|
|
<ul>
|
|
<li>{% trans trac=i2pconv('trac.i2p2.i2p') -%}
|
|
Managing Trac tickets is everybody's job, please help.
|
|
Monitor {{ trac }} for tickets you have been assigned or can help with.
|
|
Assign, categorize, comment on, fix, or close tickets if you can.
|
|
{%- endtrans %}</li>
|
|
<li>{% trans -%}
|
|
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.
|
|
{%- endtrans %}</li>
|
|
<li>{% trans -%}
|
|
Close a ticket 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.
|
|
{%- endtrans %}</li>
|
|
</ul>
|
|
|
|
{% endblock %}
|