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

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

doc/doc-new: Clarify updating a single port may lead to errors, closes #48909

File size: 38.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  <section id="project.tickets">
8    <title>Using Trac for Tickets</title>
9
10    <para>The MacPorts Project uses a system called <ulink
11    url="http://trac.edgewall.org/">Trac</ulink> to file tickets to report bugs
12    and enhancement requests. Trac also provides an interface to browse the
13    <ulink url="https://trac.macports.org/browser/">MacPorts
14    Subversion repository</ulink>. Though anyone may search Trac for tickets,
15    you must <ulink
16    url="https://trac.macports.org/auth/register/">register</ulink> for a Trac
17    account to create tickets.</para>
18
19    <section id="project.tickets.prerequisites">
20      <title>Before Filing a New Ticket</title>
21
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="https://trac.macports.org/wiki/ProblemHotlist">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="https://trac.macports.org/search?portsummarysearch=on">the search page</ulink></para></listitem>
54                <listitem><para>browsing the list of <ulink url="https://trac.macports.org/report">categorized reports</ulink></para></listitem>
55                <listitem><para>making an advanced search by constructing a <ulink url="https://trac.macports.org/query">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>
82
83    <section id="project.tickets.creating">
84      <title>Creating Trac Tickets</title>
85
86      <para>Once you are logged into Trac, you may click <ulink
87      url="https://trac.macports.org/newticket">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>
93
94      <screenshot>
95        <screeninfo>A new Trac ticket</screeninfo>
96
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>
107
108    <section id="project.tickets.guidelines">
109      <title>Trac Ticket Guidelines</title>
110
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>
114
115      <itemizedlist>
116        <listitem>
117          <para><guilabel>Summary:</guilabel>
118          <replaceable>[port]</replaceable>
119          <replaceable>[version]</replaceable> <replaceable>[concise
120          description]</replaceable></para>
121
122          <itemizedlist>
123            <listitem>
124              <para>Example: "rrdtool @1.2.23 +python Configure error - build
125              failure"</para>
126            </listitem>
127          </itemizedlist>
128        </listitem>
129
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="https://trac.macports.org/wiki/WikiFormatting">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>
140
141          <literallayout>
142{{{
143<replaceable>your error message here</replaceable>
144}}}
145          </literallayout>
146
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>
153
154        </listitem>
155
156        <listitem>
157          <para><guilabel>Type:</guilabel> There are five types of
158          tickets.</para>
159
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>
165
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>
171
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>
177
178            <listitem>
179              <para><guimenu>submission</guimenu> - Tickets created to submit
180              Portfiles for software not currently available in MacPorts.
181              </para>
182            </listitem>
183
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>
190
191        <listitem>
192          <para><guilabel>Priority:</guilabel> Assign a priority level to the
193          ticket.</para>
194
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>
201
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>
207
208            <listitem>
209              <para><guimenu>Low</guimenu> - For mostly cosmetic improvements,
210              documentation corrections/improvements, etc.</para>
211            </listitem>
212
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>
219
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>
226
227        <listitem>
228          <para><guilabel>Component:</guilabel> Set what part of the MacPorts
229          Project the ticket is to be filed against.</para>
230
231          <itemizedlist>
232            <listitem>
233              <para><guimenu>base</guimenu> - Tickets related to MacPorts base
234              code.</para>
235            </listitem>
236
237            <listitem>
238              <para><guimenu>guide</guimenu> - Documentation enhancements and
239              error corrections, or patches to the MacPorts Guide.</para>
240            </listitem>
241
242            <listitem>
243              <para><guimenu>ports</guimenu> - Tickets related to
244              ports.</para>
245            </listitem>
246
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>
252
253            <listitem>
254              <para><guimenu>website</guimenu> - MacPorts website enhancements
255              and error corrections.</para>
256            </listitem>
257
258            <listitem>
259              <para><guimenu>wiki</guimenu> - MacPorts Wiki enhancements and
260              error corrections.</para>
261            </listitem>
262          </itemizedlist>
263        </listitem>
264
265        <listitem>
266          <para><guilabel>Version:</guilabel> Select the MacPorts version you
267          are using when it is applicable.</para>
268        </listitem>
269
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>
280
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>you@example.org, maintainer@macports.org</literal>).</para>
287
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>
296
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>
301
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>openmaintainer@macports.org</email> if it appears.
309          If the maintainer's email address is
310          <email>nomaintainer@macports.org</email>, leave the field
311          blank.</para>
312        </listitem>
313
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>
319
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>
333
334  <section id="project.contributing">
335    <title>Contributing to MacPorts</title>
336
337    <para>You may contribute new ports and enhancements of any kind to already
338    existing ports using Trac tickets.</para>
339
340    <!-- Should we have similar sections about committing to base sources and
341    documentation, or alternatively add this to the following? -->
342
343    <section id="project.contributing.new">
344      <title>New Ports</title>
345
346      <para>Ports are contributed by following these steps. See the <link
347        linkend="project.tickets">Ticket Submission Guidelines</link> for
348      a description of all fields.</para>
349
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>
357
358        <listitem>
359          <para>Create a Trac ticket.</para>
360        </listitem>
361
362        <listitem>
363          <para>Set the type to <guilabel>submission</guilabel>.</para>
364        </listitem>
365
366        <listitem>
367          <para>Set the component to <guilabel>ports</guilabel>.</para>
368        </listitem>
369
370        <listitem>
371          <para>Set the <guilabel>port</guilabel> field to the name of the new port.</para>
372        </listitem>
373
374        <listitem>
375          <para>Attach the <filename>Portfile</filename> and any required
376            patchfiles to the ticket.</para>
377        </listitem>
378
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>macports-dev@lists.macosforge.org</email> and request a
383            review and/or commit.</para>
384        </listitem>
385      </orderedlist>
386    </section>
387
388    <section id="project.contributing.updates">
389      <title>Port Enhancements</title>
390
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="project.tickets">Ticket Submission Guidelines</link> for
396      a description of all fields.</para>
397
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>
404
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>
412
413        <listitem>
414          <para>Create a Trac ticket.</para>
415        </listitem>
416
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>
422
423        <listitem>
424          <para>Set the component to <guilabel>ports</guilabel>.</para>
425        </listitem>
426
427        <listitem>
428          <para>Set the <guilabel>port</guilabel> field to the name of the port you want to change.</para>
429        </listitem>
430
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>openmaintainer@macports.org</email> and
438            <email>nomaintainer@macports.org</email> are not real people and should thus not be Cc'd.</para>
439        </listitem>
440
441        <listitem>
442          <para>Attach your Portfile patch file and any new or changed patch
443            files to the ticket.</para>
444        </listitem>
445
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>macports-dev@lists.macosforge.org</email> and request a
450            review and/or commit.</para>
451        </listitem>
452      </orderedlist>
453    </section>
454
455    <section id="project.contributing.maintaining">
456      <title>Becoming a Port Maintainer</title>
457
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>
462
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="https://trac.macports.org/">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>
482
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>macports-dev@lists.macosforge.org</email> mailing
503            list.</para>
504        </listitem>
505      </itemizedlist>
506
507      <para>
508        To become the maintainer of a port, first check whether the port
509        already has a maintainer. Run
510
511        <programlisting><prompt>%%</prompt> <userinput>port info --maintainer $portname</userinput></programlisting>
512
513        where <userinput>$portname</userinput> is the name of the port you want
514        to maintain. If the output is
515
516        <screen>maintainer: nomaintainer@macports.org</screen>
517
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>
523
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>
529
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.
539
540            <programlisting><prompt>%%</prompt> <userinput>cp -r $(port dir $portname) /var/tmp</userinput></programlisting>
541
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>
549
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>
558
559          <programlisting><prompt>%%</prompt> <userinput>cd /var/tmp/$portname</userinput>
560<!--      --><prompt>%%</prompt> <userinput>port info</userinput><!--
561          --></programlisting>
562
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>
565
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>
569
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>
578
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>
588
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>
598
599          <para>Once you are done, save the file and verify the
600            <filename>Portfile</filename> structure using MacPorts' builtin
601            lint check:</para>
602
603          <programlisting><prompt>%%</prompt> <userinput>port lint --nitpick</userinput></programlisting>
604
605          <para>You will likely see at least one error:</para>
606
607          <screen>Error: Portfile parent directory tmp does not match primary category $XYZ</screen>
608
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>
616
617          <para>Finally, run <userinput>port info</userinput> again. The
618            maintainers line in the output should now contain your email
619            address.</para>
620
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>
626
627            <screen>Error: Unable to execute port: Could not open file: /private/var/tmp/somewhere/Portfile</screen>
628
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>
632
633            <programlisting><prompt>%%</prompt> <userinput>chmod -R go+rX /var/tmp/$portname</userinput></programlisting>
634
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>
641
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>
645
646          <programlisting><prompt>%%</prompt> <userinput>diff -uR $(port dir $portname) . > change-$portname-maintainer.diff</userinput></programlisting>
647
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>
654
655        <listitem>
656          <para>If you are only changing the maintainer, <ulink
657              url="https://trac.macports.org/newticket">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>
668
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>
681
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>macports-dev@lists.macosforge.org</email> and request
686            a review and/or commit.</para>
687        </listitem>
688      </orderedlist>
689
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>macports-dev@lists.macosforge.org</email> list.</para>
695    </section>
696  </section>
697
698  <section id="project.update-policies">
699    <title>Port Update Policies</title>
700
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>
708
709    <section id="project.update-policies.nonmaintainer">
710      <title>Non-Maintainer Port Updates</title>
711
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>
715
716      <orderedlist>
717        <listitem>
718          <para>If a port's maintainer is
719          <email>nomaintainer@macports.org</email>, you may feel free to make
720          updates and/or take maintainership of the port.</para>
721        </listitem>
722
723        <listitem>
724          <para>If a port's maintainer contains the address
725          <email>openmaintainer@macports.org</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>
730
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>
736
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>
742
743      <para>However, for maintained ports without
744      <email>openmaintainer@macports.org</email>, there are some conditions
745      under which maintainer permission may be waived:</para>
746
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>macports-dev@lists.macosforge.org</email> and request the
755          updates be committed.</para>
756        </listitem>
757
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>
763
764        <listitem>
765          <para>A critical port is broken that affects many users.</para>
766        </listitem>
767      </itemizedlist>
768    </section>
769
770    <section id="project.update-policies.abandonment">
771      <title>Port Abandonment</title>
772
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>
787
788      <orderedlist>
789        <listitem>
790          <para>File a new Trac ticket with the summary line: [Port
791          Abandoned] <guilabel>portname</guilabel>.</para>
792        </listitem>
793
794        <listitem>
795          <para>The ticket should be assigned to the maintainer. Non-macports team members should Cc the maintainer.</para>
796        </listitem>
797
798        <listitem>
799          <para>Set the ticket Type to Defect.</para>
800        </listitem>
801
802        <listitem>
803          <para>In the Description field, refer to any unacknowledged ticket(s).</para>
804        </listitem>
805
806        <listitem>
807          <para>In the Port field, indicate which port is abandoned.</para>
808        </listitem>
809
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          macports-tickets@lists.macosforge.org 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>
821
822  <section id="project.membership">
823    <title>MacPorts Membership</title>
824
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>
829
830    <itemizedlist>
831      <listitem>
832        <para>Contributing new ports.</para>
833      </listitem>
834
835      <listitem>
836        <para>Fixing bugs in existing ports.</para>
837      </listitem>
838
839      <listitem>
840        <para>Volunteering as a maintainer of non-maintained ports.</para>
841      </listitem>
842
843      <listitem>
844        <para>Involvement on MacPorts development and/or user support mailing lists.</para>
845      </listitem>
846
847      <listitem>
848        <para>Contributing with documentation.</para>
849      </listitem>
850    </itemizedlist>
851
852    <para>To apply for MacPorts commit rights, send a brief email to the
853    PortMgr team at <email>macports-mgr@lists.macosforge.org</email> entitled
854    &ldquo;Commit access: <replaceable>Your Name</replaceable>&rdquo; with the
855    following contents:</para>
856
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>
864
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>@macports.org</literal>
868        alias.</para>
869      </listitem>
870
871      <listitem>
872        <para>a real e-mail address to which you'd like your MacPorts alias to forward.</para>
873      </listitem>
874    </itemizedlist>
875
876    <para>The PortMgr team will consider all applications and provide an appropriate
877    response as soon as they get to it.</para>
878
879  </section>
880
881  <section id="project.portmgr">
882    <title>The PortMgr Team</title>
883
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="https://trac.macports.org/wiki/MacPortsDevelopers">MacPorts
888    Developers wiki page</ulink>.</para>
889
890    <para>They are responsible for matters such as:</para>
891
892    <itemizedlist>
893        <listitem>
894          <para>approving new project members (i.e., granting commit
895          rights);</para>
896        </listitem>
897
898        <listitem>
899          <para>setting general guidelines for the project;</para>
900        </listitem>
901
902        <listitem>
903          <para>dispute resolution;</para>
904        </listitem>
905
906        <listitem>
907          <para>managing the projects infrastructure; and</para>
908        </listitem>
909
910        <listitem>
911          <para>engineering releases.</para>
912        </listitem>
913      </itemizedlist>
914
915  </section>
916</chapter>
Note: See TracBrowser for help on using the repository browser.