<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head><meta http-equiv="content-type" content="text/html; charset=utf-8" />
<title>[122854] trunk/doc-new/guide/xml/project.xml</title>
</head>
<body>
<style type="text/css"><!--
#msg dl.meta { border: 1px #006 solid; background: #369; padding: 6px; color: #fff; }
#msg dl.meta dt { float: left; width: 6em; font-weight: bold; }
#msg dt:after { content:':';}
#msg dl, #msg dt, #msg ul, #msg li, #header, #footer, #logmsg { font-family: verdana,arial,helvetica,sans-serif; font-size: 10pt; }
#msg dl a { font-weight: bold}
#msg dl a:link { color:#fc3; }
#msg dl a:active { color:#ff0; }
#msg dl a:visited { color:#cc6; }
h3 { font-family: verdana,arial,helvetica,sans-serif; font-size: 10pt; font-weight: bold; }
#msg pre { overflow: auto; background: #ffc; border: 1px #fa0 solid; padding: 6px; }
#logmsg { background: #ffc; border: 1px #fa0 solid; padding: 1em 1em 0 1em; }
#logmsg p, #logmsg pre, #logmsg blockquote { margin: 0 0 1em 0; }
#logmsg p, #logmsg li, #logmsg dt, #logmsg dd { line-height: 14pt; }
#logmsg h1, #logmsg h2, #logmsg h3, #logmsg h4, #logmsg h5, #logmsg h6 { margin: .5em 0; }
#logmsg h1:first-child, #logmsg h2:first-child, #logmsg h3:first-child, #logmsg h4:first-child, #logmsg h5:first-child, #logmsg h6:first-child { margin-top: 0; }
#logmsg ul, #logmsg ol { padding: 0; list-style-position: inside; margin: 0 0 0 1em; }
#logmsg ul { text-indent: -1em; padding-left: 1em; }#logmsg ol { text-indent: -1.5em; padding-left: 1.5em; }
#logmsg > ul, #logmsg > ol { margin: 0 0 1em 0; }
#logmsg pre { background: #eee; padding: 1em; }
#logmsg blockquote { border: 1px solid #fa0; border-left-width: 10px; padding: 1em 1em 0 1em; background: white;}
#logmsg dl { margin: 0; }
#logmsg dt { font-weight: bold; }
#logmsg dd { margin: 0; padding: 0 0 0.5em 0; }
#logmsg dd:before { content:'\00bb';}
#logmsg table { border-spacing: 0px; border-collapse: collapse; border-top: 4px solid #fa0; border-bottom: 1px solid #fa0; background: #fff; }
#logmsg table th { text-align: left; font-weight: normal; padding: 0.2em 0.5em; border-top: 1px dotted #fa0; }
#logmsg table td { text-align: right; border-top: 1px dotted #fa0; padding: 0.2em 0.5em; }
#logmsg table thead th { text-align: center; border-bottom: 1px solid #fa0; }
#logmsg table th.Corner { text-align: left; }
#logmsg hr { border: none 0; border-top: 2px dashed #fa0; height: 1px; }
#header, #footer { color: #fff; background: #636; border: 1px #300 solid; padding: 6px; }
#patch { width: 100%; }
#patch h4 {font-family: verdana,arial,helvetica,sans-serif;font-size:10pt;padding:8px;background:#369;color:#fff;margin:0;}
#patch .propset h4, #patch .binary h4 {margin:0;}
#patch pre {padding:0;line-height:1.2em;margin:0;}
#patch .diff {width:100%;background:#eee;padding: 0 0 10px 0;overflow:auto;}
#patch .propset .diff, #patch .binary .diff {padding:10px 0;}
#patch span {display:block;padding:0 10px;}
#patch .modfile, #patch .addfile, #patch .delfile, #patch .propset, #patch .binary, #patch .copfile {border:1px solid #ccc;margin:10px 0;}
#patch ins {background:#dfd;text-decoration:none;display:block;padding:0 10px;}
#patch del {background:#fdd;text-decoration:none;display:block;padding:0 10px;}
#patch .lines, .info {color:#888;background:#fff;}
--></style>
<div id="msg">
<dl class="meta">
<dt>Revision</dt> <dd><a href="https://trac.macports.org/changeset/122854">122854</a></dd>
<dt>Author</dt> <dd>cal@macports.org</dd>
<dt>Date</dt> <dd>2014-07-31 14:24:25 -0700 (Thu, 31 Jul 2014)</dd>
</dl>
<h3>Log Message</h3>
<pre>guide: add section on how to become a port's maintainer</pre>
<h3>Modified Paths</h3>
<ul>
<li><a href="#trunkdocnewguidexmlprojectxml">trunk/doc-new/guide/xml/project.xml</a></li>
</ul>
</div>
<div id="patch">
<h3>Diff</h3>
<a id="trunkdocnewguidexmlprojectxml"></a>
<div class="modfile"><h4>Modified: trunk/doc-new/guide/xml/project.xml (122853 => 122854)</h4>
<pre class="diff"><span>
<span class="info">--- 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)
</span><span class="lines">@@ -448,6 +448,237 @@
</span><span class="cx"> </listitem>
</span><span class="cx"> </orderedlist>
</span><span class="cx"> </section>
</span><ins>+
+ <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@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@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@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@lists.macosforge.org</email> list.</para>
+ </section>
</ins><span class="cx"> </section>
</span><span class="cx">
</span><span class="cx"> <section id="project.update-policies">
</span></span></pre>
</div>
</div>
</body>
</html>