Changeset 122854 for trunk/doc-new

Jul 31, 2014, 9:24:25 PM (6 years ago)

guide: add section on how to become a port's maintainer

1 edited


  • trunk/doc-new/guide/xml/project.xml

    r122834 r122854  
    449449      </orderedlist>
    450450    </section>
     452    <section id="project.contributing.maintaining">
     453      <title>Becoming a Port Maintainer</title>
     455      <para>MacPorts is always looking for people that want to take care of
     456        a certain package. If you notice an outdated port, a bug in a port or
     457        simply a port without maintainer that you are interested in, feel free
     458        to volunteer as maintainer. To become a maintainer you need:</para>
     460      <itemizedlist>
     461        <listitem>
     462          <para>An email address.</para>
     463        </listitem>
     464        <listitem>
     465          <para>A copy of the <filename>Portfile</filename>. Do not worry if
     466            you don't know where to find one yet. There's more documentation
     467            on that below.</para>
     468        </listitem>
     469        <listitem>
     470          <para>An account in the <ulink
     471              url="">MacPorts Trac</ulink>,
     472            preferrably with the email address you want to use for your
     473            port.</para>
     474        </listitem>
     475        <listitem>
     476          <para>Interest in the software you want to maintain and some time.</para>
     477        </listitem>
     478      </itemizedlist>
     480      <para>You do <emphasis>not</emphasis> need:</para>
     481      <itemizedlist>
     482        <listitem>
     483          <para>Commit access to the MacPorts repository. Instead, you create
     484            patches and open tickets in Trac. You can, however, <link
     485              linkend="project.membership">apply for commit access</link>
     486            once you have some experience in maintaining ports. In fact, we
     487            would like to encourage you to apply after a few months.</para>
     488        </listitem>
     489        <listitem>
     490          <para>Expert knowldge of the software you want to maintain or
     491            experience in <filename>Portfile</filename> programming. You can
     492            pick those up along the way. Your knowledge about the software
     493            you want to maintain is probably more than what most other
     494            MacPorts developers have, given the number of ports MacPorts has.
     495            Consult <xref linkend="development" /> chapter and <xref
     496              linkend="reference" /> on how to write
     497            a <filename>Portfile</filename>. If your questions are not
     498            answered there, please ask on the
     499            <email></email> mailing
     500            list.</para>
     501        </listitem>
     502      </itemizedlist>
     504      <para>
     505        To become the maintainer of a port, first check whether the port
     506        already has a maintainer. Run
     508        <programlisting><prompt>%%</prompt> <userinput>port info --maintainer $portname</userinput></programlisting>
     510        where <userinput>$portname</userinput> is the name of the port you want
     511        to maintain. If the output is
     513        <screen>maintainer:</screen>
     515        the port is unmaintained and you are more than welcome to take it over.
     516        If the output lists a different email address, you can still
     517        co-maintain the port, but you should contact the existing maintainer(s)
     518        first.
     519      </para>
     521      <para>
     522        Once you have verified that a port is unmaintained or the existing
     523        maintainer has invited you to co-maintain the port of your choice,
     524        follow these steps to become a maintainer:
     525      </para>
     527      <orderedlist>
     528        <listitem>
     529          <para>Locate the port's directory and make a copy. MacPorts can help
     530            you locate the directory that contains the
     531            <filename>Portfile</filename> by running <userinput>port dir
     532              $portname</userinput>. Copy this directory to a separate location
     533            (so you can easily generate a patch later) that is readable by the
     534            macports user. In general, your home directory does not fulfill
     535            that requirement, but <filename>/var/tmp</filename> does.
     537            <programlisting><prompt>%%</prompt> <userinput>cp -r $(port dir $portname) /var/tmp</userinput></programlisting>
     539            Check <filename>/var/tmp</filename> for the new directory. In most
     540            cases, its name should be equal to the name of the port you want to
     541            maintain. In those few cases where it is not (i.e., the so-called
     542            <option>subports</option> feature is used), check the output of
     543            <userinput>port dir $portname</userinput> for the correct name.
     544          </para>
     545        </listitem>
     547        <listitem>
     548          <para>Change to the new directory and run <userinput>port
     549              info</userinput> to make sure everything went right. Note that
     550            running any port command without a port name tries to use the
     551            <filename>Portfile</filename> in the current directory. This is
     552            very helpful when testing modifications or new ports, so keep this
     553            in mind.
     554          </para>
     556          <programlisting><prompt>%%</prompt> <userinput>cd /var/tmp/$portname</userinput>
     557<!--      --><prompt>%%</prompt> <userinput>port info</userinput><!--
     558          --></programlisting>
     560          <para>If you don't see info output for the port, but an error message
     561            instead, it will usually be in the following form:</para>
     563          <screen>Can't map the URL 'file://.' to a port description file ("couldn't read file "Portfile": permission denied").
     564Please verify that the directory and portfile syntax are correct.
     565To use the current port, you must be in a port's directory.</screen>
     567          <para>Pay attention to the part in the brackets in the first line. It
     568            will either contain a permission problem (in which case you need to
     569            adjust the permissions of your <filename>Portfile</filename> and
     570            the folders leading up to it), or a Tcl error message, in case of
     571            syntax errors in the <filename>Portfile</filename>. Also check that
     572            the copy of the working directory is in fact the current working
     573            directory in your shell.</para>
     574        </listitem>
     576        <listitem>
     577          <para>Open the <filename>Portfile</filename> in your favorite editor
     578            and look for the line that starts with <option>maintainer</option>.
     579            Delete <option>nomaintainer</option> from the line if it exists and
     580            add your own email address in the form
     581            <userinput>domain.tld:localpart</userinput>. The address is
     582            obfuscated to prevent email harvesters from automatically grabbing
     583            your address. If you want, you can start fixing bugs in the
     584            <filename>Portfile</filename> as well.</para>
     586          <para>At this point, please read <xref
     587              linkend="project.update-policies.nonmaintainer" /> and
     588            familiarize yourself with the meaning of
     589            <option>openmaintainer</option>. Consider adding
     590            <option>openmaintainer</option> to speed up and simplify small
     591            updates of your port. If you decided to allow minor updates without
     592            consultation, add <userinput>openmaintainer</userinput>, separated
     593            with a space, to the <option>maintainer</option> line of the
     594            <filename>Portfile</filename>.</para>
     596          <para>Once you are done, save the file verify the
     597            <filename>Portfile</filename> structure using MacPorts' builtin
     598            lint check:</para>
     600          <programlisting><prompt>%%</prompt> <userinput>port lint --nitpick</userinput></programlisting>
     602          <para>You will likely see at least one error:</para>
     604          <screen>Error: Portfile parent directory tmp does not match primary category $XYZ</screen>
     606          <para>You can safely ignore <emphasis>this</emphasis> message. It is
     607            printed because the copy of the port's directory is not in
     608            a directory named after the port's primary category, but in
     609            <filename>/var/tmp</filename> instead. Please try to address all
     610            other warnings and error messages, though. If you need help, feel
     611            free to continue and add a note to the ticket you will
     612            create asking for instructions.</para>
     614          <para>Finally, run <userinput>port info</userinput> again. The
     615            maintainers line in the output should now contain your email
     616            address.</para>
     618          <note>
     619            <para>If you made changes other than the maintainer line, you might
     620              want to test build and installation as well. To do that, run
     621              <userinput>sudo port destroot</userinput> in the port's
     622              directory. If you see</para>
     624            <screen>Error: Unable to execute port: Could not open file: /private/var/tmp/somewhere/Portfile</screen>
     626            <para>check the permissions of the <filename>Portfile</filename> and
     627              all folders above it. They must be readable by the
     628              <option>macports</option> user. The easiest way to ensure this is to run</para>
     630            <programlisting><prompt>%%</prompt> <userinput>chmod -R go+rX /var/tmp/$portname</userinput></programlisting>
     632            <para>If the port fails to build, see the
     633              <filename>main.log</filename> referenced in the error message for
     634              details. If the build completes successfully, run <userinput>sudo
     635                port clean</userinput> to clean up all leftovers.</para>
     636          </note>
     637        </listitem>
     639        <listitem>
     640          <para>Create a patch from the changes you made to the
     641            <filename>Portfile</filename> and possible related files. To do that, run</para>
     643          <programlisting><prompt>%%</prompt> <userinput>diff -uR $(port dir $portname) . > change-$portname-maintainer.diff</userinput></programlisting>
     645          <para>in the directory where you edited the
     646            <filename>Portfile</filename>. You can inspect the generated
     647            unified diff in
     648            <filename>change-$portname-maintainer.diff</filename> if you
     649            want.</para>
     650        </listitem>
     652        <listitem>
     653          <para>Now, <ulink url="">file
     654              a new ticket in Trac</ulink>. Set <guilabel>type</guilabel> to
     655            <guilabel>request</guilabel> if you only changed the maintainer and
     656            an appropriate other type if you also fixed a bug or enhanced or
     657            updated the port. Leave the <guilabel>milestone</guilabel> field
     658            empty. If you added yourself as co-maintainer, add the other
     659            maintainers in the <guilabel>Cc</guilabel> field. Finally, fill in
     660            the <guilabel>port</guilabel> field, set
     661            <guilabel>keywords</guilabel> to <userinput>haspatch</userinput>
     662            (because you are attaching a patch), check the box that you want to
     663            attach files to the ticket and submit. After submission, attach the
     664            patch you created in the previous step.</para>
     665        </listitem>
     667        <listitem>
     668          <para>If your ticket doesn't receive any attention within a few days
     669            (for example, because the port you are trying to modify does not
     670            have a maintainer), you may email
     671            <email></email> and request
     672            a review and/or commit.</para>
     673        </listitem>
     674      </orderedlist>
     676      <para>Once you are the maintainer for a port, all new tickets for this
     677        port will be assigned to you. You are expected to take a look at these
     678        tickets, give advice and try to debug problems. If you are stuck, do
     679        not hesitate to ask on the
     680        <email></email> list.</para>
     681    </section>
    451682  </section>
Note: See TracChangeset for help on using the changeset viewer.