Since our website only contains static information, we need to update the website every time a new release is published.

The code for our website is maintained in the $REEF_HOME/website directory, and thus updating the website generally follows the same process of creating a pull request on GitHub for some new feature or bug fix. Create a branch for the new website, make local changes, and then generate a pull request. There is one additional thing to do: publish the website contents on Apache svn. Detailed explanations on specific tasks, including the publishing step, are described below.

 

Adding new API documentation (Java)

For each release, we provide the corresponding Java API via javadoc. Run the following command at $REEF_HOME of a new release branch:

$ mvn javadoc:aggregate

HTML files will be generated under $REEF_HOME/target/site/apidocs. Move all files and folders from the new release's $REEF_HOME/target/site/apidocs to your PR branch's $REEF_HOME/website/target/staging/site/apidocs/$VERSION_NUM. For example, if the new release version is 0.14.0, then you would first run 'mvn javadoc:aggregate' at $REEF_HOME of the apache-reef-0.14.0 source code. Then, you should move the generated files and folders to $REEF_HOME/website/target/staging/site/apidocs/0.14.0 of the reef source code (the branch you created from master branch, not 0.14 release branch). They will be uploaded with the new website content, during the publishing step described below.

Adding new API documentation (.NET)

For each release, we provide the corresponding .NET API.

Install Doxygen from http://www.stack.nl/~dimitri/doxygen/download.html. Run the following command at $REEF_HOME of a new release branch:

$ doxygen

HTML files will be generated under $REEF_HOME/target/apidoc_net. Move all files and folders from the new release's $REEF_HOME/target/apidoc_net to your PR branch's $REEF_HOME/website/target/staging/site/apidoc_net/$VERSION_NUM. For example, if the new release version is 0.14.0, then you would first run 'doxygen' at $REEF_HOME of the apache-reef-0.14.0 source code. Then, you should move the generated files and folders to $REEF_HOME/website/target/staging/site/apidoc_net/0.14.0 of the reef source code (the branch you created from master branch, not 0.14 release branch). They will be uploaded with the new website content, during the publishing step described below.

Updating the website with new release information
 

Information about new release downloads and APIs can be updated using script $REEF_HOME/dev/update_website.py. Run the following command:

python update_website <reef_home> <reef_version> <sha512> <release_notes_link>

This change needs to be reviewed and merged to master branch, same as regular code changes.

 

New committers

The list of committers will change throughout the development of REEF. You can fix the lists by modifying $REEF_HOME/website/src/site/apt/team.apt. It shouldn't be hard to locate the list. Add (or remove) a new line in the following manner:

   jsjason   |  Joo Seong (Jason) Jeong | Seoul National University |
*------------*--------------------------*---------------------------*

The new committer should appear in the committer list. One thing to note: the ID column refers to a committer's Apache ID, not GitHub ID. Take a look at the ASF Committers page to check a committer's Apache ID.

 

Testing the website before publish

Before you actually publish the website publicly, you should (must!) generate and take a look at the actual HTML files and examine whether the intended changes were made correctly. Run the following command at $REEF_HOME/website:

$ mvn site:site

HTML files will be generated in the $REEF_HOME/website/target/staging/site directory. Open index.html and navigate through the files to your heart's content. One thing to note: links that point to past API pages will seem to be broken, since the website code doesn't automatically generate those files. Don't worry though; they should work fine on the Apache svn server.

 

Publishing the website

Run the publish script in $REEF_HOME/website:

$ ./publish.sh

Enter your Apache ID and password for authentication, and provide a short commit message (this commit message is for Apache svn, not GitHub). Make sure you run the script at $REEF_HOME/website; otherwise, the publish may not work correctly. This step may either take more than ten minutes (when uploading new javadoc API files), or less than one minute (no new API files).

  • No labels