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

Last change on this file since 146649 was 146649, checked in by cal@…, 5 years ago

guide: Instruct users to include links to tickets

If a user wants his changes to be reviewed, they should make it easy to reach
the changes. Instruct users to post a link to the ticket for easy clicking.

File size: 38.9 KB
1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
4<chapter id="project">
5  <title>MacPorts Project</title>
7  <section id="">
8    <title>Using Trac for Tickets</title>
10    <para>The MacPorts Project uses a system called <ulink
11    url="">Trac</ulink> to file tickets to report bugs
12    and enhancement requests. Trac also provides an interface to browse the
13    <ulink url="">MacPorts
14    Subversion repository</ulink>. Though anyone may search Trac for tickets,
15    you must <ulink
16    url="">register</ulink> for a Trac
17    account to create tickets.</para>
19    <section id="">
20      <title>Before Filing a New Ticket</title>
22      <itemizedlist>
23        <listitem>
24          <para>Clean and try again</para>
25          <para>
26            If a build fails or is otherwise interrupted, and you try again,
27            MacPorts tries to pick up where it left off. Sometimes this causes
28            new problems, and even if it doesn't, it means that log messages
29            from earlier steps, which can be essential for figuring out why a
30            build failed, are not included in the new log; MacPorts prints
31            <quote>Skipping completed</quote> in the log for each
32            previously-completed phase that was skipped. Before filing a
33            ticket, <userinput>sudo port clean</userinput> the port that
34            failed, then try again.</para>
35        </listitem>
36        <listitem>
37          <para>Check the problem hotlist</para>
38          <para>
39            The <ulink
40              url="">Problem
41              Hotlist</ulink> contains possible solutions to problems that
42            affect many MacPorts users. If a solution to your problem listed
43            there works, don't file a ticket.
44          </para>
45        </listitem>
46        <listitem>
47          <para>Search to see if a Trac ticket has already been filed</para>
48          <para>
49            Avoid filing duplicate bugs. Search for duplicates by:
50          </para>
51            <itemizedlist>
52                <listitem><para>using the search bar that appears on each page</para></listitem>
53                <listitem><para>using <ulink url="">the search page</ulink></para></listitem>
54                <listitem><para>browsing the list of <ulink url="">categorized reports</ulink></para></listitem>
55                <listitem><para>making an advanced search by constructing a <ulink url="">custom query</ulink></para></listitem>
56            </itemizedlist>
57        </listitem>
58        <listitem>
59          <para>Is the problem an application error and not related to compiling and installing?</para>
60          <para>
61            In general, application bugs should be reported to the developers of the app
62            (<quote>upstream</quote>), not MacPorts. An application bug that affects a large number of
63            MacPorts users might merit a MacPorts bug for informational purposes only, but
64            this should be done sparingly.
65          </para>
66        </listitem>
67        <listitem>
68          <para>Is the problem with a 'port upgrade' operation?</para>
69          <para>
70            If so, try a 'port uninstall <replaceable>foo</replaceable>' and
71            then reinstall. You might also want to run 'port -nR upgrade --force
72            <replaceable>foo</replaceable>' to rebuild ports depending upon
73            port <replaceable>foo</replaceable>.
74            Note that it is safest and recommended that most users always upgrade
75            with 'port upgrade outdated' to update all ports at once. Upgrading a
76            single port can lead to software errors in other ports that have not
77            yet been upgraded.
78          </para>
79        </listitem>
80      </itemizedlist>
81    </section>
83    <section id="">
84      <title>Creating Trac Tickets</title>
86      <para>Once you are logged into Trac, you may click <ulink
87      url="">New Ticket</ulink> and you
88      will be presented with a new ticket window shown in the graphic below.
89      Follow the Trac ticket guidelines below to fill out the form. If you are
90      reporting a failed port install and a log was mentioned in the error,
91      please use the <guilabel>I have files to attach to this ticket</guilabel>
92      checkbox to add that log file to the ticket.</para>
94      <screenshot>
95        <screeninfo>A new Trac ticket</screeninfo>
97        <mediaobject>
98          <textobject>
99            <phrase>screenshot of a new ticket on the Trac system</phrase>
100          </textobject>
101          <imageobject>
102            <imagedata fileref="trac-default.png" />
103          </imageobject>
104        </mediaobject>
105      </screenshot>
106    </section>
108    <section id="">
109      <title>Trac Ticket Guidelines</title>
111      <para>There are certain conventions used to ensure that Trac tickets
112      convey as much accurate information as possible so problems and
113      contributions may be acted upon efficiently.</para>
115      <itemizedlist>
116        <listitem>
117          <para><guilabel>Summary:</guilabel>
118          <replaceable>[port]</replaceable>
119          <replaceable>[version]</replaceable> <replaceable>[concise
120          description]</replaceable></para>
122          <itemizedlist>
123            <listitem>
124              <para>Example: "rrdtool @1.2.23 +python Configure error - build
125              failure"</para>
126            </listitem>
127          </itemizedlist>
128        </listitem>
130        <listitem>
131          <para><guilabel>Description:</guilabel> All details that might
132          be relevant to someone reading the ticket. Be sure to mention
133          the versions of your operating system and Xcode install. <ulink
134          url="">Wiki
135          formatting</ulink> should be used to ensure that text is formatted
136          correctly. Use the Preview button before submitting. If you want to
137          post preformatted text such as a log or terminal output, make sure
138          you use <literal>{{{<replaceable>...</replaceable>}}}</literal>
139          around the text or it could break the page layout. Example:</para>
141          <literallayout>
143<replaceable>your error message here</replaceable>
145          </literallayout>
147          <para>Submitters are advised to trim inline pastes and logs to
148          what's really relevant to the report, as otherwise overly large
149          ticket pages can become unmanageable. Long output, such as the
150          full log from a port build, should be added as an attachment, not
151          pasted inline. See <guilabel>I have files to attach to this
152          ticket</guilabel> below.</para>
154        </listitem>
156        <listitem>
157          <para><guilabel>Type:</guilabel> There are five types of
158          tickets.</para>
160          <itemizedlist>
161            <listitem>
162              <para><guimenu>defect</guimenu> - The default; any port/MacPorts
163              build/runtime failures and/or documentation corrections.</para>
164            </listitem>
166            <listitem>
167              <para><guimenu>enhancement</guimenu> - Tickets, with or without
168              patches, created to enhance something that isn't failing its
169              intended purpose.</para>
170            </listitem>
172            <listitem>
173              <para><guimenu>update</guimenu> - Tickets, with or without
174              patches, involving updating a port to a newer upstream
175              version.</para>
176            </listitem>
178            <listitem>
179              <para><guimenu>submission</guimenu> - Tickets created to submit
180              Portfiles for software not currently available in MacPorts.
181              </para>
182            </listitem>
184            <listitem>
185              <para><guimenu>request</guimenu> - Tickets created to request
186              the creation of a new port.</para>
187            </listitem>
188          </itemizedlist>
189        </listitem>
191        <listitem>
192          <para><guilabel>Priority:</guilabel> Assign a priority level to the
193          ticket.</para>
195          <itemizedlist>
196            <listitem>
197              <para><guimenu>High</guimenu> - Reserved for the use of MacPorts
198              team members, as they are the best fit to determine which
199              reports warrant a higher priority over others.</para>
200            </listitem>
202            <listitem>
203              <para><guimenu>Normal</guimenu> - The default. For normal port
204              failures, non-critical enhancement requests, non-critical port
205              failures.</para>
206            </listitem>
208            <listitem>
209              <para><guimenu>Low</guimenu> - For mostly cosmetic improvements,
210              documentation corrections/improvements, etc.</para>
211            </listitem>
213            <listitem>
214              <para><guimenu>Not set</guimenu> - Anything that doesn't fit the
215              categories high, normal, or low.</para>
216            </listitem>
217          </itemizedlist>
218        </listitem>
220        <listitem>
221          <para><guilabel>Milestone:</guilabel> This is a ticket label that
222          indicates that the ticket is intended to be fixed in a particular
223          MacPorts release. Leave it blank; it will be set by a project member
224          if appropriate.</para>
225        </listitem>
227        <listitem>
228          <para><guilabel>Component:</guilabel> Set what part of the MacPorts
229          Project the ticket is to be filed against.</para>
231          <itemizedlist>
232            <listitem>
233              <para><guimenu>base</guimenu> - Tickets related to MacPorts base
234              code.</para>
235            </listitem>
237            <listitem>
238              <para><guimenu>guide</guimenu> - Documentation enhancements and
239              error corrections, or patches to the MacPorts Guide.</para>
240            </listitem>
242            <listitem>
243              <para><guimenu>ports</guimenu> - Tickets related to
244              ports.</para>
245            </listitem>
247            <listitem>
248              <para><guimenu>server/hosting</guimenu> - For MacPorts hosting
249              &amp; server-side issues, reserved for MacPorts PortMgr team
250              members.</para>
251            </listitem>
253            <listitem>
254              <para><guimenu>website</guimenu> - MacPorts website enhancements
255              and error corrections.</para>
256            </listitem>
258            <listitem>
259              <para><guimenu>wiki</guimenu> - MacPorts Wiki enhancements and
260              error corrections.</para>
261            </listitem>
262          </itemizedlist>
263        </listitem>
265        <listitem>
266          <para><guilabel>Version:</guilabel> Select the MacPorts version you
267          are using when it is applicable.</para>
268        </listitem>
270        <listitem>
271          <para><guilabel>Keywords:</guilabel> Type any keywords that might
272          help when searching for tickets. It is not useful to list words here
273          that already appear elsewhere in the ticket. Keywords also serve as
274          tags; for example, use <quote>tiger</quote> if reporting a bug that
275          only affects OS X 10.4, <quote>haspatch</quote> if a fix is attached
276          to the ticket, <quote>maintainer</quote> if you are the port's
277          maintainer, or <quote>LP64</quote> if reporting an issue that only
278          affects 64-bit platforms.</para>
279        </listitem>
281        <listitem>
282          <para><guilabel>Cc:</guilabel> Anyone else besides the ticket
283          reporter and assignee who would like to be kept involved in the
284          development of the ticket. Multiple email addresses should be
285          separated with a comma and a space
286          (e.g., <literal>,</literal>).</para>
288          <para>When reporting port-related tickets, make sure you add the
289          port maintainers email address to the <guilabel>Cc:</guilabel> field
290          so they are notified of the ticket (unless you have commit access,
291          then see <guilabel>Assign To:</guilabel> below). You can obtain the
292          email address of the port maintainer from the Portfile, or by running
293          <literal>port info --maintainers <replaceable>[port]</replaceable>
294          </literal></para>
295        </listitem>
297        <listitem>
298          <para><guilabel>Assign To:</guilabel> Only users with commit access
299          can edit this field. If this is not you, see the section on the
300          <guimenu>Cc</guimenu> field above.</para>
302          <para>For tickets on ports, enter
303          the email address of the port's maintainer (use <command>port info
304          &lt;portname&gt;</command> to find this). If multiple maintainers
305          are listed, enter the first maintainer's email address here and
306          enter the remaining maintainers' email addresses in the
307          <guimenu>Cc</guimenu> field. Exclude the email address
308          <email></email> if it appears.
309          If the maintainer's email address is
310          <email></email>, leave the field
311          blank.</para>
312        </listitem>
314        <listitem>
315          <para><guilabel>Port:</guilabel> For tickets on ports, enter the
316          name of the port (or ports, space-separated, when multiple are
317          affected).</para>
318        </listitem>
320        <listitem>
321          <para><guilabel>I have files to attach to this ticket:</guilabel>
322          Use this checkbox to attach files to the ticket immediately after
323          you create it. Or you can attach files later using the
324          <guilabel>Attach File</guilabel> button.</para>
325          <para>If the file you are attaching is larger than 256 KiB, please
326          compress it with bzip2 or gzip first to save space on the server and
327          bandwidth for those downloading it, as
328          Trac will not preview files above that size anyway.</para>
329        </listitem>
330      </itemizedlist>
331    </section>
332  </section>
334  <section id="project.contributing">
335    <title>Contributing to MacPorts</title>
337    <para>You may contribute new ports and enhancements of any kind to already
338    existing ports using Trac tickets.</para>
340    <!-- Should we have similar sections about committing to base sources and
341    documentation, or alternatively add this to the following? -->
343    <section id="">
344      <title>New Ports</title>
346      <para>Ports are contributed by following these steps. See the <link
347        linkend="">Ticket Submission Guidelines</link> for
348      a description of all fields.</para>
350      <orderedlist>
351        <listitem>
352          <para>Please run
353            <programlisting><prompt>%%</prompt> <userinput>port lint --nitpick $portname</userinput></programlisting>
354            where <userinput>$portname</userinput> is the name of the port you
355            are submitting. Please fix any warnings and errors.</para>
356        </listitem>
358        <listitem>
359          <para>Create a Trac ticket.</para>
360        </listitem>
362        <listitem>
363          <para>Set the type to <guilabel>submission</guilabel>.</para>
364        </listitem>
366        <listitem>
367          <para>Set the component to <guilabel>ports</guilabel>.</para>
368        </listitem>
370        <listitem>
371          <para>Set the <guilabel>port</guilabel> field to the name of the new port.</para>
372        </listitem>
374        <listitem>
375          <para>Attach the <filename>Portfile</filename> and any required
376            patchfiles to the ticket.</para>
377        </listitem>
379        <listitem>
380          <para>If your ticket doesn't receive any attention within a few days
381            you may send an email to
382            <email></email> and request a
383            review and/or commit. Please include a link to the ticket.</para>
384        </listitem>
385      </orderedlist>
386    </section>
388    <section id="project.contributing.updates">
389      <title>Port Enhancements</title>
391      <para>Enhancements to existing ports may comprise new functionality for
392      a given port, bug fixes or even simple version updates. They should
393      always be contributed as patches against the current
394      <filename>Portfile</filename>. See the <link
395        linkend="">Ticket Submission Guidelines</link> for
396      a description of all fields.</para>
398      <orderedlist>
399        <listitem>
400          <para>Create a <filename>Portfile</filename> patch with your changes.
401            See <link linkend="development">Portfile Development</link> for
402            more information on how to edit Portfiles.</para>
403        </listitem>
405        <listitem>
406          <para>Please run
407            <programlisting><prompt>%%</prompt> <userinput>port lint --nitpick $portname</userinput></programlisting>
408            where <userinput>$portname</userinput> is the name of the port you
409            modified. Please fix any warnings and errors before submitting your
410            changes.</para>
411        </listitem>
413        <listitem>
414          <para>Create a Trac ticket.</para>
415        </listitem>
417        <listitem>
418          <para>Set the type to <guilabel>enhancement</guilabel> for
419          miscellaneous enhancements, to <guilabel>defect</guilabel> for bug
420          fixes, or to <guilabel>update</guilabel> for version updates.</para>
421        </listitem>
423        <listitem>
424          <para>Set the component to <guilabel>ports</guilabel>.</para>
425        </listitem>
427        <listitem>
428          <para>Set the <guilabel>port</guilabel> field to the name of the port you want to change.</para>
429        </listitem>
431        <listitem>
432          <para>Put the maintainer's email address into the
433            <guilabel>Cc</guilabel> field. You can use
434            <programlisting><prompt>%%</prompt> <userinput>port info --maintainer $portname</userinput></programlisting>
435            where <userinput>$portname</userinput> is the name of the port you
436            want to modify. Note that
437            <email></email> and
438            <email></email> are not real people and should thus not be Cc'd.</para>
439        </listitem>
441        <listitem>
442          <para>Attach your Portfile patch file and any new or changed patch
443            files to the ticket.</para>
444        </listitem>
446        <listitem>
447          <para>If your ticket doesn't receive any attention within a few days
448            you may send an email to
449            <email></email> and request a
450            review and/or commit. Please include a link to the ticket.</para>
451        </listitem>
452      </orderedlist>
453    </section>
455    <section id="project.contributing.maintaining">
456      <title>Becoming a Port Maintainer</title>
458      <para>MacPorts is always looking for people that want to take care of
459        a certain package. If you notice an outdated port, a bug in a port or
460        simply a port without maintainer that you are interested in, feel free
461        to volunteer as maintainer. To become a maintainer you need:</para>
463      <itemizedlist>
464        <listitem>
465          <para>An email address.</para>
466        </listitem>
467        <listitem>
468          <para>A copy of the <filename>Portfile</filename>. Do not worry if
469            you don't know where to find one yet. There's more documentation
470            on that below.</para>
471        </listitem>
472        <listitem>
473          <para>An account in the <ulink
474              url="">MacPorts Trac</ulink>,
475            preferably with the email address you want to use for your
476            port.</para>
477        </listitem>
478        <listitem>
479          <para>Interest in the software you want to maintain and some time.</para>
480        </listitem>
481      </itemizedlist>
483      <para>You do <emphasis>not</emphasis> need:</para>
484      <itemizedlist>
485        <listitem>
486          <para>Commit access to the MacPorts repository. Instead, you create
487            patches and open tickets in Trac. You can, however, <link
488              linkend="project.membership">apply for commit access</link>
489            once you have some experience in maintaining ports. In fact, we
490            would like to encourage you to apply after a few months.</para>
491        </listitem>
492        <listitem>
493          <para>Expert knowledge of the software you want to maintain or
494            experience in <filename>Portfile</filename> programming. You can
495            pick those up along the way. Your knowledge about the software
496            you want to maintain is probably more than what most other
497            MacPorts developers have, given the number of ports MacPorts has.
498            Consult <xref linkend="development" /> chapter and <xref
499              linkend="reference" /> on how to write
500            a <filename>Portfile</filename>. If your questions are not
501            answered there, please ask on the
502            <email></email> mailing
503            list.</para>
504        </listitem>
505      </itemizedlist>
507      <para>
508        To become the maintainer of a port, first check whether the port
509        already has a maintainer. Run
511        <programlisting><prompt>%%</prompt> <userinput>port info --maintainer $portname</userinput></programlisting>
513        where <userinput>$portname</userinput> is the name of the port you want
514        to maintain. If the output is
516        <screen>maintainer:</screen>
518        the port is unmaintained and you are more than welcome to take it over.
519        If the output lists a different email address, you can still
520        co-maintain the port, but you should contact the existing maintainer(s)
521        first.
522      </para>
524      <para>
525        Once you have verified that a port is unmaintained or the existing
526        maintainer has invited you to co-maintain the port of your choice,
527        follow these steps to become a maintainer:
528      </para>
530      <orderedlist>
531        <listitem>
532          <para>Locate the port's directory and make a copy. MacPorts can help
533            you locate the directory that contains the
534            <filename>Portfile</filename> by running <userinput>port dir
535              $portname</userinput>. Copy this directory to a separate location
536            (so you can easily generate a patch later) that is readable by the
537            macports user. In general, your home directory does not fulfill
538            that requirement, but <filename>/var/tmp</filename> does.
540            <programlisting><prompt>%%</prompt> <userinput>cp -r $(port dir $portname) /var/tmp</userinput></programlisting>
542            Check <filename>/var/tmp</filename> for the new directory. In most
543            cases, its name should be equal to the name of the port you want to
544            maintain. In those few cases where it is not (i.e., the so-called
545            <option>subports</option> feature is used), check the output of
546            <userinput>port dir $portname</userinput> for the correct name.
547          </para>
548        </listitem>
550        <listitem>
551          <para>Change to the new directory and run <userinput>port
552              info</userinput> to make sure everything went right. Note that
553            running any port command without a port name tries to use the
554            <filename>Portfile</filename> in the current directory. This is
555            very helpful when testing modifications or new ports, so keep this
556            in mind.
557          </para>
559          <programlisting><prompt>%%</prompt> <userinput>cd /var/tmp/$portname</userinput>
560<!--      --><prompt>%%</prompt> <userinput>port info</userinput><!--
561          --></programlisting>
563          <para>If you don't see info output for the port, but an error message
564            instead, it will usually be in the following form:</para>
566          <screen>Can't map the URL 'file://.' to a port description file ("couldn't read file "Portfile": permission denied").
567Please verify that the directory and portfile syntax are correct.
568To use the current port, you must be in a port's directory.</screen>
570          <para>Pay attention to the part in the brackets in the first line. It
571            will either contain a permission problem (in which case you need to
572            adjust the permissions of your <filename>Portfile</filename> and
573            the folders leading up to it), or a Tcl error message, in case of
574            syntax errors in the <filename>Portfile</filename>. Also check that
575            the copy of the working directory is in fact the current working
576            directory in your shell.</para>
577        </listitem>
579        <listitem>
580          <para>Open the <filename>Portfile</filename> in your favorite editor
581            and look for the line that starts with <option>maintainer</option>.
582            Delete <option>nomaintainer</option> from the line if it exists and
583            add your own email address in the form
584            <userinput>domain.tld:localpart</userinput>. The address is
585            obfuscated to prevent email harvesters from automatically grabbing
586            your address. If you want, you can start fixing bugs in the
587            <filename>Portfile</filename> as well.</para>
589          <para>At this point, please read <xref
590              linkend="project.update-policies.nonmaintainer" /> and
591            familiarize yourself with the meaning of
592            <option>openmaintainer</option>. Consider adding
593            <option>openmaintainer</option> to speed up and simplify small
594            updates of your port. If you decided to allow minor updates without
595            consultation, add <userinput>openmaintainer</userinput>, separated
596            with a space, to the <option>maintainer</option> line of the
597            <filename>Portfile</filename>.</para>
599          <para>Once you are done, save the file and verify the
600            <filename>Portfile</filename> structure using MacPorts' builtin
601            lint check:</para>
603          <programlisting><prompt>%%</prompt> <userinput>port lint --nitpick</userinput></programlisting>
605          <para>You will likely see at least one error:</para>
607          <screen>Error: Portfile parent directory tmp does not match primary category $XYZ</screen>
609          <para>You can safely ignore <emphasis>this</emphasis> message. It is
610            printed because the copy of the port's directory is not in
611            a directory named after the port's primary category, but in
612            <filename>/var/tmp</filename> instead. Please try to address all
613            other warnings and error messages, though. If you need help, feel
614            free to continue and add a note to the ticket you will
615            create asking for instructions.</para>
617          <para>Finally, run <userinput>port info</userinput> again. The
618            maintainers line in the output should now contain your email
619            address.</para>
621          <note>
622            <para>If you made changes other than the maintainer line, you might
623              want to test build and installation as well. To do that, run
624              <userinput>sudo port destroot</userinput> in the port's
625              directory. If you see</para>
627            <screen>Error: Unable to execute port: Could not open file: /private/var/tmp/somewhere/Portfile</screen>
629            <para>check the permissions of the <filename>Portfile</filename> and
630              all folders above it. They must be readable by the
631              <option>macports</option> user. The easiest way to ensure this is to run</para>
633            <programlisting><prompt>%%</prompt> <userinput>chmod -R go+rX /var/tmp/$portname</userinput></programlisting>
635            <para>If the port fails to build, see the
636              <filename>main.log</filename> referenced in the error message for
637              details. If the build completes successfully, run <userinput>sudo
638                port clean</userinput> to clean up all leftovers.</para>
639          </note>
640        </listitem>
642        <listitem>
643          <para>Create a patch from the changes you made to the
644            <filename>Portfile</filename> and possible related files. To do that, run</para>
646          <programlisting><prompt>%%</prompt> <userinput>diff -uR $(port dir $portname) . > change-$portname-maintainer.diff</userinput></programlisting>
648          <para>in the directory where you edited the
649            <filename>Portfile</filename>. You can inspect the generated
650            unified diff in
651            <filename>change-$portname-maintainer.diff</filename> if you
652            want.</para>
653        </listitem>
655        <listitem>
656          <para>If you are only changing the maintainer, <ulink
657              url="">file a new ticket in
658              Trac</ulink>. Set <guilabel>type</guilabel> to
659            <guilabel>enhancement</guilabel>. Leave the
660            <guilabel>milestone</guilabel> field empty. If you added yourself
661            as co-maintainer, add the other maintainers in the
662            <guilabel>Cc</guilabel> field. Finally, fill in the
663            <guilabel>port</guilabel> field, set <guilabel>keywords</guilabel>
664            to <userinput>haspatch</userinput> (because you are attaching
665            a patch), check the box that you want to attach files to the ticket
666            and submit. After submission, attach the patch you created in the
667            previous step.</para>
669          <para>If you are also fixing a bug, attach a separate patch for that
670            change to the same ticket. If you are fixing a bug that already has
671            a ticket, attach a patch fixing the bug there and file the
672            maintainer change in a separate ticket (with a separate patch) as
673            discussed above. In general, please create a separate patch for
674            each semantic change. Doing so simplifies reviewing. It enables
675            each independent change to be accepted without worries about
676            conflicts that sometimes arise when several changes are rolled into
677            one patch. Do not worry that you cannot change the
678            <guilabel>keywords</guilabel> to <userinput>haspatch</userinput> on
679            existing tickets.</para>
680        </listitem>
682        <listitem>
683          <para>If your ticket doesn't receive any attention within a few days
684            you may send an email to
685            <email></email> and request
686            a review and/or commit. Please include a link to the ticket.</para>
687        </listitem>
688      </orderedlist>
690      <para>Once you are the maintainer for a port, all new tickets for this
691        port will be assigned to you. You are expected to take a look at these
692        tickets, give advice and try to debug problems. If you are stuck, do
693        not hesitate to ask on the
694        <email></email> list.</para>
695    </section>
696  </section>
698  <section id="project.update-policies">
699    <title>Port Update Policies</title>
701    <para>Port maintainers normally are given commit privileges to the
702    Subversion repository so they can make updates to their own ports as
703    described in <xref linkend="project.membership" />.
704    However, The MacPorts Project does not restrict commit privileges for
705    maintainers, so before a person other than a port's maintainer updates a
706    port it is a good practice to inform a port's maintainer. See details
707    below.</para>
709    <section id="project.update-policies.nonmaintainer">
710      <title>Non-Maintainer Port Updates</title>
712      <para>If you have a port update or bugfix for a port you do not
713      maintain, to respect the rights of the port maintainer you should follow
714      the following guidelines:</para>
716      <orderedlist>
717        <listitem>
718          <para>If a port's maintainer is
719          <email></email>, you may feel free to make
720          updates and/or take maintainership of the port.</para>
721        </listitem>
723        <listitem>
724          <para>If a port's maintainer contains the address
725          <email></email>, this means that the
726          author allows minor updates to the port without contacting him
727          first. But permission should still be sought for major
728          changes.</para>
729        </listitem>
731        <listitem>
732          <para>Create patch file(s) as necessary, attach them to a Trac
733          ticket, and assign the ticket to the maintainer (or Cc him or
734          her, if you are unable to assign tickets).</para>
735        </listitem>
737        <listitem>
738          <para>Wait for a response from the maintainer. The maintainer should
739          apply the patches and close the ticket within 72 hours.</para>
740        </listitem>
741      </orderedlist>
743      <para>However, for maintained ports without
744      <email></email>, there are some conditions
745      under which maintainer permission may be waived:</para>
747      <itemizedlist>
748        <listitem>
749          <para>If the maintainer does not respond within 72 hours, you or
750          another committer may review the patches and update the port. The log
751          message of this commit must explain that you are taking advantage of
752          maintainer timeout and include a reference to the ticket. If you are
753          not a committer you may send an email to
754          <email></email> and request the
755          updates be committed.</para>
756        </listitem>
758        <listitem>
759          <para>A port is abandoned by its current maintainer. A port against
760          which a Port Abandoned ticket has been filed (see below) can be
761          updated without contacting the maintainer.</para>
762        </listitem>
764        <listitem>
765          <para>A critical port is broken that affects many users.</para>
766        </listitem>
767      </itemizedlist>
768    </section>
770    <section id="project.update-policies.abandonment">
771      <title>Port Abandonment</title>
773      <para>A port may be considered abandoned if any of the following apply:</para>
774        <itemizedlist>
775        <listitem><para>A bug has not been acknowledged for more than three weeks
776            after a ticket is filed.</para></listitem>
777        <listitem><para>All tickets filed against the port have been resolved
778            with no input from the maintainer, after the 72-hour timeout,
779            for a significant period of time (at least three weeks). This
780            needs to involve a reasonable number of tickets; one timeout
781            doesn't make a port abandoned.</para></listitem>
782        <listitem><para>The listed maintainer address bounces, and no alternate way
783            of contacting the maintainer is known.</para></listitem>
784        </itemizedlist>
785      <para>If you wish to initiate the Port Abandonment
786      protocol and optionally volunteer as the new maintainer:</para>
788      <orderedlist>
789        <listitem>
790          <para>File a new Trac ticket with the summary line: [Port
791          Abandoned] <guilabel>portname</guilabel>.</para>
792        </listitem>
794        <listitem>
795          <para>The ticket should be assigned to the maintainer. Non-macports team members should Cc the maintainer.</para>
796        </listitem>
798        <listitem>
799          <para>Set the ticket Type to Defect.</para>
800        </listitem>
802        <listitem>
803          <para>In the Description field, refer to any unacknowledged ticket(s).</para>
804        </listitem>
806        <listitem>
807          <para>In the Port field, indicate which port is abandoned.</para>
808        </listitem>
810        <listitem>
811          <para>The Port Abandoned ticket may be closed when the new
812          maintainer is assigned, and the original ticket(s) with the updates may
813          be resolved as usual. All other tickets assigned to the former maintainer should be set to
814 as owner. The Port Abandoned ticket should stay open
815          for the usual 72-hour timeout period, to give the maintainer one last chance
816          to indicate that they have not actually abandoned the port.</para>
817        </listitem>
818      </orderedlist>
819    </section>
820  </section>
822  <section id="project.membership">
823    <title>MacPorts Membership</title>
825    <para>A requirement for a person to become a MacPorts committer is to
826    first become involved and contribute to the project. This may be done by
827    having a record of contribution to the project in several of the following
828    ways:</para>
830    <itemizedlist>
831      <listitem>
832        <para>Contributing new ports.</para>
833      </listitem>
835      <listitem>
836        <para>Fixing bugs in existing ports.</para>
837      </listitem>
839      <listitem>
840        <para>Volunteering as a maintainer of non-maintained ports.</para>
841      </listitem>
843      <listitem>
844        <para>Involvement on MacPorts development and/or user support mailing lists.</para>
845      </listitem>
847      <listitem>
848        <para>Contributing with documentation.</para>
849      </listitem>
850    </itemizedlist>
852    <para>To apply for MacPorts commit rights, send a brief email to the
853    PortMgr team at <email></email> entitled
854    &ldquo;Commit access: <replaceable>Your Name</replaceable>&rdquo; with the
855    following contents:</para>
857    <itemizedlist>
858      <listitem>
859        <para>a description of your application and why you think you deserve
860        commit rights. Include evidence of contributions to MacPorts as described
861        above; at best add direct links to Trac tickets or Trac searches that
862        make the review easier for the PortMgr team.</para>
863      </listitem>
865      <listitem>
866        <para>the identity you'd like to use as a member of the project, a.k.a. the
867        &ldquo;handle&rdquo;, as part of your <literal><replaceable>handle</replaceable></literal>
868        alias.</para>
869      </listitem>
871      <listitem>
872        <para>a real e-mail address to which you'd like your MacPorts alias to forward.</para>
873      </listitem>
874    </itemizedlist>
876    <para>The PortMgr team will consider all applications and provide an appropriate
877    response as soon as they get to it.</para>
879  </section>
881  <section id="project.portmgr">
882    <title>The PortMgr Team</title>
884    <para>The MacPorts PortMgr team is the steering group for The MacPorts
885    Project. Its membership is usually determined by public elections among
886    project members; the current members of the team can be found on the
887    <ulink url="">MacPorts
888    Developers wiki page</ulink>.</para>
890    <para>They are responsible for matters such as:</para>
892    <itemizedlist>
893        <listitem>
894          <para>approving new project members (i.e., granting commit
895          rights);</para>
896        </listitem>
898        <listitem>
899          <para>setting general guidelines for the project;</para>
900        </listitem>
902        <listitem>
903          <para>dispute resolution;</para>
904        </listitem>
906        <listitem>
907          <para>managing the projects infrastructure; and</para>
908        </listitem>
910        <listitem>
911          <para>engineering releases.</para>
912        </listitem>
913      </itemizedlist>
915  </section>
Note: See TracBrowser for help on using the repository browser.