[Blends-commit] [SCM] blends-gsoc branch, master, updated. cf47b2e2e3a2c1b046e506a32605494af03d92f1
Emmanouil Kiagias
e.kiagias at gmail.com
Mon Sep 23 18:43:08 UTC 2013
The following commit has been merged in the master branch:
commit cf47b2e2e3a2c1b046e506a32605494af03d92f1
Author: Emmanouil Kiagias <e.kiagias at gmail.com>
Date: Mon Sep 23 20:42:54 2013 +0200
added doc/en/08_websentinel.xml converted documentation, remember the TODOs comments in the end of the page
diff --git a/doc/debian-blends.en.xml b/doc/debian-blends.en.xml
index c7ebaf2..d38c806 100644
--- a/doc/debian-blends.en.xml
+++ b/doc/debian-blends.en.xml
@@ -11,6 +11,7 @@
<!ENTITY ch-inside SYSTEM "en/05_inside.xml">
<!-- <!ENTITY ch-technology SYSTEM "en/06_technology.xml"> -->
<!ENTITY ch-starting SYSTEM "en/07_starting.xml">
+ <!ENTITY ch-websentinel SYSTEM "en/08_websentinel.xml">
]>
@@ -25,5 +26,6 @@
&ch-inside;
<!-- &ch-technology; -->
&ch-starting;
+ &ch-websentinel;
</book>
\ No newline at end of file
diff --git a/doc/en/08_websentinel.xml b/doc/en/08_websentinel.xml
new file mode 100644
index 0000000..81df61d
--- /dev/null
+++ b/doc/en/08_websentinel.xml
@@ -0,0 +1,492 @@
+<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.alioth.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 controling 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 SVN 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 SVN repositories) the Blends SVN at
+<informalexample>
+ <programlisting>
+ svn://svn.debian.org/svn/blends/projects/BLEND/trunk/SRCPKG/tasks
+ </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 builded 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-Svn</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 SVN.
+ </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-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-Svn</filename> or <filename>Vcs-Git</filename>
+ there is no need to set <filename>Vcs-Browser</filename> explicitely
+ 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>
+
+<varlistentry>
+ <term>Published-* (deprecated)</term>
+ <listitem>
+ <para>These tags were previouosely used to specify scientific
+ publications. Its use is now deprecated and you rather
+ should use the file <filename>debian/upstream</filename> as documented in
+ <ulink url="http://wiki.debian.org/UpstreamMetadata">Debian
+ Wiki</ulink>. The <filename>debian/upstream</filename> files will be gathered
+ in their state in SVN - so changes become effective after some
+ delay caused by cron jobs. This new way to handle publications
+ prevents code duplication and can be used more flexible by single
+ maintainers and is also useful for other purposes than only for
+ Blends sentinel.
+ </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://svn.debian.org/wsvn/blends/blends/trunk/webtools/webconf/"
+ >maintained in SVN</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>AliothUrl</term>
+ <listitem><para>URL of the Alioth project of the Blend (might be identical to
+ ProjectUrl)</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 Alioth and usually stored
+ at <filename>/var/lib/gforge/chroot/home/groups/blends/htdocs/<ProjectName></filename>
+ </para>
+ </listitem>
+</varlistentry>
+
+<varlistentry>
+ <term>DataDir</term>
+ <listitem><para>Directory where the rendering code stores temporary data like
+ SVN checkout of tasks files etc. This is usually set to
+ <filename>/var/lib/gforge/chroot/home/groups/blends/data/<ProjectName></filename>
+ </para>
+ </listitem>
+</varlistentry>
+
+<varlistentry>
+ <term>VcsDir</term>
+ <listitem><para>Path to tasks files in Blends SVN
+ <filename>/svn/blends/projects/science/trunk/<ProjectName></filename>
+ </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 explicitely 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.alioth.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="svnoverview">
+ <title>SVN overview</title>
+<para>
+This page gives a recent overview about the current development
+activities of the Blend developers.
+</para>
+ </sect1>
+
+ <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>
+
+<!--
+
+line 479: package tag was prgn
+comment out xref elements
+
+ -->
\ No newline at end of file
--
Git repository for blends-gsoc code
More information about the Blends-commit
mailing list