Title: Release Download Pages (DRAFT)
Notice: Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
.
http://www.apache.org/licenses/LICENSE-2.0
.
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
A release download page is the page that links the project's content to the
mirrored artifact download. This document aims to describe the various
options available to projects for download pages together with policy and
best practices. (Background about the policy is in a [separate
document](mirrors).) Release managers are the target audience.
# Contents #
[TOC]
# Help Wanted! # {#help}
Help to finish this document by [contributing documentation
patches](infra-site.html) ! If the information you seek isn't in this
document, then please submit a patch once the infrastructure folks have
answered your question.
# Download Links # {#links}
- All links to the mirrored distribution artifacts **must not** reference
the main Apache web site. They *should* use the standard mechanisms to
distribute the load between the mirrors.
- All links to checksums, detached signatures and public keys **must**
reference the main Apache web site and *should* use https:// (SSL).
- Old releases *should* be [archived](release.html#how-to-archive) and may
be linked from the download page.
- Artifacts which are not full official releases (for example, milestones,
betas and alphas) may be linked from the download page. Links to these
artifacts should be removed in a timely fashion.
# Download Scripts # {#download-scripts}
Balancing the downloads between mirrors requires the use of a script. A
standard mechanism has been created that allows scripts to be easily
created which will not only comply with mirroring distribution policy but
also take advantage of more advanced features such as intelligent selection
of a preferred mirror. This mechanism is described below.
There are two basic options available:
- The [generic download script](#closer) is quick to setup but is linked
from (rather than integrated with) the project documentation.
- A [project specific script](#custom) which is integrated with a page
created in the normal way for the project and which uses the project's
standard document look and feel. This option takes more time to setup.
# Standard Generic Download Script # {#closer}
The starting point for a generic script is a download page. This is just a
page in the standard documentation which describes the releases. To use the
generic script, this page needs to be altered so that the actual download
links to the generic script in the appropriate fashion.
The generic script is called `closer.cgi`. The relative path of the
distribution (from the distribution root to the artifact) needs to be
passed in as a parameter. So (for example) if the artifact is
`foo-5.5.1.zip` and is located in `bar/foo` relative to
`/www/www.apache.org/dist` then
[http://www.apache.org/dyn/closer.cgi/bar/foo/foo-5.5.1.zip](http://www.apache.org/dyn/closer.cgi/bar/foo/foo-5.5.1.zip)
will display the mirrored distribution for download.
**Note** there is some information which every project should include on
the download page. Please read [best practices](#best_practice).
# Project Specific Download Script # {#custom}
To create a project specific download page, two elements are needed:
- a wrapper cgi script (for the standard python mirroring script)
- a project page (containing information to be presented to the user
together with variables to be replaced by the script)
The script takes the path to the project page as an input and passes this
to the standard mirroring script. The standard script then reads the page
and uses information about the mirrors to substitute values for the
varibles. When linking to the project page (for example, from the rest of
the project documentation), it is important that these links are targeted
at the script address (and not the page address).
Conventionally, the wrapping script is called `download.cgi`. This should
be created in the same directory as the project page. This wrapper script
just needs to set up the correct directory and call the mirroring script.
The following will do:
:::shell
#!/bin/sh
# Wrapper around the standard mirrors.cgi script
exec /www/www.apache.org/dyn/mirrors/mirrors.cgi $*
The release download page should be generated in the same way as the rest
of the project documentation. By convention, the name of the output should
be `download.html`.
**Note:** the mirroring script guesses the download release page to be
processed by matching file names. There is no requirement to call the
script `download.cgi` and the download release page `download.html` but the
name of the script must correspond to the name of the download page. For
example, `release.cgi` and `release.html` will work but `download.cgi` and
`release.html` will not.
There are a number of elements that a [good project download
page](http://httpd.apache.org/download.cgi) should contain. The content
used to generate that page can be viewed
[here](http://svn.apache.org/repos/asf/httpd/site/trunk/content/download.mdtext).
Downloads of artifacts linked to a mirror by an variable url. The correct
mirroring base url will be substituted for the `[preferred]` variable. The
rest of the url should be the path to the artifact relative to the base of
the Apache distribution directory.
For example, for artifact `foo-1.0.0.tar.gz` contained in `bar/foo` should
use `[preferred]/bar/foo/foo-1.0.0.tar.gz`
Links to the checksum and signature for the artifact should be given next
to the download link. It is important that users check the sum and verify
the signature so these links should be close and clear. **Note:** these
documents *must not* be mirrored.
For example, for artifact `foo-1.0.0.tar.gz` contained in `bar/foo` :
zip
MD5
PGP
Users should also be given information about the mirrors and the chance to
choose a different mirror (if they prefer). This is a little complex to
describe so here is a typical script:
<p>[if-any logo]
<a href="[link]"><img align="right" src="[logo]" border="0"
/></a>[end]
The currently selected mirror is <b>[preferred]</b>. If you
encounter a
problem with this mirror, please select another mirror. If all
mirrors are failing, there are <i>backup</i> mirrors (at the
end of
the mirrors list) that should be available.</p>
<form action="[location]" method="get" id="SelectMirror">
Other mirrors: <select name="Preferred">
[if-any http]
[for http]<option value="[http]">[http]</option>[end]
[end]
[if-any ftp]
[for ftp]<option value="[ftp]">[ftp]</option>[end]
[end]
[if-any backup]
[for backup]<option value="[backup]">[backup]
(backup)</option>[end]
[end]
</select>
<input type="submit" value="Change" />
</form>
<p>You may also consult the <a
href="http://www.apache.org/mirrors/">complete
list of mirrors</a>.</p>
% svn propset svn:executable yes download.cgi
% svn commit