From 491b29a243ffc0be9f99bb12ac22c65ada8f96c4 Mon Sep 17 00:00:00 2001
From: hertzog <hertzog@313b444b-1b9f-4f58-a734-7bb04f332e8d>
Date: Sat, 24 May 2003 20:25:21 +0000
Subject: [PATCH] - Documented how to add custom content to the PTS.

git-svn-id: svn://anonscm.debian.org/ddp/manuals/trunk/developers-reference@2312 313b444b-1b9f-4f58-a734-7bb04f332e8d
---
 debian/changelog          |  1 +
 developers-reference.sgml | 68 +++++++++++++++++++++++++++++++++++++--
 2 files changed, 67 insertions(+), 2 deletions(-)

diff --git a/debian/changelog b/debian/changelog
index 5b62c33..d514d6f 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -5,6 +5,7 @@ developers-reference (3.3.3) unstable; urgency=low
   * Raphaël Hertzog
     - Updated documentation concerning the PTS
     - Added a paragraph about the PTS web interface
+    - Documented how to add custom news item in the PTS
 
  -- Adam Di Carlo <aph@debian.org>  Fri,  2 May 2003 00:57:24 +0200
 
diff --git a/developers-reference.sgml b/developers-reference.sgml
index a89556f..ea0d883 100644
--- a/developers-reference.sgml
+++ b/developers-reference.sgml
@@ -6,7 +6,7 @@
   <!entity % commondata  SYSTEM "common.ent" > %commondata;
 
   <!-- CVS revision of this document -->
-  <!entity cvs-rev "$Revision: 1.198 $">
+  <!entity cvs-rev "$Revision: 1.199 $">
   <!-- if you are translating this document, please notate the CVS
        revision of the developers reference here -->
   <!--
@@ -32,7 +32,7 @@
 	<copyrightsummary>
 copyright &copy; 1998&mdash;2003 Adam Di Carlo</copyrightsummary>
 	<copyrightsummary>
-copyright &copy; 2002 Raphaël Hertzog</copyrightsummary>
+copyright &copy; 2002&mdash;2003 Raphaël Hertzog</copyrightsummary>
 	<copyrightsummary>
 copyright &copy; 1997, 1998 Christian Schwarz</copyrightsummary>
 	<p>
@@ -1392,7 +1392,71 @@ the mail service offered by the PTS.
 You can jump directly to the web page concerning a specific source package
 with an url like <tt>http://&pts-host;/<var>srcpackage</var></tt>. Otherwise
 you can go through the <url id="http://&pts-host;" name="main page">.
+	<p>
+This web interface has been designed like a portal for the development of
+packages: you can add custom content on the pages of your packages. You can
+add "static information" (news item that are meant to stay available
+indefinitely) and news items in the "latest news" section.
+	<p>
+Static news can be used to indicate:
+<list>
+<item>the availability of a project hosted on alioth.debian.org for co-maintaining the package
+<item>a link to the upstream website
+<item>a link to the upstream bugtracker
+<item>the existence of an IRC channel dedicated to the software
+<item>any other available resource that could be useful in the maintenance of the package
+</list>
+Usual news item may be used to announce that:
+<list>
+<item>beta packages are available for test
+<item>final packages are expected for next week
+<item>the packaging is about to be redone from scratch
+<item>backports are available
+<item>the maintainer is on vacation (if he wishes to publish this information)
+<item>a NMU is being worked on
+<item>something important will affect the package
+</list>
+	<p>
+Both kind of news are generated in a similar manner: you just have to send a mail
+either to <email>pts-static-news@qa.debian.org</email> or to
+<email>pts-news@qa.debian.org</email>. The mail should indicate which package is
+concerned by the news by giving the name of the source package in a
+<tt>X-PTS-Package</tt> mail header or in a <tt>Package</tt> pseudo-header (like the
+BTS reports). If an URL is available in the <tt>X-PTS-Url</tt> mail header or in
+the <tt>Url</tt> pseudo-header, then the result is a link to that URL instead
+of a complete news item.
+	<p>
+Some examples of valid mails used to generate news item in the PTS are following. The first one
+adds a link to the cvsweb interface of debian-cd in the "Static information" section.
+<example>
+From: Raphael Hertzog &lt;hertzog@debian.org&gt;
+To: pts-static-news@qa.debian.org
+Subject: Browse debian-cd CVS repository with cvsweb
+
+Package: debian-cd
+Url: http://cvs.debian.org/debian-cd/
+</example>
+The second one is an announce sent to a mailing list which is also sent
+to the PTS so that it is published on the PTS web page of the package. Note the
+use of the BCC field to avoid answers sent to the PTS by mistake ...
+<example>
+From: Raphael Hertzog &lt;hertzog@debian.org&gt;
+To: debian-gtk-gnome@lists.debian.org
+Bcc: pts-news@qa.debian.org
+Subject: Galeon 2.0 backported for woody
+X-PTS-Package: galeon
 
+Hello gnomers !
+
+I'm glad to announce that galeon has been backported for woody. You'll find
+everything here:
+...
+</example>
+	<p>
+Think twice before adding a news to the PTS because you won't be able to
+remove it later and you wan't be able to edit it either. The only thing that you
+can do is send a second news that will deprecate the information contained in
+the first news.
 
     <sect id="ddpo">Developer's packages overview
 	<p>
-- 
2.30.2