Contributing to the ICE Website

This article outlines the process by which committers may modify the content of and contribute to the ICE website.

Install the PHP Development Tools (PDT)

You may use any Eclipse text editor to edit PHP and HTML files for the website. However, the PHP Development Tools (PDT) might make the experience more enjoyable. These tools can be installed in Eclipse via the Eclipse Marketplace or by selecting Help > Install New Software... and using the following site:

http://download.eclipse.org/tools/pdt/updates/3.4

Clone the ICE Website Repository

In Eclipse, create a new project. If you have installed the PHP Development Tools, make this a PHP Project. For this article, we will name this project www.

To access the code repository for the ICE website, open the Git perspective and select to Clone a Git repository. Select Clone URI in the dialog and then enter the following information into the dialog:

where committer_id in the dialog is your Eclipse Git committer identity. This might not be a value you would expect. To find your Eclipse Git identity, login to the Gerrit settings page using the email address and password that you use to login to eclipse.org. After successfully logging into the Gerrit settings page, the field labelled Username will display your committer_id.

Continue through the dialog selecting to check out the master branch and setting your Destination directory to the path to the project you created previously (www for this article). Also, check the box to Import all existing projects after clone finishes.

If you plan to set up a local test server, you will also need to check out the eclipse.org-common project. Clone this repository in a similar manner to how you checked out the ICE website repo with the following exceptions. The URI for the eclipse.org-common project is https://git.eclipse.org/r/www.eclipse.org/eclipse.org-common. The committer_id@ portion of the URI used for cloning the ICE repo may be omitted here (as shown in the previous sentence) if you do not plan to try to contribute code back to this project. Clone this repo into the same project as used for the ICE repo (www for this article).

Set Up and Test with a Local Server

Setting up a local test server is not strictly required for contributing to the ICE website. However, committing code that breaks the website and likely upsets other ICE contributors is discouraged, so completing this step to test locally before committing to the repo is highly encouraged.

If you are "web dev savvy" and have an existing installation of Apache 2.0+ and PHP 5.0+, you may be able to configure and use that as your test server. For the rest of us, Apache/MySQL/PHP distributions, such as XAMPP, MAMP, or WampServer, can help to make this process considerably more straight-forward. The distributions mentioned here are fairly non-intrusive, and their installers tend keep everything contained to a single directory. The installers for these distributions also tend toward minimal, or none in some cases, touching of any system configuration files. For this article, setting up a local test server on Mac OS X using MAMP will be used to demonstrate this process. Analogous operations in other distributions should exist to get a test server running on your computer.

After installing an Apache/MySQL/PHP distribution and starting the application, the Apache server root directory needs to be set to the directory of the project created previously (www for this article). This can be done in the MAMP GUI by selecting Preferences, and in the Web Server tab changing the Document Root to the project directory. The Ports tab allows the user to set the port for the Apache server. By default, this is set to 8888.

Changes made in the MAMP GUI modify the Apache httpd.conf file. This file may be modified directly. For MAMP, this file can be found at /Applications/MAMP/conf/apache/httpd.conf. For the default installation of XAMPP on Linux, this file is at /opt/lampp/etc/httpd.conf. The values for Listen, ServerName, and DocumentRoot should be set appropriate for your Apache server and project location. Restart the server after any changes. (The MAMP GUI will do this automatically if you use that route.)

With the Apache server running, you may use a web browser to access localhost:<apache-port>/ice to test your local version of the ICE website code. Alternatively, you can set up a run configuration to test directly in Eclipse. Select Run > Run Configurations... from the menu bar, and create a new PHP Web Application in the left side of the dialog. Set the Server, File, and URL to the values shown below or the appropriate values for your Apache server and Eclipse project.

Click Apply and Run. If successful, this will open an Eclipse browser displaying the ICE website homepage.

Commit Changes

When you are ready to commit changes back to the ICE website repository, the usual git utilities in Eclipse may be used. In the Commit Changes dialog, ensure that the Author: and Committer: fields contain the same information found in your Gerrit settings. Click Commit and Push. A Login dialog will appear. Enter the Username and Password values given by your Gerrit HTTP credentials. You may need to generate a password at the previous link first.

Access and Accept Gerrit Code Reviews

Changes pushed to the ICE website repository are subject to Gerrit code reviews before they can be merged into the master branch. You may view your recently committed changes by visiting your Eclipse Gerrit change log. To merge your changes into the repo, select the commit message in the Outgoing reviews section. On the resulting page, click on Reply... near the top-center of the page. Optionally add a comment to the resulting dialog, and select the appropriate radio buttons next to Code-Review and Verified to accept or reject your proposed changes before clicking Post. To finally complete the Gerrit code review and merge changes into the repo, click Submit. The commit may be aborted by clicking Abandon.