source: trunk/doc-new/guide/xml/project.xml @ 38027

Last change on this file since 38027 was 38027, checked in by raimue@…, 11 years ago

guide:
Add a link to our 'New ticket' page from #project.tickets

File size: 18.8 KB
Line 
1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
4<chapter id="project">
5  <title>MacPorts Project</title>
6
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.macports.org/browser/">MacPorts
11  Subversion repository</ulink>. Though anyone may search Trac for tickets,
12  you must <ulink
13  url="https://trac.macports.org/auth/register/">register</ulink> for a Trac
14  account to create tickets.</para>
15
16  <section id="project.tickets">
17    <title>Creating Trac Tickets</title>
18
19    <para>Once you are logged into Trac, you may click <ulink
20    url="http://trac.macports.org/newticket">New Ticket</ulink> and you
21    will be presented with a new ticket window shown in the graphic below.
22    Follow the Trac ticket guidelines below 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 id="project.tickets.guidelines">
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><guilabel>Short Summary:</guilabel>
44          <replaceable>[port]</replaceable>
45          <replaceable>[version]</replaceable> <replaceable>[concise
46          description]</replaceable></para>
47
48          <itemizedlist>
49            <listitem>
50              <para>Example: "rrdtool-1.2.23 Configure error - build
51              failure"</para>
52            </listitem>
53          </itemizedlist>
54        </listitem>
55
56        <listitem>
57          <para><guilabel>Type:</guilabel> There are two main types of
58          tickets.</para>
59
60          <itemizedlist>
61            <listitem>
62              <para><guimenu>defect</guimenu> - The default; any port/MacPorts
63              build/runtime failures and/or documentation corrections.</para>
64            </listitem>
65
66            <listitem>
67              <para><guimenu>enhancement</guimenu> - Tickets, with or without
68              patches, created to enhance something that isn't failing its
69              intended purpose.</para>
70            </listitem>
71          </itemizedlist>
72        </listitem>
73
74        <listitem>
75          <para><guilabel>Full Description:</guilabel> All details that might
76          be relevant to someone reading the ticket. <ulink
77          url="http://trac.macports.org/wiki/WikiFormatting">Wiki
78          formatting</ulink> or attached log files should be used for large
79          text blocks. If you want to post a build log make sure you use
80          <literal>{{{<replaceable>...</replaceable>}}}</literal> around the
81          log or it could break the page layout. Example:</para>
82
83          <literallayout>
84{{{
85<replaceable>your build log here</replaceable>
86}}}
87          </literallayout>
88
89          <para>Submitters are advised to trim pastes and logs of any kind to what's
90          really relevant to the report, as otherwise overly large submissions that
91          might contain redundant and/or unnecessary information might become unmanageable.
92          </para>
93
94        </listitem>
95
96        <listitem>
97          <para><guilabel>Priority:</guilabel> Assign a priority level to the
98          ticket.</para>
99
100          <itemizedlist>
101            <listitem>
102              <para><guimenu>High</guimenu> - Reserved for the use of MacPorts
103              team members, as they are the best fit to determine which
104              reports warrant a higher priority over others.</para>
105            </listitem>
106
107            <listitem>
108              <para><guimenu>Normal</guimenu> - The default. For normal port
109              failures, non-critical enhancement requests, non-critical port
110              failures.</para>
111            </listitem>
112
113            <listitem>
114              <para><guimenu>Low</guimenu> - For mostly cosmetic improvements,
115              documentation corrections/improvements, etc.</para>
116            </listitem>
117
118            <listitem>
119              <para><guimenu>Not set</guimenu> - Anything that doesn't fit the
120              categories high, normal, or low.</para>
121            </listitem>
122          </itemizedlist>
123        </listitem>
124
125        <listitem>
126          <para><guilabel>Component:</guilabel> Set what part of the MacPorts
127          Project the ticket is to be filed against.</para>
128
129          <itemizedlist>
130            <listitem>
131              <para><guimenu>base</guimenu> - Tickets related to MacPorts base
132              code.</para>
133            </listitem>
134
135            <listitem>
136              <para><guimenu>guide</guimenu> - Documentation enhancements and
137              error corrections, or patches to the MacPorts Guide.</para>
138            </listitem>
139
140            <listitem>
141              <para><guimenu>ports</guimenu> - Tickets related to
142              ports.</para>
143            </listitem>
144
145            <listitem>
146              <para><guimenu>server/hosting</guimenu> - For MacPorts hosting
147              &amp; server-side issues, reserved for MacPorts PortMgr team
148              members.</para>
149            </listitem>
150
151            <listitem>
152              <para><guimenu>website</guimenu> - MacPorts website enhancements
153              and error corrections.</para>
154            </listitem>
155
156            <listitem>
157              <para><guimenu>wiki</guimenu> - MacPorts Wiki enhancements and
158              error corrections.</para>
159            </listitem>
160          </itemizedlist>
161        </listitem>
162
163        <listitem>
164          <para><guilabel>Keywords:</guilabel> Type any keywords that might
165          help when searching for tickets (portname, type of problem,
166          etc).</para>
167        </listitem>
168
169        <listitem>
170          <para><guilabel>Cc:</guilabel> Anyone else besides the ticket
171          reporter and assignee who would like to be kept involved in the
172          development of the ticket, and/or the port maintainer in case
173          his/her address does not appear in the <guimenu>Assign To</guimenu>
174          drop down menu. Multiple emails should be separated with a comma
175          (i.e. <literal>you@example.org, maintainer@macports.org</literal>).
176          To get the maintainer email address use <command>port info
177          &lt;portname&gt;</command>.</para>
178        </listitem>
179
180        <listitem>
181          <para><guilabel>Milestone:</guilabel> This is a ticket category that
182          allows for search and sorting tickets efficiently.</para>
183
184          <itemizedlist>
185            <listitem>
186              <para><guimenu>MacPorts base enhancements</guimenu> - for
187              tickets requesting or providing improvements to the
188              functionality of the MacPorts system.</para>
189            </listitem>
190
191            <listitem>
192              <para><guimenu>MacPorts base bugs</guimenu> - for tickets
193              reporting or fixing bugs in the MacPorts system.</para>
194            </listitem>
195
196            <listitem>
197              <para><guimenu>Port Bugs</guimenu> - for tickets reporting or
198              fixing bugs in ports provided by MacPorts.</para>
199            </listitem>
200
201            <listitem>
202              <para><guimenu>Port Enhancements</guimenu> - for submissions
203              providing enhancements to ports provided by MacPorts.</para>
204            </listitem>
205
206            <listitem>
207              <para><guimenu>Port Requests</guimenu> - for requests for ports
208              to be added to MacPorts.</para>
209            </listitem>
210
211            <listitem>
212              <para><guimenu>Port Submissions</guimenu> - for submissions that
213              add a port to MacPorts.</para>
214            </listitem>
215
216            <listitem>
217              <para><guimenu>Port Updates</guimenu> - for submissions that
218              update a port provided by MacPorts.</para>
219            </listitem>
220
221            <listitem>
222              <para><guimenu>Website &amp; Documentation</guimenu> - for
223              tickets relating to the documentation for MacPorts, including
224              the MacPorts guide, Wiki, man pages and the website.</para>
225            </listitem>
226
227            <listitem>
228              <para>Blank - For unclassified tickets that don't fit into any
229              of the provided milestones.</para>
230            </listitem>
231          </itemizedlist>
232        </listitem>
233
234        <listitem>
235          <para><guilabel>Version:</guilabel> Select the MacPorts version you
236          are using when it is applicable.</para>
237        </listitem>
238
239        <listitem>
240          <para><guilabel>Assign To:</guilabel> For tickets on ports, select
241          the port maintainer's email address (use <command>port info
242          &lt;portname&gt;</command>). If the maintainer's email address is
243          <email>nomaintainer@macports.org</email>, select
244          <email>macports-tickets@lists.macosforge.org</email>.</para>
245        </listitem>
246
247        <listitem>
248          <para><guilabel>Attachments:</guilabel> Files may be attached to a
249          ticket when it is being created if the checkbox that reads &ldquo;I
250          have files to attach to this ticket&rdquo; is selected, or after it
251          has been submitted by using the file attachment button.</para>
252        </listitem>
253      </itemizedlist>
254    </section>
255  </section>
256
257  <section id="project.contributing">
258    <title>Contributing to MacPorts</title>
259
260    <para>You may contribute new ports and enhancements of any kind to already
261    existing ports using Trac tickets.</para>
262
263    <!-- Should we have similar sections about committing to base sources and
264    documentation, or alternatively add this to the following? -->
265
266    <section id="project.contributing.new">
267      <title>New Ports</title>
268
269      <para>Ports are contributed by following these steps. See Ticket
270      Submission Guidelines above for a description of all fields.</para>
271
272      <orderedlist>
273        <listitem>
274          <para>Create a Trac ticket.</para>
275        </listitem>
276
277        <listitem>
278          <para>Set the type to <guilabel>enhancement</guilabel>.</para>
279        </listitem>
280
281        <listitem>
282          <para>Set the milestone to <guilabel>Port
283          Submissions</guilabel>.</para>
284        </listitem>
285
286        <listitem>
287          <para>Attach the <filename>Portfile</filename> and any required
288          patchfiles to the ticket.</para>
289        </listitem>
290      </orderedlist>
291    </section>
292
293    <section id="project.contributing.updates">
294      <title>Port Enhancements</title>
295
296      <para>Enhancements to existing ports may comprise new functionality for
297      a given port, bug fixes or even simple version updates. They should
298      always be contributed as <filename>Portfile</filename> patches. See
299      Ticket Submission Guidelines above for a description of all
300      fields.</para>
301
302      <orderedlist>
303        <listitem>
304          <para>Create a <filename>Portfile</filename> patch with your changes
305          as described in Portfile Development.</para>
306        </listitem>
307
308        <listitem>
309          <para>Create a Trac ticket.</para>
310        </listitem>
311
312        <listitem>
313          <para>Set the type to <guilabel>enhancement</guilabel> for
314          miscellaneous enhancements or to <guilabel>defect</guilabel> for bug
315          fixes.</para>
316        </listitem>
317
318        <listitem>
319          <para>Set the milestone to <guilabel>Port Enhancements</guilabel>,
320          <guilabel>Port Updates</guilabel> or <guilabel>Port Bugs</guilabel>
321          depending on the case.</para>
322        </listitem>
323
324        <listitem>
325          <para>Attach your Portfile patch file and any new or changed patch
326          files (don't patch patches) to the ticket.</para>
327        </listitem>
328      </orderedlist>
329    </section>
330  </section>
331
332  <section id="project.update-policies">
333    <title>Port Update Policies</title>
334
335    <para>Port maintainers normally are given commit privileges to the
336    Subversion repository so they can make updates to their own ports.
337    However, The MacPorts Project does not restrict commit privileges for
338    maintainers, so before a person other than a port's maintainer updates a
339    port it is a good practice to inform a port's maintainer. See details
340    below.</para>
341
342    <section id="project.update-policies.nonmaintainer">
343      <title>Non-Maintainer Port Updates</title>
344
345      <para>If you have a port update or bugfix for a port you do not
346      maintain, to respect the rights of the port maintainer you should follow
347      the following guidelines:</para>
348
349      <orderedlist>
350        <listitem>
351          <para>If a port's maintainer is
352          <email>nomaintainer@macports.org</email>, you may feel free to make
353          updates and/or take maintainership of the port.</para>
354        </listitem>
355
356        <listitem>
357          <para>If a port's maintainer contains the address
358          <email>openmaintainer@macports.org</email>, this means that the
359          author allows minor updates to the port without contacting him
360          first. But permission should still be sought for major
361          changes.</para>
362        </listitem>
363
364        <listitem>
365          <para>Create patch file(s) as necessary, attach them to a Trac
366          ticket, and assign the ticket to the maintainer and Cc him or
367          her.</para>
368        </listitem>
369
370        <listitem>
371          <para>Wait for a response from the maintainer. The maintainer should
372          apply the patches and close the ticket within 72 hours.</para>
373        </listitem>
374      </orderedlist>
375
376      <para>However, for maintained ports without
377      <email>openmaintainer@macports.org</email>, there are some conditions
378      under which maintainer permission may be waived:</para>
379
380      <itemizedlist>
381        <listitem>
382          <para>If the maintainer does not respond within 72 hours, you or
383          another committer may review the patches and update the port. If you
384          are not a committer, you may email
385          <email>macports-dev@lists.macosforge.org</email> and request the
386          updates be committed.</para>
387        </listitem>
388
389        <listitem>
390          <para>A port is abandoned by it's current maintainer. A port against
391          which a Port Abandoned ticket has been filed (see below) can be
392          updated without contacting the maintainer.</para>
393        </listitem>
394
395        <listitem>
396          <para>A critical port is broken that affects many users.</para>
397        </listitem>
398      </itemizedlist>
399    </section>
400
401    <section id="project.update-policies.abandonment">
402      <title>Port Abandonment</title>
403
404      <para>A port may be considered abandoned if a bug has not been
405      acknowledged for more than three weeks after a ticket is filed. If this
406      time period has passed and you wish to initiate the Port Abandonment
407      protocol and volunteer as the new maintainer:</para>
408
409      <orderedlist>
410        <listitem>
411          <para>File a new Trac ticket with the summary line [Port
412          Abandoned].</para>
413        </listitem>
414
415        <listitem>
416          <para>Refer to the original unacknowledged ticket in the Port
417          Abandoned ticket.</para>
418        </listitem>
419
420        <listitem>
421          <para>The Port Abandoned ticket may be closed when the new
422          maintainer is assigned, and the original ticket with the updates may
423          be resolved when the updates attached to the original ticket are
424          committed.</para>
425        </listitem>
426      </orderedlist>
427    </section>
428  </section>
429
430  <section id="project.membership">
431    <title>MacPorts Membership</title>
432
433    <para>A requirement for a person to become a MacPorts committer is to
434    first become involved and contribute to the project. This may be done by
435    having a record of contribution to the project in several of the following
436    ways:</para>
437
438    <itemizedlist>
439      <listitem>
440        <para>Contributing new ports.</para>
441      </listitem>
442
443      <listitem>
444        <para>Fixing bugs in existing ports.</para>
445      </listitem>
446
447      <listitem>
448        <para>Volunteering as a maintainer of non-maintained ports.</para>
449      </listitem>
450
451      <listitem>
452        <para>Involvement on MacPorts support lists.</para>
453      </listitem>
454
455      <listitem>
456        <para>Contributing with documentation</para>
457      </listitem>
458    </itemizedlist>
459
460    <para>To apply for MacPorts commit rights, send a brief email to the
461    PortMgr team at <email>macports-mgr@lists.macosforge.org</email> entitled
462    &ldquo;Request for commit rights&rdquo; with the following contents:</para>
463
464    <itemizedlist>
465      <listitem>
466        <para>a description of your application and why you think you deserve
467        commit rights (including evidence of contributions to MacPorts as described
468        above).</para>
469      </listitem>
470
471      <listitem>
472        <para>the identity you'd like to use as a member of the project, A.K.A. the
473        &ldquo;handle&rdquo;, as part of your <literal><replaceable>handle</replaceable>@macports.org</literal>
474        alias.</para>
475      </listitem>
476
477      <listitem>
478        <para>a real e-mail address to which you'd like your MacPorts alias to forward.</para>
479      </listitem>
480    </itemizedlist>
481
482    <para>The PortMgr team will consider all applications and provide an appropriate
483    response in a timely manner.</para>
484
485  </section>
486
487  <section id="project.portmgr">
488    <title>The PortMgr Team</title>
489
490    <para>The MacPorts PortMgr team is the steering group for The MacPorts
491    Project. Its membership was determined by public elections among project
492    members in March of 2005, resulting in the appointing of <personname>
493
494        <firstname>James</firstname>
495
496        <othername role="initial">D.</othername>
497
498        <surname>Berry</surname>
499      </personname>, <personname>
500      <firstname>Juan</firstname>
501
502        <othername role="middlename">Manuel</othername>
503
504        <surname>Palacios</surname>
505      </personname> and <personname>
506
507        <firstname>Markus</firstname>
508
509        <othername role="initial">W.</othername>
510
511        <surname>Weissman</surname>
512      </personname>.
513
514    They are responsible for matters such as:
515
516    <itemizedlist>
517        <listitem>
518          <para>approving new project members (i.e. granting commit
519          rights);</para>
520        </listitem>
521
522        <listitem>
523          <para>setting general guidelines for the project;</para>
524        </listitem>
525
526        <listitem>
527          <para>dispute resolution;</para>
528        </listitem>
529
530        <listitem>
531          <para>managing the projects infrastructure; and</para>
532        </listitem>
533
534        <listitem>
535          <para>engineering releases.</para>
536        </listitem>
537      </itemizedlist></para>
538
539  </section>
540</chapter>
Note: See TracBrowser for help on using the repository browser.