From: hertzog <hertzog@313b444b-1b9f-4f58-a734-7bb04f332e8d>
Date: Fri, 24 May 2002 00:17:13 +0000 (+0000)
Subject: - Completed Sec "Voting"
X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=commitdiff_plain;h=bff57a3ec4531ee535261d0b5ee1d503fa5ad9ad;p=developers-reference.git

- Completed Sec "Voting"
- Completed Sec "Documentation"
- Added Sec "IRC channels" in the Resources chapter.
- Added Sec "pbuilder" in the appendix. Mention it in the
  being kind to porter too.
- Extended the explanation about devscripts.
- Completed Sec "Helper scripts"


git-svn-id: svn://anonscm.debian.org/ddp/manuals/trunk/developers-reference@1698 313b444b-1b9f-4f58-a734-7bb04f332e8d
---

diff --git a/common.ent b/common.ent
index 2d4e4cd..f96759e 100644
--- a/common.ent
+++ b/common.ent
@@ -42,6 +42,7 @@
 <!-- deprecate, this is dead
   <!entity url-pkg-manual "http://&www-debian-org;/doc/packaging-manuals/packaging.html/"> -->
 <!entity url-social-contract "http://&www-debian-org;/social_contract">
+<!entity url-constitution "http://&www-debian-org;/devel/constitution">
 <!entity url-dfsg "&url-social-contract;#guidelines">
 <!entity url-debian-lists-subscribe "http://&www-debian-org;/MailingLists/subscribe">
 <!entity url-debian-lists "ftp://&ftp-debian-org;/debian/doc/mailing-lists.txt">
@@ -87,6 +88,8 @@
 
 <!entity url-sponsors "http://www.internatif.org/bortzmeyer/debian/sponsor/">
 
+<!entity url-rules-files "http://people.debian.org/~srivasta/rules">
+
 <!-- 
      URLs, non-debian
   -->
@@ -96,6 +99,7 @@
 <!entity url-rfc2440 "http://www.gnupg.org/rfc2440.html">
 <!entity url-u.s.-export "http://www.bxa.doc.gov/Encryption/PubAvailEncSourceCodeNofify.html">
 <!entity url-notification-of-export "http://www.bxa.doc.gov/Encryption/">
+<!entity url-openprojects "http://www.openprojects.net">
 
 <!-- Debian email addresses -->
 <!entity email-listmaster "<email>listmaster@&lists-host;</email>">
@@ -113,6 +117,7 @@
 <!entity email-debian-qa "<email>debian-qa@&lists-host;</email>">
 <!entity email-debian-release "<email>debian-release@&lists-host;</email>">
 <!entity email-debian-email "<email>debian-email@&lists-host;</email>">
+<!entity email-debian-vote "<email>debian-vote@&lists-host;</email>">
 
 <!entity email-new-maintainer "<email>new-maintainer@debian.org</email>">
 <!entity email-debian-keyring "<email>keyring-maint@debian.org</email>">
@@ -127,6 +132,8 @@
 <!entity file-bts-mailing "<file>/usr/share/doc/debian/bug-log-mailserver.txt</file>">
 <!entity file-bts-info "<file>/usr/share/doc/debian/bug-maint-info.txt</file>">
 <!entity file-bts-docs "<file>/usr/share/doc/debian/bug-*</file>">
+<!entity file-debian-private-archive "~debian/archive/debian-private/">
+
 <!entity cron-bug-report '0 17 * * fri   echo "index maint <var>address</var>" | mail request@bugs.debian.org'>
 
 <!entity control-file-fields "<list compact>
diff --git a/debian/changelog b/debian/changelog
index 80c4e92..463858a 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -92,6 +92,13 @@ developers-reference (3.0) unstable; urgency=low
     - New Section "Managing sponsored packages" contributed by
       Francesco Paolo Lovergine. Slightly updated by myself.
     - Completed Sec "Bug housekeeping". closes: #39519
+    - Completed Sec "Voting"
+    - Completed Sec "Documentation"
+    - Added Sec "IRC channels" in the Resources chapter.
+    - Added Sec "pbuilder" in the appendix. Mention it in the section
+      "Being kind to porter" too.
+    - Extended Sec "devscripts" with info about "bts" and "uscan".
+    - Completed Sec "Helper scripts".
 
   * Antoine Hulin:
     - update French translation
diff --git a/developers-reference.sgml b/developers-reference.sgml
index e1f8ea1..e794654 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.107 $">
+  <!entity cvs-rev "$Revision: 1.108 $">
   <!-- if you are translating this document, please notate the CVS
        revision of the developers reference here -->
   <!--
@@ -305,7 +305,20 @@ the documentation of the <package>debian-keyring</package> package.
 
        <sect id="voting">Voting
 	<p>
-&FIXME;<url id="url-vote">
+Even if Debian is not always a real democracy, Debian has democratic
+tools and uses a democratic process to elect its leader or
+to approve a general resolution. Those processes are described in
+the <url id="&url-constitution;" name="Debian Constitution">.
+	<p>
+Democratic processes work well only if everybody take part in the
+vote, that's why you have to vote. To be able to vote you have to
+subscribe to &email-debian-devel-announce; since call for votes are sent
+there. If you want to follow the debate preceding a vote, you
+may want to subscribe to &email-debian-vote;.
+	<p>
+The list of all the proposals (past and current) is available on the
+web at <url id="url-vote">. You will find there additionnal information
+about how to make a vote proposal.
 
 
       <sect id="inform-vacation">Going on vacation gracefully
@@ -382,7 +395,7 @@ Send an email about how you are leaving the project to
 	    <item>
 Notify the Debian key ring maintainers that you are leaving by
 emailing to &email-debian-keyring;.
-	  </enumlist>
+</enumlist>
 
 
 
@@ -441,13 +454,44 @@ posting messages.
 Online archives of mailing lists are available at <url
 id="&url-lists-archives;">.
 
+      <sect id="irc-channels">IRC channels
+	<p>
+Several IRC channels are dedicated to Debian's development. They are all
+hosted on the <url id="&url-openprojects;" name="OpenProjects"> network.
+The <tt>irc.debian.org</tt> DNS entry is just an alias to
+<tt>irc.openprojects.net</tt>.
+	<p>
+The main channel <em>#debian-devel</em> is very active since more
+than 150 persons are always logged in. It's a channel for people who work
+on Debian, it's not a support channel (there's <em>#debian</em> for that).
+It is however open to anyone who wants to lurk (and learn). Its topic is
+always full of interesting informations. Since it's an open channel, you
+should not speak there of issues that are discussed in
+&email-debian-private;. There's a key protected channel
+<em>#debian-private</em> for that purpose. The key is available 
+in the archives of debian-private in <file>&master-host;:&file-debian-private-archive;</file>, just <prgn>zgrep</prgn> for <em>#debian-private</em> in
+all the files.
+	<p>
+There are other additionnal channels dedicated to specific subjects.
+<em>#debian-bugs</em> is used for coordinating bug squash parties.
+<em>#debian-boot</em> is used to coordinate the work on the boot
+floppies (i.e. the installer). <em>#debian-doc</em> is
+occasionnaly used to work on documentation like the one you are
+reading. Other channels are dedicated to an architecture or a set of
+packages : <em>#debian-bsd</em>, <em>#debian-kde</em>,
+<em>#debian-sf</em> (SourceForge package), <em>#debian-oo</em> (OpenOffice
+package) ...
+	<p>
+Some non-english channels exist, for example <em>#debian-devel-fr</em> for
+french speaking people interested in Debian's development.
 
 
       <sect id="doc-rsrcs">Documentation
 	<p>
-&FIXME; <url id="&url-devel-docs;">
-
-
+This document contains many informations very useful to Debian developers,
+but it can not contain everything. Most of the other interesting documents
+are linked from <url id="&url-devel-docs;" name="The Developers' Corner">.
+Take the time to browse all the links, you will learn many more things.
 
       <sect id="server-machines">Debian servers
 	<p>
@@ -1985,7 +2029,9 @@ environment.  Within that chrooted environment, install the
 <package>build-essential</package> package and any package
 dependencies mentioned in <tt>Build-Depends</tt> and/or
 <tt>Build-Depends-Indep</tt>.  Finally, try building your package
-within that chrooted environment.
+within that chrooted environment.  These steps can be automated
+by the use of the <prgn>pbuilder</prgn> program which is provided by
+the package of the same name.
 		<p>
 See the <url id="&url-debian-policy;" name="Debian Policy
 Manual"> for instructions on setting build dependencies.
@@ -2528,10 +2574,26 @@ even better.
 
 	<sect1 id="helper-scripts">Helper scripts
 	<p>
-	&FIXME; debhelper best, debmake obsolete, yada exists. Custom
-	rules files are ok too: http://people.debian.org/~srivasta/rules
-	Tools are great but you still have to understand what they do
-	=> read their documentation.
+To help you in your packaging effort, you can use helper scripts.
+The best scripts available are provided by <package>debhelper</package>.
+With <prgn>dh_make</prgn> (package <package>dh-make</package>), you can
+generate in a few seconds a package that is mostly ready. However that
+apparent simplicity is hiding many things done by the helper scripts.
+You have to know what is done by them, that's why you are strongly
+encouraged to read the corresponding manual pages, starting with
+<tt>debhelper(1)</tt>. That's required because you'll have to
+understand what is going on to be able to use them wisely and to
+fix bugs in a pretty way.
+	<p>
+debhelper is very useful because it lets you follow the latest Debian policy
+without doing many modifications since the changes that can be automated are
+almost always automatically done by a debhelper script. Furthermore it
+offers enough flexibility to be able to use it in conjunction with
+some hand crafted shell invocations within the <file>rules</file> file.
+	<p>
+You can however decide to not use any helper script, and still write
+some very good <file>rules</file> file. Many examples are available
+at <url id="&url-rules-files;">.
 
 	<sect1 id="pkg-mgmt-cvs">Managing a package with CVS
 	<p>
@@ -2999,16 +3061,29 @@ depends.  Or, you can test how your package behaves when installed
 into a bare base system.
 
 
+      <sect id="pbuilder">
+        <heading><package>pbuilder</package>
+        <p>
+<package>pbuilder</package> constructs a chrooted system, and builds
+a package inside the chroot. It is very useful to check that
+a package's build-dependencies are correct, and to be sure that
+unnecessary and wrong build dependencies will not exist in the
+resulting package. 
+
+
       <sect id="devscripts">
 	<heading><package>devscripts</package>
 	<p>
 <package>devscripts</package> is a package containing a few wrappers
-and tools which you may find helpful for maintaining your Debian
+and tools which are very helpful for maintaining your Debian
 packages.  Example scripts include <prgn>debchange</prgn> and
 <prgn>dch</prgn>, which manipulate your <file>debian/changelog</file>
 file from the command-line, and <prgn>debuild</prgn>, which is a
-wrapper around <prgn>dpkg-buildpackage</prgn>.
-
+wrapper around <prgn>dpkg-buildpackage</prgn>. The <prgn>bts</prgn>
+utility is also very helpful to update the state of bug reports on the
+command line, as is <prgn>uscan</prgn> to watch for new upstream
+versions of your packages. Check the <tt>devscripts(1)</tt> manual
+page for a complete list of available scripts.
 
 
       <sect id="dpkg-dev-el">
@@ -3036,7 +3111,7 @@ thing).
   alien
   dpkg-repack
   grep-dctrl
-  pbuilder -->
+-->
 
 
   </book>