/[ddp]/manuals/trunk/maint-guide/maint-guide.en.dbk
ViewVC logotype

Diff of /manuals/trunk/maint-guide/maint-guide.en.dbk

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 8632 by osamu, Mon Apr 4 16:03:01 2011 UTC revision 8636 by osamu, Tue Apr 5 17:00:59 2011 UTC
# Line 55  exempla!</emphasis> (It's a long way by Line 55  exempla!</emphasis> (It's a long way by
55  examples!).  examples!).
56  </para>  </para>
57  <para>  <para>
58  This document has been updated for the Debian <literal>squeeze</literal>  This document has been updated for the Debian <literal>&base-release;</literal>
59  release.  <footnote><para> The document assumes you are using the  release.
60  <literal>squeeze</literal> system.  If you need to follow this text in the  <footnote><para> The document assumes you are using the
61  <literal>lenny</literal> system, you must install backported <systemitem role="package">dpkg</systemitem> and <systemitem role="package">debhelper</systemitem> packages, at least.  </para> </footnote>  <literal>&base-release;</literal> system or newer.  If you need to follow this
62    text in the older system (including the older Ubuntu system), you must install
63    backported <systemitem role="package">dpkg</systemitem> and <systemitem
64    role="package">debhelper</systemitem> packages, at least.  </para> </footnote>
65  </para>  </para>
66  <para>  <para>
67  One of the things that makes Debian such a top-notch distribution is its  One of the things that makes Debian such a top-notch distribution is its
# Line 80  help you create that first package, and Line 83  help you create that first package, and
83  next releases of that and maybe other packages later on.  next releases of that and maybe other packages later on.
84  </para>  </para>
85  <para>  <para>
86  Since this document is aimed at audiences who wish to handle program source  You must be familiar with <ulink url="&debref;">basic Debian system
87  codes from the shell prompt, proficiencies in  operations</ulink> before reading this document.
 <ulink url="&debref-tutorial;">generic Unix operations</ulink> and  
 <ulink url="&debref-program;">basic programing operations</ulink>  
 are prerequisite.  
88  </para>  </para>
89  <para>  <para>
90  If you need some help on packaging, please read <xref linkend="helpme"/> .  If you need some help on packaging, please read <xref linkend="helpme"/> .
91  </para>  </para>
92  <para>  <para>
93  Newer versions of this document should always be available online at <ulink url="&maint-guide;">&maint-guide;</ulink>  Newer versions of this document should always be available online at
94  and in the <systemitem role="package">maint-guide</systemitem> package.  <ulink url="&maint-guide;"/> and in the
95    <systemitem role="package">maint-guide</systemitem> package.
96  </para>  </para>
97  <para>  <para>
98  The translations may be available in packages such as <systemitem role="package">maint-guide-es</systemitem>.  The translations may be available in packages such as <systemitem role="package">maint-guide-es</systemitem>.
# Line 461  Please read the other manuals if you nee Line 462  Please read the other manuals if you nee
462  </section>  </section>
463  <section id="debiandeveloper"><title>Official Debian Developer</title>  <section id="debiandeveloper"><title>Official Debian Developer</title>
464  <para>  <para>
465  You can not become an official <emphasis role="strong">Debian  You can not become an official
466  Developer</emphasis> (DD) over night because it takes more than technical  <emphasis role="strong">Debian Developer</emphasis> (DD) over night because it
467  skill.  Please do not be discouraged by this.  If it is useful to others, you  takes more than technical skill.  Please do not be discouraged by this.  If it
468  can still upload your package either as a <emphasis role="strong">maintainer</emphasis> through a <emphasis role="strong">sponsor</emphasis> or as a <emphasis role="strong">Debian  is useful to others, you can still upload your package either as a
469  Maintainer</emphasis>.  See <ulink url="&nm-join;">Debian New  <emphasis role="strong">maintainer</emphasis> through a
470  Maintainers</ulink> and <ulink url="&debianmentorfaq;">Debian Mentors FAQ</ulink> for more.  <emphasis role="strong">sponsor</emphasis> or as a
471    <emphasis role="strong">Debian Maintainer</emphasis>.
472    </para>
473    <para>
474    See
475    <ulink url="&nm-do;">Debian New Maintainer site</ulink> and
476    <ulink url="&debianmentorfaq;">Debian Mentors FAQ</ulink> for more.
477  </para>  </para>
478  <para>  <para>
479  Please note that you do not need to create any new package to become an  Please note that you do not need to create any new package to become an
# Line 476  waiting for good maintainers (see <xref Line 483  waiting for good maintainers (see <xref
483  </para>  </para>
484  </section>  </section>
485  <section id="helpme"><title>Where to ask for help</title>  <section id="helpme"><title>Where to ask for help</title>
 <!--  
  /usr/share/doc/debian is used be doc-debian and debian-faq  
 -->  
486  <para>  <para>
487  Before you decide to ask your question in some public place, please read the fine documentation.  Before you decide to ask your question in some public place, please read the fine documentation.
488  </para>  </para>
# Line 491  files in <filename>/usr/share/doc/dpkg</ Line 495  files in <filename>/usr/share/doc/dpkg</
495  <listitem>  <listitem>
496  <para>  <para>
497  files in <filename>/usr/share/doc/debian</filename>  files in <filename>/usr/share/doc/debian</filename>
498    <!-- /usr/share/doc/debian is used be doc-debian and debian-faq -->
499  </para>  </para>
500  </listitem>  </listitem>
501  <listitem>  <listitem>
# Line 515  contents of "<literal><command>info</com Line 520  contents of "<literal><command>info</com
520  </listitem>  </listitem>
521  <listitem>  <listitem>
522  <para>  <para>
523  contents of <ulink url="&nm-do;">&nm-do;</ulink>  contents of <ulink url="&nm-do;">Debian New Maintainer site</ulink>
524  </para>  </para>
525  </listitem>  </listitem>
526  <listitem>  <listitem>
# Line 525  contents of <ulink url="&debianmentorfaq Line 530  contents of <ulink url="&debianmentorfaq
530  </listitem>  </listitem>
531  <listitem>  <listitem>
532  <para>  <para>
533  contents of <ulink url="&debian-mentors-ldo;">Debian Mentors Mailing List Archive</ulink>  contents of <ulink url="&debian-mentors-ldo;">debian-mentors@lists.debian.org mailing list archive</ulink>
534    </para>
535    </listitem>
536    <listitem>
537    <para>
538    contents of <ulink url="&debian-devel-ldo;">debian-devel@lists.debian.org mailing list archive</ulink>
539  </para>  </para>
540  </listitem>  </listitem>
541  </itemizedlist>  </itemizedlist>
542  <para>  <para>
543    Please consider to use web search engine effectively by including search string
544    such as "<literal>site:lists.debian.org</literal>" to limit the domain.
545    </para>
546    <para>
547  Making a small test package is good way to learn details of packaging.  Making a small test package is good way to learn details of packaging.
548  Inspecting existing well maintained packages is the best way to learn how other  Inspecting existing well maintained packages is the best way to learn how other
549  people make packages.  people make packages.
550  </para>  </para>
551  <para>  <para>
552  If you still have questions about packaging that you couldn't find answers to  If you still have questions about packaging that you couldn't find answers to
553  in the available documentation and web resources, you can ask them on the  in the available documentation and web resources, you can ask them interactively.
554  Debian Mentors' mailing list at <ulink url="&debian-mentors-ldo;">debian-mentors@lists.debian.org</ulink>  </para>
555  or at the <ulink url="&irc-debian;">IRC</ulink> such as <literal>#debian-mentors</literal>.  <itemizedlist>
556    <listitem>
557    <para>
558    <ulink url="&debian-mentors-ldo;">debian-mentors@lists.debian.org mailing list</ulink>. (This mailing list is for the novice.)
559    </para>
560    </listitem>
561    <listitem>
562    <para>
563    <ulink url="&debian-devel-ldo;">debian-devel@lists.debian.org mailing list</ulink>. (This mailing list is for the expert.)
564    </para>
565    </listitem>
566    <listitem>
567    <para>
568    <ulink url="&irc-debian;">IRC</ulink> such as <literal>#debian-mentors</literal>.
569    </para>
570    </listitem>
571    </itemizedlist>
572    <para>
573  The more experienced Debian developers will gladly help you, but do read at  The more experienced Debian developers will gladly help you, but do read at
574  least some of the documentation before asking a question!  least some of the documentation before asking a question!
575  </para>  </para>
576  <para>  <para>
577  When you receive a bug report (yes, actual bug reports!), you will know that it  When you receive a bug report (yes, actual bug reports!), you will know that it
578  is time for you to dig into the <ulink url="&bts;">Debian  is time for you to dig into the
579  Bug Tracking System</ulink> and read the documentation there, to be able to  <ulink url="&bts;">Debian Bug Tracking System</ulink>
580  deal with the reports efficiently.  I highly recommend reading the <ulink url="&devref-bug-handling;">Debian Developer's  and read the documentation there, to be able to
581  Reference, 5.8.  'Handling bugs'</ulink>.  deal with the reports efficiently.  I highly recommend reading the
582  </para>  <ulink url="&devref-bug-handling;">Debian Developer's Reference, 5.8.  'Handling bugs'</ulink>.
 <para>  
 If you still have questions, ask on the Debian Developers' mailing list at  
 <ulink url="&debian-devel-ldo;">debian-devel@lists.debian.org</ulink>.  
 See <ulink url="&debian-devel-ldo;">&debian-devel-ldo;</ulink>  
 for more information about this mailing list.  
583  </para>  </para>
584  <para>  <para>
585  Even if it all worked well, it's time to start praying.  Why?  Because in just  Even if it all worked well, it's time to start praying.  Why?  Because in just
# Line 577  Let's try to make your own package (or, Line 603  Let's try to make your own package (or,
603  <para>  <para>
604  You have probably chosen the package you want to create.  The first thing you  You have probably chosen the package you want to create.  The first thing you
605  need to do is check if the package is in the distribution archive already by  need to do is check if the package is in the distribution archive already by
606  using <command>aptitude</command>.  using the following.
 </para>  
 <para>  
 You can also check package information through <ulink url="&packages-do;">package search page</ulink> and  
 <ulink url="&packages-qa-do;">Debian Package  
 Tracking System</ulink>.  
607  </para>  </para>
608    <itemizedlist>
609    <listitem>
610    <para>the <command>aptitude</command> command</para>
611    </listitem>
612    <listitem>
613    <para><ulink url="&packages-do;">Debian packages</ulink> web page</para>
614    </listitem>
615    <listitem>
616    <para><ulink url="&packages-qa-do;">Debian Package Tracking System</ulink> web page</para>
617    </listitem>
618    </itemizedlist>
619  <para>  <para>
620  If the package already exists, well, install it!  :-) If it happens to be  If the package already exists, well, install it!  :-) If it happens to be
621  <emphasis role="strong">orphaned</emphasis> -- if its maintainer is set to  <emphasis role="strong">orphaned</emphasis> -- if its maintainer is set to
622  <ulink url="&qa-do;">Debian QA Group</ulink>, you may be able to  <ulink url="&qa-do;">Debian QA Group</ulink>, you may be able to pick it up if
623  pick it up if it's still available (check the ownership status at <ulink url="&wnpp-bts;">Debian Bug report logs: Bugs in package wnpp  it's still available.  You may also adopt a package for which the corresponding
624  in unstable</ulink>).  You may also adopt a package for which the corresponding  maintainer has filed a Request for Adoption
625  maintainer has filed a Request for Adoption (<emphasis role="strong">RFA</emphasis>).  (<emphasis role="strong">RFA</emphasis>).
626  </para>  </para>
627  <para>  <para>
628  Several different views of orphaned or RFA'ed packages are available at:  There are several package ownership status resorces.
629  </para>  </para>
630  <itemizedlist>  <itemizedlist>
631  <listitem>  <listitem>
632  <para>  <para> <ulink url="&wnpp-do;">Work-Needing and Prospective Packages</ulink> </para>
 <ulink url="&wnpp-do;">Work-Needing and Prospective  
 Packages</ulink>  
 </para>  
633  </listitem>  </listitem>
634  <listitem>  <listitem>
635  <para>  <para> <ulink url="&wnpp-bts;">Debian Bug report logs: Bugs in package wnpp in unstable</ulink> </para>
 <ulink url="&wnpp-dn;">Debian Packages that Need Lovin'</ulink>  
 </para>  
636  </listitem>  </listitem>
637  <listitem>  <listitem>
638  <para>  <para> <ulink url="&wnpp-dn;">Debian Packages that Need Lovin'</ulink> </para>
639  <ulink url="&wnpp-debtags;">Browse WNPP bugs based on  </listitem>
640  debtags</ulink>  <listitem>
641  </para>  <para> <ulink url="&wnpp-debtags;">Browse WNPP bugs based on debtags</ulink> </para>
642  </listitem>  </listitem>
643  </itemizedlist>  </itemizedlist>
644  <para>  <para>
# Line 641  triaging bugs of very popular packages Line 668  triaging bugs of very popular packages
668  </listitem>  </listitem>
669  <listitem>  <listitem>
670  <para>  <para>
671  preparing <ulink url="&devref-nmu;">QA  preparing <ulink url="&devref-nmu;">QA or NMU uploads</ulink>
 or NMU uploads</ulink>  
672  </para>  </para>
673  </listitem>  </listitem>
674  </itemizedlist>  </itemizedlist>
# Line 668  confirm its usefulness. Line 694  confirm its usefulness.
694  </listitem>  </listitem>
695  <listitem>  <listitem>
696  <para>  <para>
697  You must check if no one else is working on the package already at <ulink url="&wnpp-packaged;">the list of packages  You must check if no one else is working on the package already at the
698  being worked on</ulink>.  If no one else is working on it, file an ITP (Intent  <ulink url="&wnpp-do;">Work-Needing and Prospective Packages</ulink> site.
699    If no one else is working on it, file an ITP (Intent
700  To Package) bug report to the <systemitem role="package">wnpp</systemitem>  To Package) bug report to the <systemitem role="package">wnpp</systemitem>
701  pseudo-package using <command>reportbug</command>.  If someone's already on it,  pseudo-package using <command>reportbug</command>.  If someone's already on it,
702  contact them if you feel you need to.  If not - find another interesting  contact them if you feel you need to.  If not - find another interesting
# Line 684  That program <emphasis role="strong">mus Line 711  That program <emphasis role="strong">mus
711  <listitem>  <listitem>
712  <para>  <para>
713  For the <literal>main</literal> section, it <emphasis role="strong">must be  For the <literal>main</literal> section, it <emphasis role="strong">must be
714  compliant to all the Debian Free Software Guidelines (DFSG)</emphasis> (see  compliant to all the Debian Free Software Guidelines</emphasis> (<ulink url="&dfsg;">DFSG</ulink>)
 <ulink url="&dfsg;">&dfsg;</ulink>)  
715  and <emphasis role="strong">that program must not require a package outside of  and <emphasis role="strong">that program must not require a package outside of
716  <literal>main</literal></emphasis> for compilation or execution as required by  <literal>main</literal></emphasis> for compilation or execution as required by
717  the Debian Policy.  This is desired case.  the Debian Policy.  This is desired case.
# Line 746  package unmaintained pieces of software. Line 772  package unmaintained pieces of software.
772  <para>  <para>
773  Of course, these things are just safety measures, and intended to save you from  Of course, these things are just safety measures, and intended to save you from
774  raging users if you do something wrong in some setuid daemon...  When you gain  raging users if you do something wrong in some setuid daemon...  When you gain
775  some more experience in packaging, you'll be able to do such packages, but even  some more experience in packaging, you'll be able to package such packages.
 the experienced developers consult the <ulink url="&debian-mentors-ldo;">debian-mentors@lists.debian.org</ulink>  
 mailing list when they are in doubt.  And people there will gladly help.  
 </para>  
 <para>  
 For more help about these, check in <ulink url="&developers-reference;">Debian Developer's  
 Reference</ulink>.  
776  </para>  </para>
777  </section>  </section>
778  <section id="getit"><title>Get the program, and try it out</title>  <section id="getit"><title>Get the program, and try it out</title>
# Line 841  all the installed files. Line 861  all the installed files.
861  </section>  </section>
862  <section id="portable"><title>Free portable programs</title>  <section id="portable"><title>Free portable programs</title>
863  <para>  <para>
864  A lot of Free programs are written in the <ulink url="&cxx;_(programming_language)">C</ulink> and  A lot of Free programs are written in the <ulink url="&c-program;">C</ulink> and
865  <ulink url="&cxx;++">C++</ulink> languages.  Many of  <ulink url="&cxx;">C++</ulink> languages.  Many of
866  these use Autotools or CMake to make them portable across different platforms.  these use Autotools or CMake to make them portable across different platforms.
867  These tools are used to generate <filename>Makefile</filename> and other  These tools are used to generate <filename>Makefile</filename> and other
868  required source files.  Then, such programs are built with usual <literal>make;  required source files.  Then, such programs are built with usual <literal>make;
# Line 902  other files with <literal>autoreconf -i Line 922  other files with <literal>autoreconf -i
922  the compatibility of the source.  the compatibility of the source.
923  </para>  </para>
924  <para>  <para>
925  <ulink url="&cxx;Make">CMake</ulink> is an alternative  <ulink url="&cmake;">CMake</ulink> is an alternative
926  build system.  You can notice such sources by the  build system.  You can notice such sources by the
927  <filename>CMakeLists.txt</filename> file.  <filename>CMakeLists.txt</filename> file.
928  </para>  </para>
# Line 3151  as the first suffix, which means it's a Line 3171  as the first suffix, which means it's a
3171  sure to verify that this section is indeed the correct one.  Here's a short  sure to verify that this section is indeed the correct one.  Here's a short
3172  list of manual page sections:  list of manual page sections:
3173  </para>  </para>
3174  <screen>  <table id="manpage-sections" pgwide="0" frame="topbot" rowsep="1" colsep="1">
3175  Section |     Description     |     Notes  <title>manual page sections</title>
3176     1     User commands          Executable commands or scripts.  <tgroup cols="3">
3177     2     System calls           Functions provided by the kernel.    <colspec colwidth="8*" align="left"/> <colspec colwidth="24*" align="left"/> <colspec colwidth="40*" align="left"/>
3178     3     Library calls          Functions within system libraries.    <thead>
3179     4     Special files          Usually found in /dev      <row> <entry>Section</entry> <entry>Description</entry> <entry>Notes</entry> </row>
3180     5     File formats           E.g. /etc/passwd's format    </thead>
3181     6     Games                  Or other frivolous programs    <tbody>
3182     7     Macro packages         Such as man macros.      <row> <entry>1</entry> <entry>User command</entry> <entry>Executable commands or scripts</entry> </row>
3183     8     System administration  Programs typically only run by root.      <row> <entry>2</entry> <entry>System calls</entry> <entry>Functions provided by the kernel</entry> </row>
3184     9     Kernel routines        Non-standard calls and internals.      <row> <entry>3</entry> <entry>Library calls</entry> <entry>Functions within system libraries</entry> </row>
3185  </screen>      <row> <entry>4</entry> <entry>Special files</entry> <entry>Usually found in /dev</entry> </row>
3186        <row> <entry>5</entry> <entry>File formats</entry> <entry>E.g. <filename>/etc/passwd</filename>'s format</entry> </row>
3187        <row> <entry>6</entry> <entry>Games</entry> <entry>Games or other frivolous programs</entry> </row>
3188        <row> <entry>7</entry> <entry>Macro packages</entry> <entry>Such as man macros</entry> </row>
3189        <row> <entry>8</entry> <entry>System administration</entry> <entry>Programs typically only run by root</entry> </row>
3190        <row> <entry>9</entry> <entry>Kernel routines</entry> <entry>Non-standard calls and internals</entry> </row>
3191      </tbody>
3192    </tgroup>
3193    </table>
3194  <para>  <para>
3195  So <systemitem role="package">gentoo</systemitem>'s man page should be called  So <systemitem role="package">gentoo</systemitem>'s man page should be called
3196  <filename>gentoo.1</filename>.  If there was no <filename>gentoo.1</filename>  <filename>gentoo.1</filename>.  If there was no <filename>gentoo.1</filename>
Legend:
Removed from v.8632  
changed lines
  Added in v.8636
  ViewVC Help
Powered by ViewVC 1.1.5