This page contains instructions which might help you if you want to join the dgpf-project. We will explain how to create a SourceForge-account, how to contact the DGPF-team to add you as project member, and how to prepare your SourceForge-account so you can use the project's CVS and other services when once became a project member.
To create a SourceForge-account, goto http://www.sourceforge.net and click on the "create account"-button. (see image 1).
A form equal to the one illustrated in image 2 will be displayed. Fill in the fields and click "Create Account".
After this is done, log into your new account.
After your SourceForge-account has been set up, you can join the DGPF-project. Visit therefore the DGPF-project's website http://sourceforge.net/projects/dgpf/ and click on a project admin, as illustrated in image 3.
You will get to the user page of the admin you've select, click on "Send this user a message", like it is shown in image 4.
Fill in the form now appearing as shown in image 5 with a short message that you want to join the DGPF-project and what you want to contribute to it, and click on "Send Message". Your message will be received by the project admin of your selection, and he/she will process it as soon as possible and inform you after you've been added.
Our project uses SourceForge's CVS services. To access our CVS-repository you need to set a public-key for your account. For Windows users, we recommend to use PuTTY/PuTTYGen, available at http://www.putty.nl/download.html and included in common Windows CVS-clients like TortoiseCVS and WinCVS.
To create a private/public key pair with PuTTYGen, follow these steps:
Now go to the home page of your account ("My Page") and click on "Preferences", as demonstrated in image 8.
Scroll down to "Host Access Information" and click onto "Edit SSH Keys for Shell/CVS", like it is done in image 9.
Go back to the PuTTYGen Window. Copy your public key data from the "Public key for pasting into OpenSSH authorized_keys file" (shown in image 10) section of the PuTTY Key Generator, and paste the key data to the provided form on the SourceForge.net site. Click on the "Update" button to complete the posting process. (Illustrated in image 11.)
Exit the PuTTY Key Generator.
Key data sync to hosts from the SourceForge.net site occurs on regular intervals. Your key data will be synchronized to the designated server (shell and CVS) after a short delay.
To work with our project properly, you should install the following software.
Our project is based on Sun's Java Technology. To be precise, we use the Java 2 Platform, Standard Edition (J2SE) in the version 1.5.0.
Using Java makes our project platform independent, you may run it on any sort of machine where there is a Java environment available for. Our project might migrate to newer versions of Java if it looks useful to us.
To find out which version of Java you've installed, type java -version into your command
line. If the command is unknown, an error is displayed or it states a value < 1.5.0, you need to
download and install the Java software.
If you are a developer who wants to modify or work with the code of our project, you need to install the J2SE Development Kit (JDK). If you only want to run our project's applications without working on the sources, the J2SE Runtime Environment (JRE) will do. Both can be downloaded from http://java.sun.com/j2se/1.5.0/download.jsp.
Eclipse is not required to work with our sources - but it is a convenient and useful developing environment. The source code in our CVS is grouped into Eclipse projects, so it might prove useful for you to work with Eclipse too. Currently, we're using Eclipse SDK Version 3.1.1, with newer versions, problems could arise since the compilers may be incompatible. Our project might migrate to newer versions of Eclipse if it looks useful to us.
You can download Eclipse from http://www.eclipse.org/downloads/.
Developers that directly contribute to our project may also need a SCP/SSH client to access the sourceforge directories where the website of the project is stored. Normally, only the project administrator will do so, but it is always a good idea to have the tools at hand.
For Windows users I recommend WinSCP. You can download it at http://winscp.net/eng/download.php.
You can access the contents of your project via CVS. This utility allows multiple developers to work together on one project cooperatively. If you want to contribute to this project, you should use the project's CVS repository.
For Windows users I recommend the usage of TortoiseCVS.
You can download this utility at http://sourceforge.net/project/showfiles.php?group_id=48103.
You can browse our project's CVS repository with SourceForge's web-based CVS client here.
If you want to contribute to our project as developer, you should use Eclipse as SDK since the DGPF's packages are placed as Eclipse-projects into our CVS repository.
Eclipse is not required to work with our sources - but it is a convenient and useful developing environment. The source code in our CVS is grouped into Eclipse projects, so it might prove useful for you to work with Eclipse too. Currently, we're using Eclipse SDK Version 3.1.1, but any newer version will do as well. Our project might migrate to newer versions of Eclipse if it looks useful to us.
You can download Eclipse from http://www.eclipse.org/downloads/.
The source code contributed to our project follows some simple coding rules. It is much easier to comply to this rules when Eclipse reminds you to do so. For that, you can download the default Eclipse preferences for the project. They are included in the "Auxiliaries" package in the framework's download section. Download them here. If you don't know how to import them, just follow these steps: Step 1, Step 2, Step 3.
The most vital part of the coding rules are the Eclipse compiler settings. These will be set automatically if you load the preferences, but you also can set the manually under "Prefereces...", like this graphic demonstrates.
The source code contributed to our project follows some simple coding rules. These are specified here. If all developers of our project follow these rules correctly, the produced code will not only look the same in all classes and sub-packages, but will also comply to some basic primitives of software engineering, like being documented properly and consistently.
The DGPF-project uses a CVS repository. This page describes how Windows users can set up a Windows CVS client called TortoiseCVS. Before setting up your CVS client, you should've followed the instructions provided in Join the DGPF-project, especially those according the setting of a public key for your SourceForge-account.
TortoiseCVS is not required to work with our sources - but it is a convenient (as far as this is possible with CVS) and useful (as far as this is possible with CVS) tool. All data of our project is stored in the repository, from the sources, this website, to all available documents.
You can download TortoiseCVS from http://sourceforge.net/project/showfiles.php?group_id=48103.
After downloading, install the software.
In the TortoiseCVS-directory, you can find an utility called "pageant.exe". This program makes your private key (as created in Join the DGPF-project) accessible for TortoiseCVS.
Start Pageant. A new symbol will appear in the Task Bar Notification Area (bottom right part of the task bar) looking like
this: 
.
Right-click on the image and lick "Add Keys", as illustrated in image 1.
In the dialog emerging select the private key you've stored earlier (see Join the DGPF-project) as shown in image 2, confirm. You'll maybe be asked for a pass-phrase, if so, enter it and confirm again.
Before you can do this, you must've been added to the DGPF-project by an DGPF-admin.
Select the folder you want the DGPF-contents to be placed in. Right click, and in the context menu appearing select "CVS Checkout", as shown in image 3.
In the following dialog fill in as illustrated in image 4:
Confirm with "OK". Now the project's content will be checked out. This might take a while.
The source code contributed to our project follows some simple coding rules. The precise application of this rules helps others to understand and to work with our code.
The source code of our project is fully documented. This means, there are JavaDoc-tags for all elements.
| Java-Element | JavaDoc-Element to be applied |
|---|---|
| sub-project's root-package | A sub-project's root-package must contain an "Overview.html"-file. Additionally, there must be a folder in the
Releases-folder named like the sub-package containing the files "change_log.txt", "Manifest.MF" and
"release_notes.txt" with the change log, the jar-manifest to use and the release notes of the sub-project. |
package |
Inside ever package folder (also sub-packages) there must be a file called "package.html" containing information
about the package. Each package is described with at least two sentences. |
| class-file | Every class file starts with a specific header, stating when it was created, who works with it and such and such, as well as the license agreement. See the already existing files to find out how this header must look like. |
class |
For every class (and sub-class) there must be a JavaDoc comment stating what the class is used for and what it does.
For main classes (these which have the same name as the file they're included in) there is a @author-tag
stating its author. |
| member variable | For each member variable, there is a JavaDoc-comment stating what the variable is used for. |
| method | For each method, there is a JavaDoc-comment stating what it does. For each parameter (if any) of the method there is a
@param-tag stating its meaning. For the return value (if any) there is the @return-tag
stating its meaning. Exceptions possible thrown will be explained by using the @throws-tag. |
These documentation rules can be enforced by using the predefined Eclipse preferences, see Configuring Eclipse for more information.
If you get used to the naming rules, they will help you to identify the elements more quickly and easily.
| Java-Element | Naming-convention |
|---|---|
package |
Package names are all lowercase and consist of only one word. |
class |
Name starts with an uppercase letter, the rest is lower case. If the name is a concatenation of some words, each single word starts with an uppercase letter. |
static, final member |
Each letter is uppercase, words are separated by the underscore character ("_"). |
static, non-final member |
The name begins with "s_", each other letter is lowercase, words are separated by the underscore character ("_").
You should try to avoid such members as much as possible and try to replace them with non-static members. |
non-static member |
The name begins with "m_", each other letter is lowercase, words are separated by the underscore character ("_"). |
| method | Each letter is lowercase, words are separated by the underscore character ("_"). |
| parameters | The name begins with "p_", each other letter is lowercase, words are separated by the underscore character ("_"). |
| local variables | The name begins with "l_", each other letter is lowercase, words are separated by the underscore character ("_"). |
final as possible" - if you don't need to change/override them, mark them as final.
Final methods are faster, since the compiler can bind the statically.final static members (named in all upper case) are allowed to be
public. This enforces encapsulation of classes and functionality. Encapsulation, if consequently applied, eases future
changes and enforces separation of concern.static final memberstatic initializer if needed)static non-final memberstatic initializer if needed)this." Doing so furthers the understanding that a member access
is an indirect variable access, while a local variable can be accessed indirectly and faster. Also it helps you to see
what object the variable belongs to.@Override". This has something to do with Java's new features, and is generally a good thing,
though I'm not sure why :-)private static final long serialVersionUID = XXX;, where
XXX represents the serialization id of the class and is incremented on every release by one.s_) as much as possible and try to replace them with non-static members.
