# MacPorts Project

The MacPorts Project uses a system called Trac to file tickets to report bugs and enhancement requests. Trac also provides an interface to browse the MacPorts Subversion repository. Though anyone may search Trac for tickets, you must register for a Trac account to create tickets.

## Creating Trac Tickets

Once you are logged into Trac, you may click New Ticket and you will be presented with a new ticket window shown in the graphic below. Follow the Trac ticket guidelines below to fill out the form.

A new Trac ticket

### Trac Ticket Guidelines

There are certain conventions used to ensure that Trac tickets convey as much accurate information as possible so problems and contributions may be acted upon efficiently.

- Short Summary: [port] [version] [concise description]

  - Example: "rrdtool-1.2.23 Configure error - build failure"

- Type: There are two main types of tickets.

  - defect - The default; any port/MacPorts build/runtime failures and/or documentation corrections.

  - enhancement - Tickets, with or without patches, created to enhance something that isn't failing its intended purpose.

- Full Description: All details that might be relevant to someone reading the ticket. Wiki formatting or attached log files should be used for large text blocks. If you want to post a build log make sure you use `{{{...}}}` around the log or it could break the page layout. Example:

      {{{
      your build log here
      }}}

  Submitters are advised to trim pastes and logs of any kind to what's really relevant to the report, as otherwise overly large submissions that might contain redundant and/or unnecessary information might become unmanageable.

- Priority: Assign a priority level to the ticket.

  - High - Reserved for the use of MacPorts team members, as they are the best fit to determine which reports warrant a higher priority over others.

  - Normal - The default. For normal port failures, non-critical enhancement requests, non-critical port failures.

  - Low - For mostly cosmetic improvements, documentation corrections/improvements, etc.

  - Not set - Anything that doesn't fit the categories high, normal, or low.

- Component: Set what part of the MacPorts Project the ticket is to be filed against.

  - base - Tickets related to MacPorts base code.

  - guide - Documentation enhancements and error corrections, or patches to the MacPorts Guide.

  - ports - Tickets related to ports.

  - server/hosting - For MacPorts hosting & server-side issues, reserved for MacPorts PortMgr team members.

  - website - MacPorts website enhancements and error corrections.

  - wiki - MacPorts Wiki enhancements and error corrections.

- Keywords: Type any keywords that might help when searching for tickets (portname, type of problem, etc).

- Cc: Anyone else besides the ticket reporter and assignee who would like to be kept involved in the development of the ticket. Multiple email addresses should be separated with a comma and a space (i.e. `you@example.org, maintainer@macports.org`).

- Milestone: This is a ticket category that allows for search and sorting tickets efficiently.

  - MacPorts base enhancements - for tickets requesting or providing improvements to the functionality of the MacPorts system.

  - MacPorts base bugs - for tickets reporting or fixing bugs in the MacPorts system.

  - Port Bugs - for tickets reporting or fixing bugs in ports provided by MacPorts.

  - Port Enhancements - for submissions providing enhancements to ports provided by MacPorts.

  - Port Requests - for requests for ports to be added to MacPorts.

  - Port Submissions - for submissions that add a port to MacPorts.

  - Port Updates - for submissions that update a port provided by MacPorts.

  - Website & Documentation - for tickets relating to the documentation for MacPorts, including the MacPorts guide, Wiki, man pages and the website.

  - Blank - For unclassified tickets that don't fit into any of the provided milestones.

- Version: Select the MacPorts version you are using when it is applicable.

- Assign To: For tickets on ports, enter the email address of the port's maintainer (use `port info <portname>` to find this). If multiple maintainers are listed, enter the first maintainer's email address here and enter the remainining maintainers' email addresses in the Cc field. Exclude the email address openmaintainer@macports.org if it appears. If the maintainer's email address is nomaintainer@macports.org, leave the field blank.

- I have files to attach to this ticket: Use this checkbox to attach files to the ticket immediately after you create it. Or you can attach files later using the Attach File button.

## Contributing to MacPorts

You may contribute new ports and enhancements of any kind to already existing ports using Trac tickets.

### New Ports

Ports are contributed by following these steps. See Ticket Submission Guidelines above for a description of all fields.

1. Create a Trac ticket.

2. Set the type to enhancement.

3. Set the milestone to Port Submissions.

4. Attach the `Portfile` and any required patchfiles to the ticket.

### Port Enhancements

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 `Portfile` patches. See Ticket Submission Guidelines above for a description of all fields.

1. Create a `Portfile` patch with your changes as described in Portfile Development.

2. Create a Trac ticket.

3. Set the type to enhancement for miscellaneous enhancements or to defect for bug fixes.

4. Set the milestone to Port Enhancements, Port Updates or Port Bugs depending on the case.

5. Attach your Portfile patch file and any new or changed patch files (don't patch patches) to the ticket.

## Port Update Policies

Port maintainers normally are given commit privileges to the Subversion repository so they can make updates to their own ports. However, The MacPorts Project does not restrict commit privileges for maintainers, so before a person other than a port's maintainer updates a port it is a good practice to inform a port's maintainer. See details below.

### Non-Maintainer Port Updates

If you have a port update or bugfix for a port you do not maintain, to respect the rights of the port maintainer you should follow the following guidelines:

1. If a port's maintainer is nomaintainer@macports.org, you may feel free to make updates and/or take maintainership of the port.

2. If a port's maintainer contains the address openmaintainer@macports.org, this means that the author allows minor updates to the port without contacting him first. But permission should still be sought for major changes.

3. Create patch file(s) as necessary, attach them to a Trac ticket, and assign the ticket to the maintainer (or Cc him or her, if you are unable to assign tickets).

4. Wait for a response from the maintainer. The maintainer should apply the patches and close the ticket within 72 hours.

However, for maintained ports without openmaintainer@macports.org, there are some conditions under which maintainer permission may be waived:

- If the maintainer does not respond within 72 hours, you or another committer may review the patches and update the port. If you are not a committer, you may email macports-dev@lists.macosforge.org and request the updates be committed.

- A port is abandoned by it's current maintainer. A port against which a Port Abandoned ticket has been filed (see below) can be updated without contacting the maintainer.

- A critical port is broken that affects many users.

### Port Abandonment

A port may be considered abandoned if a bug has not been acknowledged for more than three weeks after a ticket is filed. If this time period has passed and you wish to initiate the Port Abandonment protocol and volunteer as the new maintainer:

1. File a new Trac ticket with the summary line [Port Abandoned].

2. Refer to the original unacknowledged ticket in the Port Abandoned ticket.

3. The Port Abandoned ticket may be closed when the new maintainer is assigned, and the original ticket with the updates may be resolved when the updates attached to the original ticket are committed.

## MacPorts Membership

A requirement for a person to become a MacPorts committer is to first become involved and contribute to the project. This may be done by having a record of contribution to the project in several of the following ways:

- Contributing new ports.

- Fixing bugs in existing ports.

- Volunteering as a maintainer of non-maintained ports.

- Involvement on MacPorts support lists.

- Contributing with documentation

To apply for MacPorts commit rights, send a brief email to the PortMgr team at macports-mgr@lists.macosforge.org entitled “Request for commit rights” with the following contents:

- a description of your application and why you think you deserve commit rights (including evidence of contributions to MacPorts as described above).

- the identity you'd like to use as a member of the project, A.K.A. the “handle”, as part of your `handle@macports.org` alias.

- a real e-mail address to which you'd like your MacPorts alias to forward.

The PortMgr team will consider all applications and provide an appropriate response in a timely manner.

## The PortMgr Team

The MacPorts PortMgr team is the steering group for The MacPorts Project. Its membership was determined by public elections among project members in March of 2005, resulting in the appointing of James D. Berry , Juan Manuel Palacios and Markus W. Weissman .

They are responsible for matters such as:

- approving new project members (i.e. granting commit rights);

- setting general guidelines for the project;

- dispute resolution;

- managing the projects infrastructure; and

- engineering releases.