You may contribute new ports and enhancements of any kind to already existing ports using Trac tickets. However, we prefer that you open a pull request on GitHub, in which case no Trac ticket is required.
The GitHub pull request method is strongly preferred over submitting Trac tickets. Submitting a Pull Request will likely result in your contribution being merged into MacPorts much faster, as the workflow is much easier for the maintainers.
Ports are contributed by following these steps. See the Ticket Submission Guidelines for a description of all fields.
Please run
%%port lint --nitpick $portname
where $portname is the name of the port you
are submitting. Please fix any warnings and errors.
Either submit the new port through a pull request on GitHub...
...or create a Trac ticket.
Set the type to submission.
Set the component to ports.
Set the port field to the name of the new port.
Attach the Portfile and any required
patchfiles to the ticket.
If your ticket or pull request doesn't receive any attention within a few days
you may send an email to
<macports-dev@lists.macports.org> and request a
review and/or commit. Please include a link to the ticket or pull request.
Enhancements to existing ports may comprise new functionality for
a given port, bug fixes or even simple version updates. They should
always be contributed as patches against the current
Portfile. See the Ticket Submission Guidelines for
a description of all fields.
Create a Portfile patch with your changes.
See Portfile Development for
more information on how to edit Portfiles.
Please run
%%port lint --nitpick $portname
where $portname is the name of the port you
modified. Please fix any warnings and errors before submitting your
changes.
Either submit the port update through a pull request on GitHub...
...or create a Trac ticket.
Set the type to enhancement for miscellaneous enhancements, to defect for bug fixes, or to update for version updates.
Set the component to ports.
Set the port field to the name of the port you want to change.
Put the maintainer's email address or GitHub username into the Cc field. You can use
%%port info --maintainer $portname
where $portname is the name of the port you
want to modify. Note that
<openmaintainer@macports.org> and
<nomaintainer@macports.org> are not real people and should thus not be Cc'd.
Attach your Portfile patch file and any new or changed patch files to the ticket.
If your ticket or pull request doesn't receive any attention within a few days
you may send an email to
<macports-dev@lists.macports.org> and request a
review and/or commit. Please include a link to the ticket or pull request.
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:
An email address and a GitHub account.
A copy of the Portfile. Do not worry if
you don't know where to find one yet. There's more documentation
on that below.
An account in the MacPorts Trac, (you'll log in with your GitHub account).
Interest in the software you want to maintain and some time.
You do not need:
Commit access to the MacPorts repository. Instead, you open pull requests in GitHub (or create patches and open tickets in Trac.) You can, however, apply for commit access once you have some experience in maintaining ports. In fact, we would like to encourage you to apply after a few months.
Expert knowledge of the software you want to maintain or
experience in Portfile 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 Chapter 4, Portfile Development chapter and Chapter 5, Portfile Reference on how to write
a Portfile. If your questions are not
answered there, please ask on the
<macports-dev@lists.macports.org> mailing
list.
To become the maintainer of a port, first check whether the port already has a maintainer. Run
%%port info --maintainer $portname
where $portname is the name of the port you want
to maintain. If the output is
maintainer:
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.
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:
Locate the port's directory and make a copy. MacPorts can help
you locate the directory that contains the
Portfile by running port dir
$portname. 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 /var/tmp does.
%%cp -r $(port dir $portname) /var/tmp
Check /var/tmp 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
subports feature is used), check the output of
port dir $portname for the correct name.
Change to the new directory and run port
info to make sure everything went right. Note that
running any port command without a port name tries to use the
Portfile in the current directory. This is
very helpful when testing modifications or new ports, so keep this
in mind.
%%cd /var/tmp/$portname%%port info
If you don't see info output for the port, but an error message instead, it will usually be in the following form:
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.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 Portfile and
the folders leading up to it), or a Tcl error message, in case of
syntax errors in the Portfile. Also check that
the copy of the working directory is in fact the current working
directory in your shell.
Open the Portfile in your favorite editor
and look for the line that starts with maintainer.
Delete nomaintainer from the line if it exists and
add your own email address and GitHub username, grouped together
with curly braces. Email addresses should be written in the form
domain.tld:localpart. (The address is
obfuscated to prevent email harvesters from automatically grabbing
your address.) For GitHub usernames, prefix your username with an
@ sign. For example, if your email address is
julesverne@example.org and your GitHub username
is jverne, your entry on the
maintainers line should read
{example.org:julesverne @jverne}.
At this point, please read Section 7.4.1, “Non-Maintainer Port Updates” and
familiarize yourself with the meaning of
openmaintainer. Consider adding
openmaintainer to speed up and simplify small
updates of your port. If you decided to allow minor updates without
consultation, add openmaintainer, separated
with a space, to the maintainer line of the
Portfile.
Once you are done, save the file and verify the
Portfile structure using MacPorts' builtin
lint check:
%%port lint --nitpick
You will likely see at least one error:
Error: Portfile parent directory tmp does not match primary category $XYZ
You can safely ignore this 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
/var/tmp 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.
Finally, run port info again. The
maintainers line in the output should now contain your email
address or GitHub username.
If you made changes other than the maintainer line, you might
want to test build and installation as well. To do that, run
sudo port destroot in the port's
directory. If you see
Error: Unable to execute port: Could not open file: /private/var/tmp/somewhere/Portfile
check the permissions of the Portfile and
all folders above it. They must be readable by the
macports user. The easiest way to ensure this is to run
%%chmod -R go+rX /var/tmp/$portname
If the port fails to build, see the
main.log referenced in the error message for
details. If the build completes successfully, run sudo
port clean to clean up all leftovers.
Create a patch from the changes you made to the
Portfile and possible related files. To do that, run
%%diff -ru $(port dir $portname) . > change-$portname-maintainer.diff
in the directory where you edited the
Portfile. You can inspect the generated
unified diff in
change-$portname-maintainer.diff if you
want.
If you are only changing the maintainer, file a pull request on GitHub.
You may also
file a new ticket in
Trac to change the maintainer, though GitHub pull requests are preferred.
Set type to
enhancement. Leave the
milestone field empty. If you added yourself
as co-maintainer, add the other maintainers in the
Cc field. Finally, fill in the
port field, set keywords
to haspatch (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.
If you are also fixing a bug, make a separate commit
for that in your pull request, or attach a separate patch for that
change to the same ticket. If you are fixing a bug that already has
a ticket, attach a patch fixing the bug there and file the
maintainer change in a separate ticket (with a separate patch) as
discussed above. In general, please create a separate patch for
each semantic change. Doing so simplifies reviewing. It enables
each independent change to be accepted without worries about
conflicts that sometimes arise when several changes are rolled into
one patch. Do not worry that you cannot change the
keywords to haspatch on
existing tickets.
If your pull request or ticket doesn't receive any attention within a few days
you may send an email to
<macports-dev@lists.macports.org> and request
a review and/or commit. Please include a link to the pull
request or ticket.
Once you are the maintainer for a port, all new pull requests
and tickets for this port will be assigned to you.
You are expected to take a look at these pull requests and
tickets, give advice and try to debug problems. If you are stuck, do
not hesitate to ask on the
<macports-dev@lists.macports.org> list.