Developer

Source Code

We are using git as our source code management system, hosted on github. We have many different git repositories for the website, freenet itself (fred), official plugins, the two installers, libraries and so on; for the list, see our page on github.

We strongly recommend that you use the official command-line git client, or the Windows port. If you want to use the Eclipse git integration, see the tutorial here.

You can obtain the latest source code from git using the following command line:

	git clone git://github.com/freenet/fred-staging.git

Once you have cloned the repository, to get new changes you should do:

	git pull origin

More information on how to use git is further down this page.

Git is a distributed revision control system, this means amongst other things:

• Everyone has a full copy of the repository, including all the history.
• Branching and merging is easy.
• Working offline (e.g. on a train) is easy.
• We are much less vulnerable to compromise or failure of a central server.
• Anonymous contribution over Freenet is much easier.
• Generally a more secure workflow.

Initially we used git in a manner similar to SVN: Every developer has the right to push to the repository, and we gave out push rights fairly liberally. However, this is probably not the best model: Many other projects using Git use a more centralised (or decentralised, depending on how you look at it) model where you fork the repository (this is really easy on github), make your changes, push them to your repository, and then ask us to pull them; then a core developer reviews the changes and either pulls them into the main repository or asks for further changes. The advantage is there are fewer reverts in the history, better code in general, stuff can be put off more easily when we are trying to get a release out, and the security model is simpler. We are trying to mode to this model at the moment. You may find it is easier to fork -staging and then post a pull request (github makes both of these things easy), rather than asking for push rights to -staging.

Each part of Freenet currently has two repositories: -official and -staging (e.g. fred-official and fred-staging). This is left over from our using git similarly to SVN: The -official repository has been reviewed and released at least as a pre-build, and only core devs can push to it - they must review the code they are pushing before doing so, and will usually sign a tag for the build or pre-build after doing so. The -staging repository almost anyone can write to. New developers should fork on github and then post pull requests.

Either way, please keep us informed of what you are doing with Freenet! Create a github account, and then contact us either through the development mailing list or on IRC in the #freenet channel at irc.freenode.net.Note that you must use a real (working) email address when committing; we will provide contributors with @freenetproject.org redirects if needed.

Build Instructions

To build the source code you will need Apache ANT.

Full Build

Building Fred (the Freenet reference daemon) with ant will pull in freenet-ext.jar for third party dependancies from the website. To build freenet-ext.jar yourself you need to get the contrib module, build it, and put it into lib/freenet-ext.jar before you build the main project. Note also that the contrib module contains a number of native libraries used to improve performance; you may also want to rebuild these.

Plugins, installers etc can generally be built with ant, but some libraries may be written in other languages and have their own building procedures.

Basic git workflow

To pull all changes to the repository:

	git pull origin

Or if you want to review the changes before you merge them into your local repository:

	git fetch origin
	git log -p -M --ignore-space-change master..origin/master

If you are happy with the changes, then either merge your local changes into the remote changes:

	git rebase origin/master

Or merge the remote changes into your local repository:

	git merge origin/master

The latter will result in a non-linear history, so you should use rebase unless your local changes are very large.

To commit your local changes to your local repository:

	git commit -a

Or:

	git commit [ filenames you want to commit ]

To upload your changes (assuming you have cloned the -staging tree):

	git push origin

To view recent changes:

	git log -p -M --ignore-space-change

To undo one or more local commits, assuming you have not pushed your changes, and have not merged remote changes (this will simply reset your local repository to a previous version, getting rid of everything since then):

	git reset [ last good revision ]

Or if you have committed your change, you will need to revert it:

	git revert [ revision to get rid of ]

More documentation for git can be found here or here.

If you don't like a commit, or think it could be improved, generally you should post to the devl mailing list. You should CC the author of the commit, but unless it is a trivial matter you should always mail devl.

Please avoid monster commits. All commits are reviewed manually both to ensure security and to avoid bugs, and this is much easier if you follow some basic rules:

• Keep cosmetic changes separate from functional changes. In particular, indenting and braces improvements, while these are generally acceptable, should not be mixed with functional changes.
• Don't break the build: When you push, fred should build. Ideally each individual commit should build.
• Small commits: "git commit" is a purely local operation, so there is no reason to combine a bunch of unrelated changes in a single commit. Obviously use your judgement.
• Big or controversial stuff should go on a branch, rather than just getting pushed. We may be in the process of getting a new build out, and if big stuff is pushed it is likely to be shifted to a branch while the build is deployed.

The website

To edit the website, check out the website-staging repository, edit the files (in pages/en/), commit and push as above. Then remind Toad to deploy it if he doesn't do so in a reasonable time. Alternatively, fork the website module on github, and then post a pull request. This may actually get results more quickly!

The website is php-based but is compiled at deploy time into static HTML. You can simulate this to see exactly what your changes will look like by running the make-pages.sh script (you will need php5-cgi). This outputs static HTML to output/.

We are trying to move most of the documentation to the wiki, which should be easier to edit.