Rework the maintainer's page completely to give the big picture

debexpo/templates/index/intro-maintainers.mako

@@ -3,38 +3,66 @@
 
 ${ c.custom_html }
 
-<h1>Introduction for maintainers</h1>
-
-<h2>Welcome to ${ c.config['debexpo.sitetitle'] }</h2>
+<h1>Introduction for maintainers: How will my package get into Debian</h1>
 
 <p>We are glad that you found your way to our web site. Honestly the whole web site is just there to get your work into Debian. Your contribution is appreciated and it would be a pity if you did not find a sponsor to upload your packages. Read on to see in what ways we will be helping you find a sponsor.</p>
 
+<h2>1. Find a requested package</h2>
+
+<p>Debian is a distribution, not a general purpose repository. Many of us do not believe <em>every</em> piece of free software necessarily belongs to Debian. Please do not treat Debian as platform to advertise your own software, unless there is some <em>real</em> request for it. That said, there is no one who ultimately judges about that. Eventually you may get some feedback on that discussion after filing your WNPP bug (see below), however you are free to interpret that as suggestion, not as final vote. After all, you need to find a sponsor believing in the benefit of having your package in Debian, though. Please have a look to our ${ h.tags.link_to("sponsors page", h.url(controller='sponsor', action='index')) } to learn about personal interests of sponors.
+
+<p>If you want to contribute to Debian, but you do not know which package Debian misses yet, have a look to "Request for package" (<em>RFP</em>) bugs. See WNPP below.</p>
+
+<h2>2. File a WNPP bug</h2>
+
+<p><a href="http://www.debian.org/devel/wnpp/">Work-Needing and Prospective Packages</a> <em>WNPP</em> is our system of announcing your intent to markup packages being worked on. In particular its a bug against the <a href="http://bugs.debian.org/cgi-bin/pkgreport.cgi?pkg=wnpp">WNPP pseudo package</a> (<a href="http://wnpp.debian.net/">or use a nice frontend</a> to browse WNPP bugs). If you want to package something for Debian, the very first step should be to file an "Intent to package" (<em>ITP</em>) bug against <em>WNPP</em>. You may want to use the <tt><a href="http://packages.debian.org/squeeze/reportbug">reportbug</a></tt> tool to achieve that, by selecting "<em>wnpp</em>" as package to report a bug to.</p>
+
+<h2>3. Make the package</h2>
 
-<h3>How will my package get into Debian?</h3>
+<p>Debian packages must comply to several normative requirements and guidelines. We can't give you exhaustive instructions how to build packages here. In short, we expect you to provide a <em>source package</em> complying to the Debian policy at least (see below). Please have a look to those excellent resources:</p>
 
-<p>This web site is a public package repository of source packages. You can upload your package to this server (through special tools like 'dupload' or 'dput') and after a few checks it will be stored in our repository. ${ h.tags.link_to("Interested sponsors", h.url(controller='sponsor', action='index')) } can then download the package and upload it to Debian. So the basic procedure is:</p>
+    <dl>
+        <dt><a href="http://www.debian.org/doc/debian-policy/">The Debian Policy Manual</a></dt>
+        <dd>A must read resource to learn about technical specification and technical requirements of Debian packages.</dd>
+        <dt><a href="http://www.debian.org/doc/manuals/maint-guide/">New Maintainer's Guide</a></dt>
+        <dd>A must read resource to learn basics of Debian source packages</dd>
+        <dt><a href="http://anonscm.debian.org/gitweb/?p=collab-maint/packaging-tutorial.git;a=blob_plain;f=packaging-tutorial.pdf;hb=8d4e3da6e828af7b3ccaf3bee0c25401958bd700">Lucas Nussbaum's packaging tutorial</a></dt>
+        <dd>A quick introduction to Debian packaging</dd>
+        <dt><a href="http://www.debian.org/doc/manuals/developers-reference/index.html">Developer's Reference</a></dt>
+        <dd>A comprehensive manual describing typical workflows and best practices related to Debian packages</dd>
+        <dt><a href="http://wiki.debian.org/DebianMentorsFaq">Debian Mentors FAQ</a> (Debian Wiki)</dt>
+        <dd>Another valuable resource to learn about common terms and workflows related to Debian</dd>
+    </dl>
 
-<ol>
+
+<h2>4. Publish your package</h2>
+
+<p>This web site is a public package repository of source packages. You can upload your package to this server (through special tools like '<tt><a href="http://packages.debian.org/squeeze/dupload">dupload</a></tt>' or '<tt><a href="http://packages.debian.org/squeeze/dput">dput</a></tt>') and after a few checks it will be stored in our repository. ${ h.tags.link_to("Interested sponsors", h.url(controller='sponsor', action='index')) } can then download the package and upload it to Debian.</p>
+
+<h3>Using ${ c.config['debexpo.sitetitle'] }</h3>
+
+<ul>
     <li><strong>${ h.tags.link_to("Sign up for an account", h.url(controller='register', action='register')) }</strong>. Getting an account on this server is an automatic process and will just take a moment. We require registration so we have a valid email address where sponsors can reach you.</li>
     <li><strong>Upload your package</strong> to <tt>mentors.debian.net</tt>. You do not need to put your packages into any other web space on the Internet. Everybody will be able to download your package using either the web browser, the '<tt>dget</tt>' tools or even through a simple run of <tt>apt-get source ....</tt></li>
     <li>Have a look to your ${ h.tags.link_to("personal package page", h.url(controller='package', action='my')) }. Your uploaded package should <strong>show up there</strong>. From there you can toggle several settings and retrieve the RFS (request-for-sponsorship) template</li>
     <li>Your package is on display on the main page of ${ c.config['debexpo.sitetitle'] }, if you enable the "<i>Needs a Sponsor</i>" button, so interested sponsors will see it and hopefully check it out.</li>
     <li>You will be shown a <strong>RFS (request-for-sponsorship) template</strong> that you should send to the debian-mentors mailing list to draw attention to your package.</li>
-    <li>Your package will hopefully be reviewed by a sponsor and either acknowledge your work and <strong>upload your package to Debian</strong>, or ask you to address some problems.</li>
-</ol>
-
-<h3>How to make a package?</h3>
-
-<p>Have a look to our ${ h.tags.link_to("QA section", h.url(controller='index', action='qa')) }.</p>
+</ul>
 
-<h3>How to upload packages?</h3>
+<h3>How to upload packages to <tt>${ config['debexpo.sitename'] }?</tt></h3>
 
 <p>You need to use <a href="http://packages.debian.org/dput"><tt>dput</tt></a> to upload packages. We accept your uploads through <em>HTTP</em> or <em>FTP</em>. If you are using <em>FTP</em> your package <strong>must</strong> be signed with the GnuPG key you configured in your control panel. </p>
 
-<h4>HTTP uploads</h4>
-% if c.logged_in:
+<table>
+    <tr>
+        <td width="50%">HTTP uploads</td>
+        <td width="50%">FTP uploads</td>
+    </tr>
+    <tr>
+        <td>
+        % if c.logged_in:
 
-<p>See your ${ h.tags.link_to("account page", h.url('my')) } to see how to configure <tt>dput</tt> to use HTTP, or put the following content to your <tt>~/.dput.cf</tt> file:</p>
+            <p>See your ${ h.tags.link_to("account page", h.url('my')) } to see how to configure <tt>dput</tt> to use HTTP, or put the following content to your <tt>~/.dput.cf</tt> file:</p>
 
 <pre>
 [mentors]
@@ -44,15 +72,16 @@ method = http
 allow_unsigned_uploads = 0
 progress_indicator = 2
 </pre>
-% else:
-
-<p>You need to configure <tt>dput</tt>. Please ${ h.tags.link_to("login", h.url(controller='login', action='index')) } to see your personal <tt>~/.dput.cf</tt> here.</p>
 
-% endif
+<strong>Please keep this configuration private</strong>.
+        % else:
 
-<h4>FTP uploads</h4>
+        <p>You need to configure <tt>dput</tt>. Please ${ h.tags.link_to("login", h.url(controller='login', action='index')) } to see your personal <tt>~/.dput.cf</tt> here.</p>
 
-<p>You can use <em>FTP</em> to upload packages to ${ c.config['debexpo.sitetitle'] }. If you prefer that method make sure you sign your uploads with your GPG key! This is the corresponding <tt>~/.dput.cf</tt> file:</p>
+        % endif
+        </td>
+        <td>
+            <p>You can use <em>FTP</em> to upload packages to ${ c.config['debexpo.sitetitle'] }. If you prefer that method make sure you sign your uploads with your GPG key! This is the corresponding <tt>~/.dput.cf</tt> file:</p>
 
 <pre>
 [mentors-ftp]
@@ -65,6 +94,9 @@ method = ftp
 allow_unsigned_uploads = 0
 
 </pre>
+        </td>
+    </tr>
+</table>
 
 <p>Once you have it set up, you can run it from your shell like this:</p>
 
@@ -72,9 +104,17 @@ allow_unsigned_uploads = 0
 $ dput mentors your_sourcepackage_1.0.changes
 </pre>
 
-<h3>Will my name stay visible on the package?</h3>
+If you did everything right, you will get a confirmation mail from our site, and you can start seeking a sponsor for your package.
+
+<h2>5. Find a sponsor</h2>
+
+<p>Once your package is publicly available on any resource, including but not limited to ${ c.config['debexpo.sitetitle'] } you may start searching a sponsor for your package. If you uploaded packages to Debian already, you should ask your former sponsor. A sponsor is any <a href="http://wiki.debian.org/DebianDeveloper">Debian Developer</a> willing to upload your package to Debian on your behalf. Have a look to our ${ h.tags.link_to("sponsor's page", h.url(controller='sponsor', action='index')) } to learn more on sponsors and how you find one.</p>
+
+<p>The main point of the sponsor process is to review your package to make sure it meets our technical requirements. Everyone can and should review other people's packages. Also, a clean package will increase your likelihood to find a sponsor. Please have a look to our page ${ h.tags.link_to("telling more about reviews", h.url('intro-reviewers')) }.</p>
 
-<p>Yes. The Debian project appreciates the work you do. So you will be named as the official maintainer of the package in Debian. You will even get the bug reports if people discover problems in your package. Besides from not being able to upload the package directly into Debian you are treated as a full member of the community.</p>
+<h3>The relation between you and your sponsor</h3>
+
+<p>A sponsor is not technically responsible for your package. <strong>You</strong> will be listed as official maintainer of the package in Debian. You will even get the bug reports if people discover problems in your package. Besides from not being able to upload the package directly into Debian you are treated as a full member of the community. The Debian project appreciates the work you do.</p>
 
 <h3>What can I do if I don't find a sponsor?</h3>
 
@@ -84,3 +124,13 @@ $ dput mentors your_sourcepackage_1.0.changes
     <li>Ask again on the debian-mentors mailing list. Its common practice to ask again after a few weeks.</li>
     <li>Offer your package directly to developers. We made a ${ h.tags.link_to("a list of sponsors", h.url(controller='sponsor', action='index')) }, eventually willing to upload packages for you. <em>Please don't contact every sponsor listed there. Instead, read their individual requirements and choose the sponsor which matches you and your package best</em>.
 </ul>
+
+<h2>6. Getting an upload to Debian</h2>
+
+<p>Once you found a sponsor interested in your package, he will <em>sponsor</em> it, that means build it and successively upload it to Debian. You will get notified by <em>dak</em> - the software used by Debian to manage its repositories - by the upload. Please note, if your package was not at all in Debian before, it needs manual approval by <a href="http://ftp-master.debian.org/">ftpmasters</a> to clear the <a href="http://ftp-master.debian.org/new.html">NEW queue</a>. They will do consistency checks, and check your <tt>debian/copyright</tt> file whether your package matches the <a href="http://www.debian.org/social_contract#guidelines">Debian Free Software Guidelines</a>. ftpmaster's opinion is binding here for both of you, you and your sponsor.</p>
+
+<h2>7. Maintaining your package in Debian</h2>
+
+<p>Please see the corresponding chapter in the <a href="http://www.debian.org/doc/manuals/maint-guide/update.en.html">New Maintainer's Guide</a> to get the idea. Whenever you feel like, you should update your package in Debian. The general procedure isn't different to your fist upload. Please upload your updated package to ${ config['debexpo.sitename'] } and poke your former sponsor about your change. Alternatively, follow ${ h.tags.link_to("the usual procedures", h.url(controller='sponsor', action='index')) }.</p>
+
+<p>If your package passes through the sponsoring process for <em>a few</em> packages without any notable correction by your sponsor, you can become a <a href="http://wiki.debian.org/DebianMaintainer">Debian Maintainer</a> which grants you limited upload rights to Debian directly. Get in touch with your sponsor to discuss your chances here. You can also <a href="http://www.debian.org/devel/join/">become a Debian Developer</a> giving you all necessary upload rights.</p>

debexpo/templates/sponsor/index.mako

@@ -4,7 +4,7 @@ ${ c.custom_html }
 
 <h1>The sponsoring process</h1>
 
-As sponsored maintainer you don't have upload permissions to the Debian repository. Therefore you have three possibilities to get your package into Debian:
+<p>As sponsored maintainer you don't have upload permissions to the Debian repository. Therefore you have three possibilities to get your package into Debian:</p>
 
 <ul>
     <li>Join a packaging team</li>
@@ -12,6 +12,8 @@ As sponsored maintainer you don't have upload permissions to the Debian reposito
     <li>Talk directly to people willing to sponsor your package</li>
 </ul>
 
+<p>They will ${ h.tags.link_to("review", h.url('intro-reviewers')) } your package. Everyone is invited to review packages, including you for other people in your situation.</p>
+
 <h2>Join a packaging team</h2>
 
 <p>There are teams in Debian who maintain packages collaboratively. If your package deals with libraries for programming langauges, or is about an ecosystem of associated packages, think of KDE or Gnome packages for example, you may want to join that team. Have a look to <a href="http://wiki.debian.org/Teams/#Packaging_teams">list of packaging teams</a> in Debian.</p>
@@ -22,6 +24,8 @@ As sponsored maintainer you don't have upload permissions to the Debian reposito
 
 <p>If your package does not match the interests of any team, or you are not sure whether a team could be interested in your package, please write to the <tt><a href="http://lists.debian.org/debian-mentors/">debian-mentors</a></tt> mailing list to draw attention to your package. Your request should be formatted according to our RFS ("<em>request for sponsorship</em>") template. If you uploaded your package to ${ config['debexpo.sitename'] }, a RFS template can be shown on your package page.</p>
 
+<p><em>If in doubt, choose this alternative.</em></p>
+
 <p>Don't worry if you get no answer: It does not mean your package is bad. Ask again after a few weeks if you did not find a sponsor by other means yet. </p>
 
 <h2>Finding a sponsor</h2>