Changeset 27280 for trunk/doc


Ignore:
Timestamp:
Jul 27, 2007, 6:38:31 AM (12 years ago)
Author:
markd@…
Message:

Start filling out the MacPorts Project section of the guide, including ticketing guidelines.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/doc/guide/new/xml/project.xml

    r27109 r27280  
    55  <title>MacPorts Project</title>
    66
     7  <para>The MacPorts Project uses a system called <ulink
     8  url="http://trac.edgewall.org/">Trac</ulink> to file tickets to report bugs
     9  and enhancement requests. Trac also provides an interface to browse the
     10  <ulink url="http://trac.macosforge.org/projects/macports/browser/">MacPorts
     11  Subversion repository</ulink>. Though anyone may search Trac for tickets,
     12  you must <ulink
     13  url="http://www.macosforge.org/wp-register.php">register</ulink> for a Trac
     14  account to create tickets.</para>
     15
    716  <section>
    8     <title>Submitting Bug Reports</title>
    9 
    10     <para></para>
     17    <title>Creating Trac Tickets</title>
     18
     19    <para>Once you are logged into Trac, you may click <emphasis>View Tickets
     20    -&gt; New Ticket</emphasis> and you will be presented with a new ticket
     21    window shown in the graphic below. Follow the Trac ticket guidelines below
     22    to fill out the form.</para>
     23
     24    <screenshot>
     25      <screeninfo>A new Trac ticket</screeninfo>
     26
     27      <mediaobject>
     28        <imageobject>
     29          <imagedata fileref="trac-default.png" />
     30        </imageobject>
     31      </mediaobject>
     32    </screenshot>
     33
     34    <section>
     35      <title>Trac Ticket Guidelines</title>
     36
     37      <para>There are certain conventions used to ensure that Trac tickets
     38      convey as much accurate information as possible so problems and
     39      contributions may be acted upon efficiently.</para>
     40
     41      <itemizedlist>
     42        <listitem>
     43          <para><emphasis>Short Summary:</emphasis> [port] [version] [concise
     44          description]</para>
     45
     46          <itemizedlist>
     47            <listitem>
     48              <para>Example: "rrdtool-1.2.23 Configure error - build
     49              failure"</para>
     50            </listitem>
     51          </itemizedlist>
     52        </listitem>
     53
     54        <listitem>
     55          <para><emphasis>Type:</emphasis> There are two main types of
     56          tickets.</para>
     57
     58          <itemizedlist>
     59            <listitem>
     60              <para>defect - The default; any port/MacPorts build/runtime
     61              failures and/or documentation corrections.</para>
     62            </listitem>
     63
     64            <listitem>
     65              <para>enhancement - Tickets, with or without patches, created to
     66              enhance something that isn't failing its intended
     67              purpose.</para>
     68            </listitem>
     69          </itemizedlist>
     70        </listitem>
     71
     72        <listitem>
     73          <para><emphasis>Full Description:</emphasis> All details that might
     74          be relevant to someone reading the ticket. <ulink
     75          url="http://trac.macports.org/projects/macports/wiki/WikiFormatting">Wiki
     76          formatting</ulink> or attached log files should be used for large
     77          text blocks.</para>
     78        </listitem>
     79
     80        <listitem>
     81          <para><emphasis>Priority:</emphasis> Assign a priority level to the
     82          ticket.</para>
     83
     84          <itemizedlist>
     85            <listitem>
     86              <para>High - For core MacPorts build/runtime failures and/or
     87              critical enhancement requests.</para>
     88            </listitem>
     89
     90            <listitem>
     91              <para>Normal - The default. For normal port failures,
     92              non-critical enhancement requests, non-critical port
     93              failures.</para>
     94            </listitem>
     95
     96            <listitem>
     97              <para>Low - For mostly cosmetic improvements, documentation
     98              corrections/improvements, etc.</para>
     99            </listitem>
     100
     101            <listitem>
     102              <para>Not set - Anything that doesn't fit the categories high,
     103              normal, or low.</para>
     104            </listitem>
     105          </itemizedlist>
     106        </listitem>
     107
     108        <listitem>
     109          <para><emphasis>Component:</emphasis> Set what part of the MacPorts
     110          project the ticket is to be filed against.</para>
     111
     112          <itemizedlist>
     113            <listitem>
     114              <para>ports - Tickets related to ports.</para>
     115            </listitem>
     116
     117            <listitem>
     118              <para>base - Tickets related to MacPorts base code.</para>
     119            </listitem>
     120
     121            <listitem>
     122              <para>guide - Documentation errors, corrections, or patches to
     123              the MacPorts Guide.</para>
     124            </listitem>
     125
     126            <listitem>
     127              <para>www - MacPorts website errors.</para>
     128            </listitem>
     129
     130            <listitem>
     131              <para>infrastructure - Reserved for MacPorts Portmgr team
     132              members.</para>
     133            </listitem>
     134          </itemizedlist>
     135        </listitem>
     136
     137        <listitem>
     138          <para><emphasis>Assign To:</emphasis> For tickets on ports, select
     139          the port maintainer's email address (use <command>port info
     140          &lt;portname&gt;</command>). If the maintainer's email address is
     141          <email>nomaintainer@macports.org</email>, select
     142          <email>macports-dev@lists.macosforge.org</email>.</para>
     143        </listitem>
     144
     145        <listitem>
     146          <para><emphasis>Milestone:</emphasis> This is a ticket category that
     147          allows for search and sorting tickets efficiently.</para>
     148
     149          <itemizedlist>
     150            <listitem>
     151              <para>Documentation</para>
     152            </listitem>
     153
     154            <listitem>
     155              <para>MacPorts core enhancements</para>
     156            </listitem>
     157
     158            <listitem>
     159              <para>MacPorts core bugs</para>
     160            </listitem>
     161
     162            <listitem>
     163              <para>MacPorts x.y</para>
     164            </listitem>
     165
     166            <listitem>
     167              <para>Port Bugs</para>
     168            </listitem>
     169
     170            <listitem>
     171              <para>Port Enhancements</para>
     172            </listitem>
     173
     174            <listitem>
     175              <para>Port Requests</para>
     176            </listitem>
     177
     178            <listitem>
     179              <para>Submissions</para>
     180            </listitem>
     181
     182            <listitem>
     183              <para>Port Submissions</para>
     184            </listitem>
     185
     186            <listitem>
     187              <para>Port Updates</para>
     188            </listitem>
     189          </itemizedlist>
     190        </listitem>
     191
     192        <listitem>
     193          <para><emphasis>Version:</emphasis> Select the MacPorts version you
     194          are using when it is applicable.</para>
     195        </listitem>
     196
     197        <listitem>
     198          <para><emphasis>Keywords:</emphasis> Type any keywords that might
     199          help when searching for tickets (portname, type of problem,
     200          etc).</para>
     201        </listitem>
     202
     203        <listitem>
     204          <para><emphasis>Cc:</emphasis> The reporter should enter his or her
     205          email address and the maintainer's email address to notify both
     206          parties when updates to the ticket occur. This is important, because
     207          Trac currently only sends emails to addresses on the Cc list, not to
     208          the reporter or the assignee.</para>
     209        </listitem>
     210
     211        <listitem>
     212          <para><emphasis>Attachments</emphasis> - Files may be attached only
     213          after a ticket has been submitted. Once the ticket has been created
     214          you will see the file attachment button.</para>
     215        </listitem>
     216      </itemizedlist>
     217    </section>
    11218  </section>
    12219
    13220  <section>
    14     <title>Submitting Ports</title>
    15 
    16     <para></para>
     221    <title>Contributing to MacPorts</title>
     222
     223    <para>You may contribute new ports and port updates to current ports using
     224    Trac tickets.</para>
     225
     226    <section>
     227      <title>New Ports</title>
     228
     229      <para>Ports are contributed by following these steps. See Ticket
     230      Submission Guidelines above for a description of all fields.</para>
     231
     232      <orderedlist>
     233        <listitem>
     234          <para>Create a Trac ticket.</para>
     235        </listitem>
     236
     237        <listitem>
     238          <para>Set the type to <guilabel>enhancement</guilabel>.</para>
     239        </listitem>
     240
     241        <listitem>
     242          <para>Set the milestone to <guilabel>Port
     243          Submissions</guilabel>.</para>
     244        </listitem>
     245
     246        <listitem>
     247          <para>Attach the <filename>Portfile</filename> and any required
     248          patchfiles to the ticket.</para>
     249        </listitem>
     250      </orderedlist>
     251    </section>
     252
     253    <section>
     254      <title>Port Updates</title>
     255
     256      <para>Portfile updates should always be contributed as
     257      <filename>Portfile</filename> patches. Ports are contributed by
     258      following these steps. See Ticket Submission Guidelines above for a
     259      description of all fields.</para>
     260
     261      <orderedlist>
     262        <listitem>
     263          <para>Create a <filename>Portfile</filename> patch with your changes
     264          as described in Portfile Development.</para>
     265        </listitem>
     266
     267        <listitem>
     268          <para>Create a Trac ticket.</para>
     269        </listitem>
     270
     271        <listitem>
     272          <para>Set the type to <guilabel>enhancement</guilabel>.</para>
     273        </listitem>
     274
     275        <listitem>
     276          <para>Set the milestone to <guilabel>Port
     277          Enhancements</guilabel>.</para>
     278        </listitem>
     279
     280        <listitem>
     281          <para>Attach your Portfile patch file and any new or changed patch
     282          files (don't patch patches) to the ticket.</para>
     283        </listitem>
     284      </orderedlist>
     285    </section>
    17286  </section>
    18287
     
    20289    <title>Port Update Policies</title>
    21290
    22     <para></para>
     291    <para>Port maintainers normally are given commit privileges to the
     292    Subversion repository so they can make updates to their own ports.
     293    However, the MacPorts project does not restrict commit privileges for
     294    maintainers, so before a person other than a port's maintainer updates a
     295    port it is a good practice to inform a port's maintainer. See details
     296    below.</para>
     297
     298    <section>
     299      <title>Non-Maintainer Port Updates</title>
     300
     301      <para>If you have a port update or bugfix for a port you do not
     302      maintain, to respect the rights of the port maintainer you should folow
     303      the following protocol:</para>
     304
     305      <orderedlist>
     306        <listitem>
     307          <para>Create patch file(s) as necessary, attach them to a Trac
     308          ticket, and assign the ticket to the maintainer and Cc him or
     309          her.</para>
     310        </listitem>
     311
     312        <listitem>
     313          <para>Wait for a response from the maintainer. The maintainer may
     314          apply the patches and close the ticket.</para>
     315        </listitem>
     316
     317        <listitem>
     318          <para>If the maintainer does not respond within 72 hours, you or
     319          another committer may review the patches and update the port. If you
     320          are not a committer, you may email
     321          <email>macports-dev@lists.macosforge.org</email> and request the
     322          updates be committed.</para>
     323        </listitem>
     324      </orderedlist>
     325
     326      <para>There are circumstances for which the protocol may be
     327      waived:</para>
     328
     329      <itemizedlist>
     330        <listitem>
     331          <para>A port's maintainer is set to
     332          <email>openmaintainer@macports.org</email> or
     333          <email>nomaintainer@macports.org</email>. Feel free to take over
     334          these ports.</para>
     335        </listitem>
     336
     337        <listitem>
     338          <para>A port is abandoned by it's current maintainer. A port against
     339          which a Port Abandoned ticket has been filed (see below) can be
     340          updated without contacting the maintainer.</para>
     341        </listitem>
     342
     343        <listitem>
     344          <para>A critical port is broken that affects many users.</para>
     345        </listitem>
     346      </itemizedlist>
     347    </section>
     348
     349    <section>
     350      <title>Port Abandonment</title>
     351
     352      <para>A port may be considered abandoned if a bug has not been
     353      acknowledged for more than three weeks after a ticket is filed. If this
     354      time period has passed and you wish to initiate the Port Abandonment
     355      protocol and volunteer as the new maintainer:</para>
     356
     357      <orderedlist>
     358        <listitem>
     359          <para>File a new Trac ticket with the summary line [Port
     360          Abandoned].</para>
     361        </listitem>
     362
     363        <listitem>
     364          <para>Refer to the original unacknowledged ticket in the Port
     365          Abandoned ticket.</para>
     366        </listitem>
     367
     368        <listitem>
     369          <para>The Port Abandoned ticket may be closed when the new
     370          maintainer is assigned, and the original ticket with the updates may
     371          be resolved when the updates attached to the original ticket are
     372          committed.</para>
     373        </listitem>
     374      </orderedlist>
     375    </section>
    23376  </section>
    24377
     
    26379    <title>MacPorts Membership</title>
    27380
    28     <para></para>
     381    <para>A requirement for a person to become a MacPorts committer is to
     382    first become involved and contribute to the project. This may be done by
     383    having a record of contributing to the project in several of the following
     384    ways:</para>
     385
     386    <itemizedlist>
     387      <listitem>
     388        <para>Contributing new ports.</para>
     389      </listitem>
     390
     391      <listitem>
     392        <para>Fixing bugs in existing ports.</para>
     393      </listitem>
     394
     395      <listitem>
     396        <para>Volunteering as a maintainer of non-maintained ports.</para>
     397      </listitem>
     398
     399      <listitem>
     400        <para>Involvement on MacPorts support lists.</para>
     401      </listitem>
     402    </itemizedlist>
    29403  </section>
    30404</chapter>
Note: See TracChangeset for help on using the changeset viewer.