Differences between revisions 3 and 4
Revision 3 as of 2009-09-20 21:44:09
Size: 4532
Editor: localhost
Comment: converted to 1.6 markup
Revision 4 as of 2013-05-31 15:13:59
Size: 4614
Comment:
Deletions are marked like this. Additions are marked like this.
Line 2: Line 2:

''' WARNING: THESE INSTRUCTIONS ARE OUTDATED - THE SITE NOW USES SVNPUBSUB '''

WARNING: THESE INSTRUCTIONS ARE OUTDATED - THE SITE NOW USES SVNPUBSUB

Updating the HttpComponents Main Site

For updating other parts of our website, see WebSite.

1. 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.

2. 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.

3. 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 "..."

4. 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.

WebSite/MainSite (last edited 2013-05-31 15:13:59 by SebastianBazley)