portfile
submissions
maintainer

# MacPorts submissions

## Submitting a Port

Using a standardised approach to submitting the Portfiles and associated patches scripts, etc allows us to keep track of port submissions, process them efficiently and get them submitted as quickly as possible to our ports tree in Subversion. The following sections will describe the standard port submission procedures.

### Where to submit

All ports should be submitted via the MacPorts Trac tool . If you are uncertain about any aspect of your port, you may also want to email it with your questions and the ticket number to MacPorts mailing list.

If you are submitting a modification, or an update to an existing port, please assign the port to the current maintainer in your Trac submission, so that the automatic email is directed to the maintainer, who will be best suited to deal with your submission. Also, due to a current misconfiguration in Trac, add the current maintainer to the Cc field, to make sure they are notified.

Updates and modifications should be submitted as diffs. See updating a port below.

### Using Trac to submit a Port

The following section describes in some more detail how to use Trac to submit your port.

#### Submission parameters

Short summary:

  The summary field should provide a brief explanation of purpose of the ticket.

Type:
Full description:

  The description field should contain the following information as per the example given here.

      Portname-1.2.3

      the portfile can be found here: URL or ATTACHED

      Description: What does this program do in a nutshell,
      briefly what changes were made, or what files you are attaching in the tarball.

      Homepage: URL of project or program itself, not the portfile

      Comments: Any comments you have about your port, concerns, lookouts,
      dependencies that you may want to mention
      --
      your sig if you'd like

Priority:
Component:

  Select "ports" as the component if you're submitting a change to an existing port or a new port. Select the appropriate component if you're submitting a change to a different part of the project.

Severity:
Assign to:

  Please assign UPDATEs and COMMENTs on existing ports to the maintainer. Otherwise, if this is a NEW port or an RFC, please leave blank.

Milestone:

  Milestone explanation here!

  NEW: portname-1.2.3

    Please use this format for the submission of new ports.

  UPDATE: portname-1.2.3

    Please use this format for the submission of updates to ports. Please use diffs!

  REVISION: portname-1.2.3

    Please use this format for the submission of changes to a current, uncommitted port submission

  RFC: portname-1.2.3

    Please use this format for the submission of Request for Comments on a Portfile.

  ATTACHMENT: portname-1.2.3

    to add an attachment you will have use the query tool. Once you have selected the correct port, please use this format in the summary field for your submission.

  COMMENT: portname-1.2.3

    Please use this format for the submission of comments on existing ports or submissions. Most comments should be directed to the maintainer, or the mailing lists. Some comments are of a critical nature and should be logged.

  TAKEOVER: portname

    Use this term if you want to take over maintainership of an (probably) abandoned Port. If the current maintainer does not react on this for 4 weeks, you are free to change ownership of this Port.

Version:
Keywords:
Cc:

#### Final comments on Port submission

The following general points should also be borne in mind when submitting to Trac:

- Small changes may be attached or included in the description field.
- Larger changes should be attached as a single file.
- Multiple patched files should be bundled together using tar and attached to the submission.
- Currently attachments must be sent in using the current bug number, remeber to query Trac to find out the current bug number, select that bug and use the 'Create a New Attachment' link.

### Updating a port

The following guidelines are for submitting updates to ports that are currently in the tree

All updates and modifications to existing ports should be sent in as diffs.

There are a couple of ways to obtain correct diff formats

Using diff:

- Obtain the original file (oldfile)
- cp oldfile oldfile.new
- edit oldfile.new and save your changes
- diff -u oldfile oldfile.new > oldfile.diff
- use Trac to submit your port UPDATE, assigning the bug to the corresponding port maintainer.

Or using svn diff:

- checkout the original source using svn
- edit the files and save your changes
- svn diff sourcefile > sourcefile.diff
- use Trac to submit your port UPDATE, assigning the bug to the corresponding port maintainer.

Lastly, if your update consists of several files, use tar to bundle them into one file for submission

## Submission to other project areas

If you instead plan to contribute to the project by making a submission to any other of its areas, like the "base" section holding the MacPorts sources themselves, the guidelines for such are very similar to those outlined above. Just be sure to choose the correct component (be that "base", "doc", "www" or any other) of the MacPorts product when creating the Trac entry.