131 lines
5.5 KiB
HTML
131 lines
5.5 KiB
HTML
{% extends "global/layout.html" %}
|
|
{% block title %}Developer Guidelines and Coding Style{% endblock %}
|
|
{% block content %}
|
|
<p>
|
|
Read the <a href="{{ site_url('get-involved/guides/newdevelopers') }}">new developers guide</a> first.
|
|
</p>
|
|
|
|
<h2>Basic Guidelines and Coding Style</h2>
|
|
|
|
<p>
|
|
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.
|
|
</p>
|
|
|
|
<h3>Community</h3>
|
|
<ul>
|
|
<li>
|
|
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.
|
|
</li><li>
|
|
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.
|
|
</li></ul>
|
|
|
|
<h3>Monotone</h3>
|
|
<ul>
|
|
<li>
|
|
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.
|
|
</li><li>
|
|
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.
|
|
</li><li>
|
|
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.
|
|
</li><li>
|
|
Ensure that you have the latest monotonerc file in _MTN.
|
|
Do not check in on top of untrusted revisions.
|
|
</li><li>
|
|
Ensure that you pull the latest revision before you check in.
|
|
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.
|
|
</li><li>
|
|
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.
|
|
</li></ul>
|
|
|
|
<h3>Coding Style</h3>
|
|
<ul>
|
|
<li>
|
|
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.
|
|
</li><li>
|
|
New classes and methods require at least brief javadocs. Add @since release-number.
|
|
</li><li>
|
|
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).
|
|
</li><li>
|
|
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.
|
|
</li><li>
|
|
Use generics and concurrent classes where possible. I2P is a highly multi-threaded application.
|
|
</li><li>
|
|
We require Java 6 to build but only Java 5 to run I2P.
|
|
Do not use Java 6 classes or methods without handling the class not found exceptions
|
|
and providing alternate Java 5 code. See classes in net.i2p.util for examples.
|
|
</li><li>
|
|
Explicitly convert between primitive types and classes;
|
|
don't rely on autoboxing/unboxing.
|
|
</li></ul>
|
|
|
|
<h3>Licenses</h3>
|
|
<ul>
|
|
<li>
|
|
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.
|
|
</li><li>
|
|
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.
|
|
</li></ul>
|
|
|
|
<h3>Bugs</h3>
|
|
<ul>
|
|
<li>
|
|
Managing Trac tickets is everybody's job, please help.
|
|
Monitor trac.i2p2.i2p for tickets you have been assigned or can help with.
|
|
Asssign, categorize, comment on, fix, or close tickets if you can.
|
|
</li><li>
|
|
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.
|
|
</li>
|
|
</ul>
|
|
|
|
{% endblock %}
|