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.
...or create a Trac ticket.
Portfile and any required patchfiles to the ticket.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.
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.
...or create a Trac ticket.
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.
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:
Portfile. Do not worry if you don’t know where to find one yet. There’s more documentation on that below.You do not need:
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.
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.haspatch on existing tickets.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.