<chapter id="sentinel">
  <title>The web sentinel</title>

  <sect1 id="packageslist">
  <title>Existing and prospective packages</title>

<para>
The so called tasks pages probably give the most interesting overview
about what a Blend is actually doing for newcomers as well as a nice
quality assurance tool for developers.  If you want to see examples
for tasks pages just have a look at the
<ulink url="http://blends.debian.org/">list of all Blends</ulink>
using this technique and follow the links to the tasks pages once you
selected one specific Blend.
</para>
<para>
If a Debian Pure Blend should be presented one of the first questions
is, what packages are available.  The next question might be which
packages are on the todo list for inclusion in Debian to make Debian
even more attractive for people the Blend is targeting at.  Both
questions can be answered if you point people to the dynamically
created tasks page.  The page is rebuild daily to stay up to date
according to recent developments of the Blend.  The build process works
as follows:
 <itemizedlist>
 <listitem><para>Read dependency information of the <filename>tasks</filename> files.</para></listitem>
 <listitem><para>Verify whether there is really a package with this name and
       print the description of this package.</para></listitem>
 <listitem><para>If there is no such package in Debian try to parse
       the <filename>tasks</filename> file whether there is some information
       given and mark the result as prospective package for further
       inclusion.</para></listitem>
 </itemizedlist>
</para>
<para>
The rationale behind this is to provide as much as possible
information about packages that might be interesting for the target
user of the Blend.  Moreover the page can provide useful information for
developers about things that might be a useful help for the project to
work down the todo list and build Debian packages for software that is
not yet included in Debian.
</para>
</sect1>
  <sect1 id="edittasksfiles">
  <title>Tasks files controlling web sentinel content</title>

<para>

The content of the tasks files that are used to build the metapackage
content of a Blend is also used to determine the content of the web
sentinel pages.  Thus you can influence the tasks pages by simply
editing the tasks files inside the VCS of the sources of the Blends
metapackages.  The canonical location of these tasks files inside the
sources is (with the exception of Debian Edu that is locatet in Debian
Edu Git repositories) the Blends Git at
<informalexample>
    <programlisting>
      https://salsa.debian.org/blends-team/BLEND.git
    </programlisting>
</informalexample>
Here you can add or remove additional Dependencies to existing packages
or you can add additional information about so called prospective
packages.  The syntax how to do this is explained below.
</para>

<para>
To get the todo list built it is necessary to add some additional
information to the task files which are the main database of information
for the Blend.  The information is following the RFC822 syntax as all
Debian control files do and is kept quite simple:
<variablelist>

<varlistentry>
  <term>Depends / Recommends / Suggests</term>
   <listitem><para>Even if there is no Debian package available for the moment
         the names of prospective packages are given as if they would
         exists. The rationale behind is that once such a package
         might exist the source of the metapackage does not have to
         be changed and will work out of the box after rebuilding.</para>
   </listitem>
</varlistentry>

<varlistentry>
  <term>Ignore</term>
   <listitem><para>The Ignore key should be the favourite way to use for
     specifying prospective packages in case the packages should be
     evaluated once it appears in the Debian package pool.  If 
     "Depends", "Recommends" or "Suggests" are used for not yet
     existing packages they will be turned into the list of Suggests
     of the metapackage and thus might be possible to become
     installed on a users machine if the user decides to install all
     suggested packages.  If some evaluation should be done first the
     "Ignore" tag is your friend.</para>
   </listitem>
</varlistentry>

<varlistentry>
  <term>Homepage</term>
   <listitem><para>This is the URL to the software that should be packaged.</para>
   </listitem>
</varlistentry>

<varlistentry>
  <term>WNPP</term>
   <listitem><para>In case there might be a WNPP bug filed for this software the
       bug number is given here.  This helps to keep track of the
       ongoing effort to package the software.</para>
   </listitem>
</varlistentry>

<varlistentry>
  <term>Responsible</term>
   <listitem><para>In case some developer claimed to care for the software
       (perhaps by issuing the WNPP bug report) the e-mail address of
       this developer is given here to enable an easy way to contact
       this person.</para>
   </listitem>
</varlistentry>

<varlistentry>
  <term>License</term>
   <listitem><para>Debian cares always about the license.  This information
       about prospective packages should be easily available.</para>
   </listitem>
</varlistentry>

<varlistentry>
  <term>Vcs-Git</term>
   <listitem><para>If there is some Debian packaging stuff available this
       can be addressed in this field.  Unofficial packages which
       have this field set are rendered in a separate section with
       links to the packaging Git.
       </para><para>
       The usage for this field is the same as it is described in
       <ulink url="http://www.debian.org/doc/developers-reference/best-pkging-practices.html#bpp-vcs"
          >paragraph 6.2.5 of Debian developers reference</ulink>
       </para>
   </listitem>
</varlistentry>

<varlistentry>
  <term>Vcs-Browser</term>
   <listitem><para>If there is some Debian packaging stuff available this
       can be addressed in this field.  Unofficial packages which
       have this field set are rendered in a separate section above
       unofficial packages outside the official Debian mirrors.
       If you have set <filename>Vcs-Git</filename>
       there is no need to set <filename>Vcs-Browser</filename> explicitly
       because it is obtained automatically from the other fields.
       But you might override this automatically generated URL if
       needed.
       </para><para>
       The usage for this field is the same as it is described in
       <ulink url="http://www.debian.org/doc/developers-reference/best-pkging-practices.html#bpp-vcs"
          >paragraph 6.2.5 of Debian developers reference</ulink>
       </para>
   </listitem>
</varlistentry>

<varlistentry>
  <term>Pkg-URL</term>
   <listitem><para>In some cases there are unofficial packages for some software
       which are prepared by a third party.  It helps our users if
       they could install such a package and thus the URL to it might
       be a helpful hint.  This is also true for developers because
       they might have a look at this packaging before they start from
       scratch.  Often packages are available
       at <ulink url="http://mentors.debian.net/"
          >mentors.debian.net</ulink> and prepared by people who do not
       yet have an official Debian maintainer status and thus are not
       able to upload packages to the Debian mirror.  The packages at
       mentors are waiting for sponsoring of an official Debian
       maintainer and if such a package shows up in the Blend tasks list
       it might speed up the inclusion into official Debian
       distribution.</para>
   </listitem>
</varlistentry>

<varlistentry>
  <term>Pkg-Description</term>
   <listitem><para>This tag should give reasonable information about the
       software as it normally is done in <filename>debian/control</filename>
       files.  It can be either a copy of the description of the WNPP
       bug or could be used to file a WNPP bug and thus helps to
       simplify the packaging work.</para>
   </listitem>
</varlistentry>

<varlistentry>
  <term>Remark</term>
   <listitem><para>In some cases it makes perfectly sense to add a remark on
       behalf of the Blends team to a package which is visible on the
       tasks page.  This can be done using the Remark field.  It can
       be used in the same syntax as a Description field in Debian
       control files.</para>
   </listitem>
</varlistentry>

<varlistentry>
  <term>Registration</term>
   <listitem><para>Sometimes, specifically in the case of scientific software,
       the project authors ask for registration of their software to
       get numbers of users of their software.  These numbers enable
       them to ask for further funding of their project.  To support
       this intend of authors the tasks pages can feature a link to
       this registration page if the link is given in the tasks file
       in the Registration field.</para>
   </listitem>
</varlistentry>

</variablelist>
</para>

<sect2 id="webconf">
<title>Configuring Web Sentinel pages per Blend</title>

<para>
To set some typical values for the web sentinel per Blend each Blend
has to provide a configuration file.  These files are formatted in
RFC822 files and
<ulink url="http://anonscm.debian.org/gitweb/?p=blends/website.git;a=tree;f=webtools/webconf"
     >maintained in Git</ulink>.  The following values can be set:
<variablelist>

<varlistentry>
  <term>Blend</term>
   <listitem><para>Id of the Blend (for instance debian-edu, debian-med, etc.)</para>
   </listitem>
</varlistentry>

<varlistentry>
  <term>ProjectName</term>
   <listitem><para>Name the Blend in correct spelling.  Please note that English
         spelling is without a dash and it is "Debian Edu" (not
         Debian-Edu) and Debian Med (not Debian-Med)</para>
   </listitem>
</varlistentry>

<varlistentry>
  <term>ProjectUrl</term>
   <listitem><para>URL to technical information about the Blend</para>
   </listitem>
</varlistentry>

<varlistentry>
  <term>Homepage</term>
   <listitem><para>URL to the user oriented homepage of the Blend</para>
   </listitem>
</varlistentry>

<varlistentry>
  <term>LogoUrl</term>
   <listitem><para>URL to a logo image of the Blend</para>
   </listitem>
</varlistentry>

<varlistentry>
  <term>ProjectList</term>
   <listitem><para>E-Mail address of a mailing list where developers and users
   of the Blend are communicating</para>
   </listitem>
</varlistentry>

<varlistentry>
  <term>PkgList</term>
   <listitem><para>E-Mail address of a mailing list where developers of the
   Blend are discussing technical details of packaging</para>
   </listitem>
</varlistentry>

<varlistentry>
  <term>OutputDir</term>
   <listitem><para>Directory where to put the rendered HTML pages.  The Blends
   pages are hosted on blends.debian.org and usually stored
   at <filename>/srv/blends.debian.org/www/&lt;ProjectName&gt;</filename>
      </para>
   </listitem>
</varlistentry>

<varlistentry>
  <term>DataDir</term>
   <listitem><para>Directory where the rendering code stores temporary data like
   Git clones of tasks files etc.  This is usually set to
   <filename>/srv/blends.debian.org/data/&lt;ProjectName&gt;</filename>
      </para>
   </listitem>
</varlistentry>

<varlistentry>
  <term>VcsDir</term>
   <listitem><para>URL of tasks files in Blends VCS
      </para>
   </listitem>
</varlistentry>

<varlistentry>
  <term>CSS</term>
   <listitem><para>In case a CSS file different from the default Blend CSS is
   wanted for a specific Blend a (relative) path to this file can be specified.</para>
   </listitem>
</varlistentry>

</variablelist>
</para>

</sect2>

  <sect2 id="ddtp">
  <title>Debian Description Translation Project</title>

<para>
The <ulink url="http://ddtp.debian.net/">Debian Description
Translation Project</ulink> (see <xref linkend="documentation"/> ) provides users of
non-english languages with information about Debian packages.  The
sense of supporting especially the translations of descriptions which
are in the focus of a Blend is to make the Blend even more usable for our
target users.  Moreover people interested in the special field of the
Blend are most probably able to provide good translations if it comes to
texts that are specific to their field of knowledge.  Thus there is a
web page automatically created that parses the tasks packages for
package names and verifies the translation status of the package
descriptions.
</para>
<para>
Finally the DDTP descriptions are used to create internationalised
pages of existing packages which might help users with insufficient
skills in English to easily find their software of interest.  If the
browser locale is properly set the user will get translated
descriptions of existing packages - provided that the DDTP
translations for all these packages are existing.
</para>

  </sect2>

  <sect2>
  <title>Features of the web sentinel tasks pages</title>
<para>
 For so called prospective packages - packages which are not yet in
 Debian as discussed above - only the information given explicitly in
 the tasks file can be provided.  For official packages the Debian
 infrastructure provides a lot of metadata, that is collected in the
 Ultimate Debian Database (UDD).  The script which is creating the web
 sentinel pages collects all this data from UDD and tries to provide
 the most comprehensive overview over a set of packages for a given
 task of a Blend.  The following list gives an overview over the
 metadata of packages belonging to the tasks of a Blend.
</para>
<para>

<variablelist>

<varlistentry>
  <term>Short and long Description</term>
   <listitem><para>If there is a DDTP translation the descriptions are translated.</para>
   </listitem>
</varlistentry>

<varlistentry>
  <term>Homepage</term>
   <listitem><para>The Homepage field is taken from
     the <filename>debian/control</filename> file.  If this information is
     missing for some package on the tasks page it might be a sign
     that the package is not properly maintained and deserves a
     wishlist bug report to add this information (at least for
     non-native Debian packages.</para>
   </listitem>
</varlistentry>

<varlistentry>
  <term>Maintainer / last  Uploader</term>
   <listitem><para>Both are provides as mailto-links.  If the latest Uploader is
     different from the Maintainer this information is given as well.
     This is specifically interesting for group maintained packages -
     actually a tendency in Blends to maintain packages as Blends team
     - where the maintainer is the Blends team and the Uploader is the
     name of the actual developer who uploaded the package.</para>
   </listitem>
</varlistentry>

<varlistentry>
  <term>Popularity contest</term>
   <listitem><para>The popularity contest database contains different values.
     The tasks page is presenting the most relevant of them: the
     number of people who really use this package regularly and the
     number of people who upgraded this package recently</para>
   </listitem>
</varlistentry>

<varlistentry>
  <term>Versions and architectures</term>
   <listitem><para>A button can be used to uncover the versions of this package
     in the Debian package pool as well as the architectures for which
     this version exists.  The button is coloures in yellow if there
     is a new upstream version available which enables the Blends
     packaging team to easily detect work items to do.</para>
   </listitem>
</varlistentry>

</variablelist>
</para>
  </sect2>
  </sect1>

   <sect1 id="bugs">
  <title>Bugs overview</title>
<para>
The goal of a Blend is to support their user as best as possible.  So a
feature to have a quick overview about all packages in our focus might
be helpful.  This is solved by the bugs overview page.  To create this
page the <filename>tasks</filename> files are parsed for the listed
dependencies.  Then the Debian Bug Tracking System is consulted about
known bugs of these packages.  All bugs are listed and marked with
different colours according to their severity.  So the developers can
easily check this page in case they plan to fix some bugs that are
relevant for the Blend.
</para>
<para>
If you want to see examples for those bugs pages just have a look at the
<ulink url="http://blends.debian.org/">list of all Blends</ulink>
using this technique and follow the links to the bugs pages once you
selected one specific Blend.
</para>

   </sect1>

   <sect1 id="thermometer">
  <title>Versions in stable / testing / unstable / new / VCS upstream</title>
<para>
The Debian GIS team has named this overview "Thermometer" - just find
the Debian GIS thermometer as example view
<ulink url="http://blends.debian.org/gis/thermometer/">here</ulink>.
</para>
  </sect1>

<!-- PET is currently not installed for Debian Med - PET maintainer is pinged
FIXME: PET gives a recent overview about the current development
activities of the Blend developers.
-->

  <sect1 id="qareport">
   <title>Quality assurance report</title>

<para>
The Debian Quality Assurance group does a decent job in watching the
status o f Debian packages.  If a package features a
valid <filename>debian/watch</filename> the tool <package>uscan</package> is able to
verify the upstream source location for newer versions.  The QA report
page reports issues about the packages that are relevant for a Blend.
</para>
  </sect1>

</chapter>
