[122854] trunk/doc-new/guide/xml/project.xml
cal at macports.org
cal at macports.org
Thu Jul 31 14:24:25 PDT 2014
Revision: 122854
https://trac.macports.org/changeset/122854
Author: cal at macports.org
Date: 2014-07-31 14:24:25 -0700 (Thu, 31 Jul 2014)
Log Message:
-----------
guide: add section on how to become a port's maintainer
Modified Paths:
--------------
trunk/doc-new/guide/xml/project.xml
Modified: trunk/doc-new/guide/xml/project.xml
===================================================================
--- trunk/doc-new/guide/xml/project.xml 2014-07-31 21:07:55 UTC (rev 122853)
+++ trunk/doc-new/guide/xml/project.xml 2014-07-31 21:24:25 UTC (rev 122854)
@@ -448,6 +448,237 @@
</listitem>
</orderedlist>
</section>
+
+ <section id="project.contributing.maintaining">
+ <title>Becoming a Port Maintainer</title>
+
+ <para>MacPorts is always looking for people that want to take care of
+ a certain package. If you notice an outdated port, a bug in a port or
+ simply a port without maintainer that you are interested in, feel free
+ to volunteer as maintainer. To become a maintainer you need:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>An email address.</para>
+ </listitem>
+ <listitem>
+ <para>A copy of the <filename>Portfile</filename>. Do not worry if
+ you don't know where to find one yet. There's more documentation
+ on that below.</para>
+ </listitem>
+ <listitem>
+ <para>An account in the <ulink
+ url="https://trac.macports.org/">MacPorts Trac</ulink>,
+ preferrably with the email address you want to use for your
+ port.</para>
+ </listitem>
+ <listitem>
+ <para>Interest in the software you want to maintain and some time.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>You do <emphasis>not</emphasis> need:</para>
+ <itemizedlist>
+ <listitem>
+ <para>Commit access to the MacPorts repository. Instead, you create
+ patches and open tickets in Trac. You can, however, <link
+ linkend="project.membership">apply for commit access</link>
+ once you have some experience in maintaining ports. In fact, we
+ would like to encourage you to apply after a few months.</para>
+ </listitem>
+ <listitem>
+ <para>Expert knowldge of the software you want to maintain or
+ experience in <filename>Portfile</filename> programming. You can
+ pick those up along the way. Your knowledge about the software
+ you want to maintain is probably more than what most other
+ MacPorts developers have, given the number of ports MacPorts has.
+ Consult <xref linkend="development" /> chapter and <xref
+ linkend="reference" /> on how to write
+ a <filename>Portfile</filename>. If your questions are not
+ answered there, please ask on the
+ <email>macports-dev at lists.macosforge.org</email> mailing
+ list.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ To become the maintainer of a port, first check whether the port
+ already has a maintainer. Run
+
+ <programlisting><prompt>%%</prompt> <userinput>port info --maintainer $portname</userinput></programlisting>
+
+ where <userinput>$portname</userinput> is the name of the port you want
+ to maintain. If the output is
+
+ <screen>maintainer: nomaintainer at macports.org</screen>
+
+ the port is unmaintained and you are more than welcome to take it over.
+ If the output lists a different email address, you can still
+ co-maintain the port, but you should contact the existing maintainer(s)
+ first.
+ </para>
+
+ <para>
+ Once you have verified that a port is unmaintained or the existing
+ maintainer has invited you to co-maintain the port of your choice,
+ follow these steps to become a maintainer:
+ </para>
+
+ <orderedlist>
+ <listitem>
+ <para>Locate the port's directory and make a copy. MacPorts can help
+ you locate the directory that contains the
+ <filename>Portfile</filename> by running <userinput>port dir
+ $portname</userinput>. Copy this directory to a separate location
+ (so you can easily generate a patch later) that is readable by the
+ macports user. In general, your home directory does not fulfill
+ that requirement, but <filename>/var/tmp</filename> does.
+
+ <programlisting><prompt>%%</prompt> <userinput>cp -r $(port dir $portname) /var/tmp</userinput></programlisting>
+
+ Check <filename>/var/tmp</filename> for the new directory. In most
+ cases, its name should be equal to the name of the port you want to
+ maintain. In those few cases where it is not (i.e., the so-called
+ <option>subports</option> feature is used), check the output of
+ <userinput>port dir $portname</userinput> for the correct name.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>Change to the new directory and run <userinput>port
+ info</userinput> to make sure everything went right. Note that
+ running any port command without a port name tries to use the
+ <filename>Portfile</filename> in the current directory. This is
+ very helpful when testing modifications or new ports, so keep this
+ in mind.
+ </para>
+
+ <programlisting><prompt>%%</prompt> <userinput>cd /var/tmp/$portname</userinput>
+<!-- --><prompt>%%</prompt> <userinput>port info</userinput><!--
+ --></programlisting>
+
+ <para>If you don't see info output for the port, but an error message
+ instead, it will usually be in the following form:</para>
+
+ <screen>Can't map the URL 'file://.' to a port description file ("couldn't read file "Portfile": permission denied").
+Please verify that the directory and portfile syntax are correct.
+To use the current port, you must be in a port's directory.</screen>
+
+ <para>Pay attention to the part in the brackets in the first line. It
+ will either contain a permission problem (in which case you need to
+ adjust the permissions of your <filename>Portfile</filename> and
+ the folders leading up to it), or a Tcl error message, in case of
+ syntax errors in the <filename>Portfile</filename>. Also check that
+ the copy of the working directory is in fact the current working
+ directory in your shell.</para>
+ </listitem>
+
+ <listitem>
+ <para>Open the <filename>Portfile</filename> in your favorite editor
+ and look for the line that starts with <option>maintainer</option>.
+ Delete <option>nomaintainer</option> from the line if it exists and
+ add your own email address in the form
+ <userinput>domain.tld:localpart</userinput>. The address is
+ obfuscated to prevent email harvesters from automatically grabbing
+ your address. If you want, you can start fixing bugs in the
+ <filename>Portfile</filename> as well.</para>
+
+ <para>At this point, please read <xref
+ linkend="project.update-policies.nonmaintainer" /> and
+ familiarize yourself with the meaning of
+ <option>openmaintainer</option>. Consider adding
+ <option>openmaintainer</option> to speed up and simplify small
+ updates of your port. If you decided to allow minor updates without
+ consultation, add <userinput>openmaintainer</userinput>, separated
+ with a space, to the <option>maintainer</option> line of the
+ <filename>Portfile</filename>.</para>
+
+ <para>Once you are done, save the file verify the
+ <filename>Portfile</filename> structure using MacPorts' builtin
+ lint check:</para>
+
+ <programlisting><prompt>%%</prompt> <userinput>port lint --nitpick</userinput></programlisting>
+
+ <para>You will likely see at least one error:</para>
+
+ <screen>Error: Portfile parent directory tmp does not match primary category $XYZ</screen>
+
+ <para>You can safely ignore <emphasis>this</emphasis> message. It is
+ printed because the copy of the port's directory is not in
+ a directory named after the port's primary category, but in
+ <filename>/var/tmp</filename> instead. Please try to address all
+ other warnings and error messages, though. If you need help, feel
+ free to continue and add a note to the ticket you will
+ create asking for instructions.</para>
+
+ <para>Finally, run <userinput>port info</userinput> again. The
+ maintainers line in the output should now contain your email
+ address.</para>
+
+ <note>
+ <para>If you made changes other than the maintainer line, you might
+ want to test build and installation as well. To do that, run
+ <userinput>sudo port destroot</userinput> in the port's
+ directory. If you see</para>
+
+ <screen>Error: Unable to execute port: Could not open file: /private/var/tmp/somewhere/Portfile</screen>
+
+ <para>check the permissions of the <filename>Portfile</filename> and
+ all folders above it. They must be readable by the
+ <option>macports</option> user. The easiest way to ensure this is to run</para>
+
+ <programlisting><prompt>%%</prompt> <userinput>chmod -R go+rX /var/tmp/$portname</userinput></programlisting>
+
+ <para>If the port fails to build, see the
+ <filename>main.log</filename> referenced in the error message for
+ details. If the build completes successfully, run <userinput>sudo
+ port clean</userinput> to clean up all leftovers.</para>
+ </note>
+ </listitem>
+
+ <listitem>
+ <para>Create a patch from the changes you made to the
+ <filename>Portfile</filename> and possible related files. To do that, run</para>
+
+ <programlisting><prompt>%%</prompt> <userinput>diff -uR $(port dir $portname) . > change-$portname-maintainer.diff</userinput></programlisting>
+
+ <para>in the directory where you edited the
+ <filename>Portfile</filename>. You can inspect the generated
+ unified diff in
+ <filename>change-$portname-maintainer.diff</filename> if you
+ want.</para>
+ </listitem>
+
+ <listitem>
+ <para>Now, <ulink url="https://trac.macports.org/newticket">file
+ a new ticket in Trac</ulink>. Set <guilabel>type</guilabel> to
+ <guilabel>request</guilabel> if you only changed the maintainer and
+ an appropriate other type if you also fixed a bug or enhanced or
+ updated the port. Leave the <guilabel>milestone</guilabel> field
+ empty. If you added yourself as co-maintainer, add the other
+ maintainers in the <guilabel>Cc</guilabel> field. Finally, fill in
+ the <guilabel>port</guilabel> field, set
+ <guilabel>keywords</guilabel> to <userinput>haspatch</userinput>
+ (because you are attaching a patch), check the box that you want to
+ attach files to the ticket and submit. After submission, attach the
+ patch you created in the previous step.</para>
+ </listitem>
+
+ <listitem>
+ <para>If your ticket doesn't receive any attention within a few days
+ (for example, because the port you are trying to modify does not
+ have a maintainer), you may email
+ <email>macports-dev at lists.macosforge.org</email> and request
+ a review and/or commit.</para>
+ </listitem>
+ </orderedlist>
+
+ <para>Once you are the maintainer for a port, all new tickets for this
+ port will be assigned to you. You are expected to take a look at these
+ tickets, give advice and try to debug problems. If you are stuck, do
+ not hesitate to ask on the
+ <email>macports-dev at lists.macosforge.org</email> list.</para>
+ </section>
</section>
<section id="project.update-policies">
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.macosforge.org/pipermail/macports-changes/attachments/20140731/8bfb8ebb/attachment-0001.html>
More information about the macports-changes
mailing list