- WARNING: THESE INSTRUCTIONS ARE OUTDATED - THE SITE NOW USES SVNPUBSUB*
The main site source is now located in https://svn.apache.org/repos/asf/httpcomponents/project-website/trunk
Updating the HttpComponents Main Site
For updating other parts of our website, see WebSite.
Prepare
You will need Subversion and Maven 2 to update the main site. The main site is stored in the project directory in Subversion.
Checkout the project directory from Subversion to a local directory:
svn co https://svn.apache.org/repos/asf/httpcomponents/project/
Alternatively, you may checkout the project trunk which includes the project directory as an external reference:
svn co https://svn.apache.org/repos/asf/httpcomponents/project-trunk/
If you are not a committer, you can use http: instead of https: for checkout.
Our Maven project is structured hierarchically, with the project directory on top and the components as subprojects. When you update the main site, it is important that you pass the -N or --non-recursive flag to Maven2. Otherwise, Maven will automatically descend to the components and modules, regenerating and/or deploying their sites as well. At best, this causes annoying delays.
Change and Review
The navigation bar to the left is defined in
project/src/site/site.xml
The pages are defined as .apt (Almost Plain Text) or .xml (XDoc) in
project/src/site/apt/ project/src/site/xdoc/
After changing the site, you can regenerate it with the following commands. Maven2 has to be called from the project directory, where pom.xml is located. If you have changed the navigation, use the clean target to enforce regeneration of all pages. Without that target, only pages for which the source file was modified will be regenerated.
mvn -N site:site mvn -N clean site:site
The site will be generated to the directory
project/target/site/
Links to the component sites are relative and will not work locally.
External links and links within the main site do work locally.
Patch
If you are not a committer, you can now generate a patch for contribution.
Change to the project directory and use Subversion to generate the patch in unidiff format:
svn diff > my-site-patch-xxx.txt
Please choose a meaningful name for the patch file. Then open an issue in JIRA.
Describe the changes that your patch takes care of, and attach the patch.
If you are a committer, you must commit the update to Subversion before deploying the site:
svn commit -m "..."
Deploy
Only HttpComponents committers can deploy our website. If you are not a committer, please contribute your update as a patch.
We currently deploy the main site directly from Maven2. There is some setup required to do that.
When deploying the main site, Maven2 will remove the execute permission from downloads.cgi. If this change is synced to the Apache webservers, our download site will not work anymore. It is therefore necessary to update the permission after deploying the site.
Open two terminals, one locally for deploying the main site, the other one remotely on people.apache.org.
On people.apache.org, prepare (but do not execute yet) the command for updating the permissions:
people.apache.org> chmod a+x /www/hc.apache.org/downloads.cgi
On your local machine, change to the project directory and deploy the main site. Deploying the site will not automatically regenerate it. Maybe you'd like to do that once more, just to be sure:
mvn -N clean site:site mvn -N site:deploy
Beware: You will be asked for your passphrase, and Maven2 shows your input in plain text on the terminal. Make sure nobody is watching you or the screen!
As soon as the deployment is complete, execute the command prepared above:
people.apache.org> chmod a+x /www/hc.apache.org/downloads.cgi
If you have deleted, moved or renamed pages, you have to remove them manually on people.apache.org.
Updates to the web site are synced with the Apache servers every few hours. Deletions are synced less frequently, so you will still be able to access the deleted pages when the updates are already visible. Try again the day after.