kytv/I2P_Website
1
0
Fork 0
forked from I2P_Developers/i2p.www
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Moved developer and translator guides into volunteer/guides

Browse Source
This commit is contained in:
str4d
2012-11-11 03:12:16 +00:00
parent b34b194128
commit 899892e6f7
5 changed files with 27 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
i2p2www/pages/global/nav.html
View File

@@ -69,6 +69,13 @@
<li class="has-sub"><a href="#"><span>{{ _('Volunteer') }}</span></a>
<ul>
<li><a href="{{ site_url('volunteer') }}"><span>{{ _('Get involved!') }}</span></a></li>
<li class="has-sub"><a href="#"><span>{{ _('Guides') }}</span></a>
<ul>
<li><a href="{{ site_url('volunteer/guides/newdevelopers') }}"><span>{{ _('New developers') }}</span></a></li>
<li><a href="{{ site_url('volunteer/guides/devguidelines') }}"><span>{{ _('Developer guidelines and coding style') }}</span></a></li>
<li><a href="{{ site_url('volunteer/guides/newtranslators') }}"><span>{{ _('New translators') }}</span></a></li>
</ul>
</li>
<li><a href="{{ site_url('volunteer/team') }}"><span>{{ _('Team') }}</span></a></li>
<li><a href="{{ site_url('volunteer/halloffame') }}"><span>{{ _('Hall of Fame') }}</span></a></li>
<li><a href="{{ site_url('volunteer/bounties') }}"><span>{{ _('Bounties') }}</span></a></li>

130
i2p2www/pages/site/volunteer/guides/devguidelines.html Normal file
View File

@@ -0,0 +1,130 @@
{% extends "global/layout.html" %}
{% block title %}Developer Guidelines and Coding Style{% endblock %}
{% block content %}
<p>
Read the <a href="{{ site_url('volunteer/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 %}

186
i2p2www/pages/site/volunteer/guides/newdevelopers.html Normal file
View File

@@ -0,0 +1,186 @@
{% extends "global/layout.html" %}
{% block title %}New Developer's Guide{% endblock %}
{% block content %}
<p>
So you want to start work on I2P? Great!
Here's a quick guide to getting started
on contributing to the website or the software, doing development or creating translations.
</p>
<p>
Not quite ready for coding?
Try <a href="{{ site_url('volunteer') }}">getting involved</a> first.
</p>
<div id="TOC">
<ol>
<li><a href="#basic-study">Basic study</a></li>
<li><a href="#getting-the-i2p-code">Getting the I2P code</a></li>
<li><a href="#building-i2p">Building I2P</a></li>
<li><a href="#development-ideas">Development ideas</a></li>
<li><a href="#making-the-results-available">Making the results available</a></li>
<li><a href="#get-to-know-us">Get to know us!</a></li>
<li><a href="#translations">Translations</a></li>
<li><a href="#tools">Tools</a></li>
</ol>
</div>
<h2 id="basic-study">Basic 'study'</h2>
<p>
Basic development on the I2P router or the embedded applications uses Java as the main development language.
If you don't have experience with Java, you can always have a look at <a href="http://www.mindview.net/Books/TIJ/">Thinking in Java</a>.
</p>
<p>
Study the <a href="{{ site_url('docs/how/intro') }}">how intro</a>,
the <a href="{{ site_url('docs') }}">other "how" documents</a>,
the <a href="{{ site_url('docs/how/techintro') }}">tech intro</a>,
and associated documents.
These will give you a good overview of how I2P is structured and what different things it does.
</p>
<h2 id="getting-the-i2p-code">Getting the I2P code</h2>
<p>
For development on the i2p router or the embedded applications,
get the monotone source repository installed - short instructions:
</p>
<ul>
<li>
Install <a href="http://www.monotone.ca/">monotone</a>.
Monotone is a version control system.
We use it because it allows us to keep track of who does what changes to the source code (and for a lot of complicated things, but 'keeping track of changes' is the basic idea).
</li>
<li>Skim over the <a href="http://monotone.ca/docs/Tutorial.html">monotone tutorial</a>, to make sure you understand the concepts.</li>
<li>
<p>
If you want to remain anonymous, you need to do an additional step, to set up a connection to a monotone server over I2P:
</p>
<p>
Enable the <a href="{{ site_url('docs/api/i2ptunnel') }}">i2ptunnel</a> client tunnel on port 8998 pointing to mtn.i2p2.i2p.
</p>
</li>
<li>
Pick a directory where you want to put all your I2P files, and create a monotone database: <code><b>mtn -d i2p.mtn db init</b></code>
</li>
<li>Define the trust list by creating <code>~/.monotone/monotonerc</code> (or <code>_MTN/monotonerc</code> in the i2p.i2p workspace) with the following contents:
{% include "include/monotonerc.html" %}
</li>
<li>Copy and paste the <a href="developerskeys">developer's commit keys</a> into a new file (e.g. <code>keys.txt</code>) in the same directory
that <code>i2p.mtn</code> is in. Import the keys into your database with <br><code><pre> mtn -d i2p.mtn read < keys.txt</pre></code>
<li>
Pull the I2P sources to your machine. This may take a long time, especially if you are doing this over I2P!
<ul>
<li>Anonymously: <code><b>mtn -d i2p.mtn pull 127.0.0.1:8998 i2p.i2p -k""</b></code></li>
<li>
<p>
Non-anonymously: <code><b>mtn -d i2p.mtn pull mtn.i2p2.de i2p.i2p -k"" </b></code>
</p>
<p>
Alternatively, instead of 'mtn.i2p2.de', you can also download from mtn.i2p-projekt.de.
</p>
</ul>
</li>
<li>
<p>
All the sources are now present on your machine, in the database file. To make them available in a directory, you need to check them out: <code><b>mtn -d i2p.mtn co --branch=i2p.i2p</b></code>
</p>
<p>
The above command creates a directory i2p.i2p, which contains all of the I2P sources.
</p>
</li>
</ul>
<h3>Remarks</h3>
<p>
To download the website files instead of the I2P source files, use 'i2p.www' instead of 'i2p.i2p'.
</p>
<p>
The initial pull may take several hours using the tunnel.
If it fails after a partial pull, simply rerun it, it will start where it left off.
If you are in a hurry, use the non-anonymous access.
</p>
<p>
A full list of branches, including i2p.i2p and i2p.www can be found on <a href="http://stats.i2p/cgi-bin/viewmtn/">viewmtn</a>.
</p>
<p>
A long explanation about using monotone is available on the <a href="monotone">monotone page</a>.
</p>
<h2 id="building-i2p">Building I2P</h2>
<p>
To compile the code, you need the Sun Java Development Kit 6 or higher, or equivalent JDK
(<a href="http://java.sun.com/javase/downloads/index.jsp">Sun JDK 6</a> strongly recommended) and
<a href="http://ant.apache.org/">Apache ant</a>
version 1.7.0 or higher.
If you go are working on the main I2P code, you can go into the i2p.i2p directory and run 'ant' to see the build options.
</p>
<p>
To build or work on console translations, you need
the xgettext, msgfmt, and msgmerge tools from the
<a href="http://www.gnu.org/software/gettext/">GNU gettext package</a>.
</p>
<p>
For development on new applications,
see the <a href="{{ site_url('develop/applications') }}">application development guide</a>.
</p>
<h2 id="development-ideas">Development ideas</h2>
<p>
See <a href="http://zzz.i2p/forums/3">zzz's TODO lists</a>,
<a href="{{ site_url('volunteer/todo') }}">this website's TODO list</a> or
<a href="http://trac.i2p2.de/report/1">Trac</a>
for ideas.
</p>
<h2 id="making-the-results-available">Making the results available</h2>
<p>
See the bottom of <a href="{{ site_url('develop/licenses') }}#commit">licenses.html</a> for
commit privilege requirements. You need these to put code into i2p.i2p (not required for the website!).
</p>
<p>
Short version of how to generate and use keys if you plan to commit:
<ul>
<li>mtn genkey yourname-transport@mail.i2p <i>(use an empty passphrase)</i>
<li>mtn genkey yourname@mail.i2p <i>(enter a passphrase)</i>
<li>mtn pubkey yourname-transport@mail.i2p <i>(<a href="mailto:mtn@welterde.de">send</a> this to a mtn repo operator to get push privileges)</i>
<li>mtn pubkey yourname@mail.i2p <i>(send this to <a href="mailto:zzz@mail.i2p">a release manager</a> to get commit privileges - not required for website)</i>
<li>mtn ci -k yourname@mail.i2p <i>(check in with this key)</i>
<li>mtn sync -k yourname-transport@mail.i2p <i>(push with this key)</i>
</ul>
Long version: see the <a href="monotone">monotone page</a>.
</p>
<h2 id="get-to-know-us">Get to know us!</h2>
<p>
The developers hang around on IRC. They can be reached on the Freenode network, OFTC, and on the I2P internal networks. The usual place to look is #i2p-dev. Join the channel and say hi!
We also have <a href="dev-guidelines">additional guidelines for regular developers</a>.
</p>
<h2 id="translations">Translations</h2>
<p>
Website and router console translators: See the <a href="{{ site_url('volunteer/guides/newtranslators') }}">New Translators Page</a>
for next steps.
</p>
<h2 id="tools">Tools</h2>
<p>
I2P is open source software that is mostly developed using open sourced
toolkits. The I2P project recently acquired a license for the YourKit Java
Profiler. Open source projects are eligible to receive a free license provided
that YourKit is referenced on the project web site. Please get in touch if you
are interested in profiling the I2P codebase.
</p>
<p>
YourKit is kindly supporting open source projects with its full-featured Java Profiler.
YourKit, LLC is the creator of innovative and intelligent tools for profiling
Java and .NET applications. Take a look at YourKit's leading software products:
<a href="http://www.yourkit.com/java/profiler/index.jsp">YourKit Java Profiler</a> and
<a href="http://www.yourkit.com/.net/profiler/index.jsp">YourKit .NET Profiler</a>.
</p>
{% endblock %}

178
i2p2www/pages/site/volunteer/guides/newtranslators.html Normal file
View File

@@ -0,0 +1,178 @@
{% extends "global/layout.html" %}
{% block title %}New Translator's Guide{% endblock %}
{% block content %}
Here's a very quick guide to getting started.
<h2>How to Translate the Website</h2>
<ol>
<li>
Preparation
<ol>
<li>
Come to #i2p-dev on irc and talk to people.
Claim the language -
To make sure other coworkers don't bump onto the files you are working on,
please update the translation status on <a href="http://ugha.i2p/i2pTranslation">this wiki page</a>.</li>
<li>
Follow the <a href="{{ site_url('volunteer/guides/newdevelopers') }}">new developer's guide</a>,
Including the installation of monotone,
checking out i2p.www branch, and generate your own monotone keys.
It is not required that you sign a dev agreement.</li>
</ol>
<li>
Create files:
If the file for your language does not exist yet, copy another language file to a new file <code>foo_xx.bar</code> for your language.
Then '<code>mtn add</code>' the file.
Also add a <code>_layout_xx.html</code> for your language xx.
Add a flag image file for the menu (copy from the router).</li>
<li>
Edit files:
Edit <code>_layout_xx.html</code>, <code>_menu.html</code>, and other files with any text editor.
Be sure not to use an editor in HTML mode that reformats everything.</li>
<li>
Check in:
<code>mtn pull</code>, <code>mtn update</code>. Then check in by "<code>mtn ci -k yourname@mail.i2p file1 file2 ...</code>"
This collects the diff info of your changed file into your local repo. Then "<code>mtn sync mtn.i2p2.de -k yourname-transport@mail.i2p i2p.i2p</code>".
This synchronizes your local repo with the repo on the target machine.</li>
<li>
Repeat. Check in often. Don't wait until it is perfect.</li>
</ol>
<h2>How to Translate the Router Console</h2>
<p>The easiest way by far to translate the router console is to sign up for an account at
<a href="https://www.transifex.com/projects/p/I2P/">Transifex</a> and request to join a translation team.
Alternatively it can be done "the old way" as outlined below.</p>
<ol>
<li>
Preparation
<ol>
<li>
Come to #i2p-dev on irc and talk to people.
Claim the language -
To make sure other coworkers don't bump onto the files you are working on,
please update the translation status on <a href="http://ugha.i2p/i2pTranslation">this wiki page</a>.</li>
<li>
Follow the <a href="{{ site_url('volunteer/guides/newdevelopers') }}">new developer's guide</a>,
Including the installation of monotone and the gettext tools,
checking out i2p.i2p branch, and generate your own monotone keys.</li>
<li>
Generate your own gpg key and sign the dev agreement.</li>
</ol></li>
<li>
Before starting a console translation, better help translate some i2p webpages first.
At least an i2p homepage in your language would be great. This will also help you learn monotone.</li>
<li>
What to translate:
There are about 15 files in the i2p.i2p branch that needs translation:
<ul>
<li>
<code>installer/resources/readme/readme_xx.html</code></li>
<li>
<code>installer/resources/initialNews/initialNews_xx.xml</code></li>
<li>
<code>apps/routerconsole/locale/messages_xx.po</code></li>
<li>
<code>installer/resources/proxy/*_xx.ht</code> (about 9 files)</li>
<li>
<code>apps/routerconsole/jsp/help_xx.jsp</code></li>
<li>
<code>installer/resources/eepsite.help/help/index_xx.html</code></li>
<li>
<code>apps/i2ptunnel/locale/messages_xx.po</code></li>
<li>
<code>apps/i2psnark/locale/messages_xx.po</code></li>
<li>
<code>apps/susidns/locale/messages_xx.po</code></li>
</ul>
Where xx is your language code like fr/de/ch/zh/...
There may be or may not be files with your lang code. If not, you can create your own. by copying and renaming other language files you know with your own lang code.
</li>
<li>
Create files:
If the file for your language does not exist yet, copy another language file to a new file foo_xx.bar for your language.
Then 'mtn add' the file.
After creating a .po file, edit the headers. Then run 'ant distclean poupdate'.
</li>
<li>
Start to work:
Edit the HTML files with any text editor.
Be sure not to use an editor in HTML mode that reformats everything.
To work with .po files efficiently, you may wish to use <a href="http://www.poedit.net/download.php">POEdit</a>
</li>
<li>
Check in:
mtn pull, mtn update. Then check in by "mtn ci -k yourname@mail.i2p file1 file2 ..."
This collects the diff info of your changed file into your local repo. Then "mtn sync mtn.i2p2.de -k yourname-transport@mail.i2p i2p.i2p".
This synchronizes your local repo with the repo on the target machine.
</li>
<li>
Repeat. Check in often. Don't wait until it is perfect.
</li>
</ol>
<p>As you can see, it's not that difficult.
If you have questions about the meaning of the terms in the console, ask in #i2p-dev on IRC.
</p>
<h2>FAQ</h2>
<b>Q: Why do I have to install monotone, Java, jsp, learn about .po files and html, etc.? Why can't I just do a translation and email it to you?</b>
<b>Answer: Several reasons:</b>
<ul>
<li>You might be interested in translating via Transifex. Request to join a translation team <a href="https://www.transifex.com/projects/p/I2P/">here</a></li>
<li>
We don't have anybody who has time to accept manual contributions and submit them to our source control system on your behalf. Even if we did, it doesn't scale.</li>
<li>
Maybe you are thinking translation is a one-step process. It isn't. You can't do it all at once. You will make mistakes. You need to test it and tweak it to make it look right <i>before</i> you submit it. Developers will update or add to the English text, thus requiring a translation update.
</li>
<li>
Having translators use a source control system directly provides authentication and accountablility - we know who is doing what, and we can track changes, and revert them if necessary.
</li>
<li>
.po files are not difficult. If you don't want to work directly with them, we recommend 'poedit'.
</li>
<li>
HTML files are not difficult. Just ignore the html stuff and translate the text.
</li>
<li>
Installing and using monotone is not that difficult. Several of the translators and other contributors to I2P are non-programmers, and they use monotone regularly. Monotone is simply a source control system, it is not about "coding".
</li>
<li>
Our items to translate are not "documents". They are html files and po files, with a specific format and character encoding (UTF-8) that must be maintained, and not corrupted by email programs or other methods of transfer.
</li>
<li>
We looked at 'pootle' as a front-end for translators. It didn't work well, needed an administrator, and a pootle-based process would suffer from a number of the above flaws.</li>
</ul>
<b>In summary:</b>
Yes, we know it is somewhat of a hurdle to get started. It's really the only possible way we can do it. Give it a try, it really isn't that hard.
<h2>More Information</h2>
The #i2p-dev channel on IRC, or the <a href="http://zzz.i2p/forums/14">translation forum on zzz.i2p</a>.
{% endblock %}

8
i2p2www/pages/site/volunteer/index.html
View File

@@ -4,7 +4,7 @@
<h1>We need your help!</h1>
<p>To get involved, please feel free to join us on the #i2p IRC channel (on
irc.freenode.net, or within I2P on irc.freshcoffee.i2p or irc.postman.i2p).</p>
<p>If you're interested in joining our <a href="team">team</a>, please get in
<p>If you're interested in joining our <a href="{{ site_url('volunteer/team') }}">team</a>, please get in
touch as we're always looking for eager contributors!</p>
<p>
We need help in many areas, and you don't need to know Java to contribute!
@@ -36,17 +36,17 @@ There's plenty to do if you know Java or are ready to learn.
Check for open tickets on <a href="http://trac.i2p2.de/report/1">Trac</a>
or the TODO list on <a href="http://zzz.i2p/">zzz.i2p</a> for
some ideas on where to start.
See the <a href="newdevelopers.html">new developer's guide</a> for details.
See the <a href="{{ site_url('volunteer/guides/newdevelopers') }}">new developer's guide</a> for details.
</li><li><b>Translation</b> &mdash;
Help translate the website and the software into your language.
See the <a href="newtranslators.html">new translator's guide</a> for details.
See the <a href="{{ site_url('volunteer/guides/newtranslators') }}">new translator's guide</a> for details.
</li><li><b>Analysis</b> &mdash;
Study or test the code to look for vulnerabilities.
Both anonymity vulnerabilities from the various
<a href="{{ site_url('docs/how/threatmodel') }}">threat models</a>,
and DOS and other weaknesses due to securities holes,
need researching.
</li><li><b><a href="donate.html">Donate</a></b>
</li><li><b><a href="{{ site_url('volunteer/donate') }}">Donate</a></b>
</li></ul>
{% endblock %}