Changeset 122854 for trunk/doc-new


Ignore:
Timestamp:
Jul 31, 2014, 9:24:25 PM (4 years ago)
Author:
cal@…
Message:

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

File:
1 edited

Legend:

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

    r122834 r122854  
    449449      </orderedlist>
    450450    </section>
     451
     452    <section id="project.contributing.maintaining">
     453      <title>Becoming a Port Maintainer</title>
     454
     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>
     459
     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="https://trac.macports.org/">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>
     479
     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>macports-dev@lists.macosforge.org</email> mailing
     500            list.</para>
     501        </listitem>
     502      </itemizedlist>
     503
     504      <para>
     505        To become the maintainer of a port, first check whether the port
     506        already has a maintainer. Run
     507
     508        <programlisting><prompt>%%</prompt> <userinput>port info --maintainer $portname</userinput></programlisting>
     509
     510        where <userinput>$portname</userinput> is the name of the port you want
     511        to maintain. If the output is
     512
     513        <screen>maintainer: nomaintainer@macports.org</screen>
     514
     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>
     520
     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>
     526
     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.
     536
     537            <programlisting><prompt>%%</prompt> <userinput>cp -r $(port dir $portname) /var/tmp</userinput></programlisting>
     538
     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>
     546
     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>
     555
     556          <programlisting><prompt>%%</prompt> <userinput>cd /var/tmp/$portname</userinput>
     557<!--      --><prompt>%%</prompt> <userinput>port info</userinput><!--
     558          --></programlisting>
     559
     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>
     562
     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>
     566
     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>
     575
     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>
     585
     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>
     595
     596          <para>Once you are done, save the file verify the
     597            <filename>Portfile</filename> structure using MacPorts' builtin
     598            lint check:</para>
     599
     600          <programlisting><prompt>%%</prompt> <userinput>port lint --nitpick</userinput></programlisting>
     601
     602          <para>You will likely see at least one error:</para>
     603
     604          <screen>Error: Portfile parent directory tmp does not match primary category $XYZ</screen>
     605
     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>
     613
     614          <para>Finally, run <userinput>port info</userinput> again. The
     615            maintainers line in the output should now contain your email
     616            address.</para>
     617
     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>
     623
     624            <screen>Error: Unable to execute port: Could not open file: /private/var/tmp/somewhere/Portfile</screen>
     625
     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>
     629
     630            <programlisting><prompt>%%</prompt> <userinput>chmod -R go+rX /var/tmp/$portname</userinput></programlisting>
     631
     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>
     638
     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>
     642
     643          <programlisting><prompt>%%</prompt> <userinput>diff -uR $(port dir $portname) . > change-$portname-maintainer.diff</userinput></programlisting>
     644
     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>
     651
     652        <listitem>
     653          <para>Now, <ulink url="https://trac.macports.org/newticket">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>
     666
     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>macports-dev@lists.macosforge.org</email> and request
     672            a review and/or commit.</para>
     673        </listitem>
     674      </orderedlist>
     675
     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>macports-dev@lists.macosforge.org</email> list.</para>
     681    </section>
    451682  </section>
    452683
Note: See TracChangeset for help on using the changeset viewer.