[Jakarta-httpclient Wiki] Update of "WebSite/MainSite" by RolandWeber

[Apache Wiki <wi...@apache.org>]

Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Jakarta-httpclient Wiki" for change notification.

The following page has been changed by RolandWeber:
http://wiki.apache.org/jakarta-httpclient/WebSite/MainSite

New page:
#pragma section-numbers 2

= Updating the HttpComponents Main Site =

[[TableOfContents]]

== 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 ([http://maven.apache.org/doxia/references/apt-format.html Almost Plain Text])
or .xml ([http://maven.apache.org/maven-1.x/using/site.html#Creating_a_new_Document 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.
[[BR]]
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.
[[BR]]
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 [http://hc.apache.org/issue-tracking.html issue] in JIRA.
[[BR]]
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 [wiki:Self:WebSite 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 [http://people.apache.org people.apache.org].
[[BR]]
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.

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@hc.apache.org
For additional commands, e-mail: dev-help@hc.apache.org