You've already forked macports-guide
mirror of
https://github.com/macports/macports-guide.git
synced 2026-03-31 14:38:45 -07:00
1477 lines
66 KiB
XML
1477 lines
66 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V5.0//EN"
|
|
"http://docbook.org/xml/5.0/dtd/docbook.dtd">
|
|
<chapter xml:id="project" xmlns:xlink="http://www.w3.org/1999/xlink">
|
|
<title>MacPorts Project</title>
|
|
|
|
<section xml:id="project.tickets">
|
|
<title>Using Trac for Tickets</title>
|
|
|
|
<para>The MacPorts Project uses a system called <link
|
|
xlink:href="https://trac.macports.org/">Trac</link> to file tickets to report bugs
|
|
and enhancement requests. Though anyone may search Trac for tickets,
|
|
you must have a <link
|
|
xlink:href="https://github.com/join">GitHub account</link> in order to login to
|
|
<link xlink:href="https://trac.macports.org/">Trac</link> to create tickets.</para>
|
|
|
|
<section xml:id="project.tickets.prerequisites">
|
|
<title>Before Filing a New Ticket</title>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Clean and try again</para>
|
|
<para>
|
|
If a build fails or is otherwise interrupted, and you try again,
|
|
MacPorts tries to pick up where it left off. Sometimes this causes
|
|
new problems, and even if it doesn't, it means that log messages
|
|
from earlier steps, which can be essential for figuring out why a
|
|
build failed, are not included in the new log; MacPorts prints
|
|
<quote>Skipping completed</quote> in the log for each
|
|
previously-completed phase that was skipped. Before filing a
|
|
ticket, <userinput>sudo port clean</userinput> the port that
|
|
failed, then try again.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Check the problem hotlist</para>
|
|
<para>
|
|
The <link
|
|
xlink:href="https://trac.macports.org/wiki/ProblemHotlist">Problem
|
|
Hotlist</link> contains possible solutions to problems that
|
|
affect many MacPorts users. If a solution to your problem listed
|
|
there works, don't file a ticket.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Search to see if a Trac ticket has already been filed</para>
|
|
<para>
|
|
Avoid filing duplicate bugs. Search for duplicates by:
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem><para>using the search bar that appears on each page</para></listitem>
|
|
<listitem><para>using <link xlink:href="https://trac.macports.org/search?portsummarysearch=on">the search page</link></para></listitem>
|
|
<listitem><para>browsing the list of <link xlink:href="https://trac.macports.org/report">categorized reports</link></para></listitem>
|
|
<listitem><para>making an advanced search by constructing a <link xlink:href="https://trac.macports.org/query">custom query</link></para></listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Is the problem an application error and not related to compiling and installing?</para>
|
|
<para>
|
|
In general, application bugs should be reported to the developers of the app
|
|
(<quote>upstream</quote>), not MacPorts. An application bug that affects a large number of
|
|
MacPorts users might merit a MacPorts bug for informational purposes only, but
|
|
this should be done sparingly.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Is the problem with a 'port upgrade' operation?</para>
|
|
<para>
|
|
If so, try a 'port uninstall <replaceable>foo</replaceable>' and
|
|
then reinstall. You might also want to run 'port -nR upgrade --force
|
|
<replaceable>foo</replaceable>' to rebuild ports depending upon
|
|
port <replaceable>foo</replaceable>.
|
|
Note that it is safest and recommended that most users always upgrade
|
|
with 'port upgrade outdated' to update all ports at once. Upgrading a
|
|
single port can lead to software errors in other ports that have not
|
|
yet been upgraded.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
|
|
<section xml:id="project.tickets.creating">
|
|
<title>Creating Trac Tickets</title>
|
|
|
|
<para>Once you are logged into Trac, you may click <link
|
|
xlink:href="https://trac.macports.org/newticket">New Ticket</link> 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. If you are
|
|
reporting a failed port install and a log was mentioned in the error,
|
|
please use the <emphasis role="strong">I have files to attach to this ticket</emphasis>
|
|
checkbox to add that log file to the ticket.</para>
|
|
|
|
<screenshot>
|
|
<info>
|
|
<title>A new Trac ticket</title>
|
|
</info>
|
|
|
|
<mediaobject>
|
|
<textobject>
|
|
<phrase>screenshot of a new ticket on the Trac system</phrase>
|
|
</textobject>
|
|
<imageobject>
|
|
<imagedata fileref="trac-default.png" />
|
|
</imageobject>
|
|
</mediaobject>
|
|
</screenshot>
|
|
</section>
|
|
|
|
<section xml:id="project.tickets.guidelines">
|
|
<title>Trac Ticket Guidelines</title>
|
|
|
|
<para>This is a short overview of the guidelines for Trac tickets. Please
|
|
see below for longer and more detailed explanations.</para>
|
|
|
|
<tip>
|
|
<title>TL;DR</title>
|
|
<informaltable frame="none">
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>Field</entry>
|
|
<entry>Content</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry><emphasis role="strong">Summary</emphasis></entry>
|
|
<entry>
|
|
<para>
|
|
<replaceable>$port</replaceable>
|
|
<replaceable>$version</replaceable>
|
|
<replaceable>[$variants]</replaceable>: <replaceable>short
|
|
problem summary</replaceable>
|
|
</para>
|
|
<para>
|
|
<emphasis role="strong">Example:</emphasis> openssl
|
|
@1.0.1e_1+universal: DTLS handshake error messages with
|
|
openconnect
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><emphasis role="strong">Description</emphasis></entry>
|
|
<entry>
|
|
Describe your problem. Preformatted text (such as terminal
|
|
output) should be put in <literal>{{{<replaceable>three curly
|
|
brackets</replaceable>}}}</literal>. Please attach large
|
|
amounts of output rather than pasting.
|
|
Link to GitHub commits with links like
|
|
<literal>[changeset:<replaceable>bd5d680…</replaceable>/macports-ports
|
|
<replaceable>commit bd5d680</replaceable>]</literal>.
|
|
Use the preview button!
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><emphasis role="strong">Type</emphasis></entry>
|
|
<entrytbl cols="2" colsep="0" rowsep="0">
|
|
<tbody>
|
|
<row>
|
|
<entry><emphasis role="strong">defect</emphasis></entry>
|
|
<entry>Bugs, build failures, documentation fixes</entry>
|
|
</row>
|
|
<row>
|
|
<entry><emphasis role="strong">enhancement</emphasis></entry>
|
|
<entry>Improving existing work</entry>
|
|
</row>
|
|
<row>
|
|
<entry><emphasis role="strong">update</emphasis></entry>
|
|
<entry>Update requests or patch submissions for ports</entry>
|
|
</row>
|
|
<row>
|
|
<entry><emphasis role="strong">submissions</emphasis></entry>
|
|
<entry>Submission of new <filename>Portfile</filename>s</entry>
|
|
</row>
|
|
<row>
|
|
<entry><emphasis role="strong">request</emphasis></entry>
|
|
<entry>Requests for new ports</entry>
|
|
</row>
|
|
</tbody>
|
|
</entrytbl>
|
|
</row>
|
|
<row>
|
|
<entry><emphasis role="strong">Priority</emphasis></entry>
|
|
<entry>
|
|
Use <emphasis role="strong">normal</emphasis> or <emphasis role="strong">low</emphasis>.
|
|
<emphasis role="strong">High</emphasis> is reserved for MacPorts developers.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><emphasis role="strong">Milestone</emphasis></entry>
|
|
<entry>Leave empty.</entry>
|
|
</row>
|
|
<row>
|
|
<entry><emphasis role="strong">Component</emphasis></entry>
|
|
<entrytbl cols="2" colsep="0" rowsep="0">
|
|
<tbody>
|
|
<row>
|
|
<entry><emphasis role="strong">base</emphasis></entry>
|
|
<entry>Tickets affecting MacPorts itself</entry>
|
|
</row>
|
|
<row>
|
|
<entry><emphasis role="strong">guide</emphasis></entry>
|
|
<entry>Use for documentation</entry>
|
|
</row>
|
|
<row>
|
|
<entry><emphasis role="strong">ports</emphasis></entry>
|
|
<entry>Tickets affecting specific ports. Remember to set
|
|
the <emphasis role="strong">port</emphasis> field!</entry>
|
|
</row>
|
|
<row>
|
|
<entry><emphasis role="strong">server/hosting</emphasis></entry>
|
|
<entry>Use for infrastructure issues</entry>
|
|
</row>
|
|
<row>
|
|
<entry><emphasis role="strong">website</emphasis></entry>
|
|
<entry>Enhancements and fixes for the web site</entry>
|
|
</row>
|
|
<row>
|
|
<entry><emphasis role="strong">wiki</emphasis></entry>
|
|
<entry>Enhancements and fixes for the wiki (or just edit
|
|
it directly!)</entry>
|
|
</row>
|
|
</tbody>
|
|
</entrytbl>
|
|
</row>
|
|
<row>
|
|
<entry><emphasis role="strong">Version</emphasis></entry>
|
|
<entry>The version of MacPorts you are running.</entry>
|
|
</row>
|
|
<row>
|
|
<entry><emphasis role="strong">Keywords</emphasis></entry>
|
|
<entry><literal>maintainer</literal> if you are the port's
|
|
maintainer. <literal>haspatch</literal> if you are attaching
|
|
a patch. <link xlink:href="https://trac.macports.org/wiki/TicketsKeywordGuidelines">Full
|
|
list</link>.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><emphasis role="strong">Port</emphasis></entry>
|
|
<entry>The name of the port affected by this ticket. Separate
|
|
multiple using spaces. Leave empty for non-port
|
|
tickets.</entry>
|
|
</row>
|
|
<row>
|
|
<entry><emphasis role="strong">Owner</emphasis>/<emphasis role="strong">Cc</emphasis></entry>
|
|
<entry>Full email address or GitHub username of the port's
|
|
maintainer. Run <command>port info --maintainer
|
|
<replaceable><portname></replaceable></command> to
|
|
look this up. Do not add
|
|
<email>nomaintainer@macports.org</email> or
|
|
<email>openmaintainer@macports.org</email>. For ports with
|
|
multiple maintainers, only put the first maintainer into the
|
|
<emphasis role="strong">Owner</emphasis> field and all others in the
|
|
<emphasis role="strong">Cc</emphasis> field. You do not need to Cc
|
|
yourself.</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</tip>
|
|
|
|
<para>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.</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><emphasis role="strong">Summary:</emphasis>
|
|
<replaceable>[port]</replaceable>
|
|
<replaceable>[version]</replaceable> <replaceable>[concise
|
|
description]</replaceable></para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Example: "rrdtool @1.2.23 +python Configure error - build
|
|
failure"</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis role="strong">Description:</emphasis> All details that might
|
|
be relevant to someone reading the ticket. Be sure to mention
|
|
the versions of your operating system and Xcode install. </para>
|
|
|
|
<para>Use <link
|
|
xlink:href="https://trac.macports.org/wiki/WikiFormatting">Wiki
|
|
formatting</link> to ensure that text is formatted correctly.
|
|
Link to GitHub commits with
|
|
<literal>[changeset:<replaceable>GithubSHA</replaceable>/macports-ports
|
|
<replaceable>optional link text</replaceable>]</literal>.
|
|
For example, for a GitHub commit with URL
|
|
<link xlink:href="https://github.com/macports/macports-ports/commit/bd5d6800828a3dcda1b65f3999fa748a365b168e">
|
|
https://github.com/macports/macports-ports/commit/bd5d6800828a3dcda1b65f3999fa748a365b168e</link>,
|
|
put <literal>[changeset:bd5d6800828a3dcda1b65f3999fa748a365b168e/macports-ports
|
|
commit bd5d680]</literal> in the description. It becomes the link,
|
|
<link xlink:href="https://trac.macports.org/changeset/bd5d6800828a3dcda1b65f3999fa748a365b168e/macports-ports">
|
|
commit bd5d680</link>. See <link
|
|
xlink:href="https://trac.macports.org/wiki/TracLinks#LinkstoMacPortsonGitHub">
|
|
TracLinks#LinkstoMacPortsonGitHub</link> for details.</para>
|
|
|
|
<para>Use the Preview button before submitting. If you want to
|
|
post preformatted text such as a log or terminal output, make sure
|
|
you use <literal>{{{<replaceable>...</replaceable>}}}</literal>
|
|
around the text or it could break the page layout. Example:</para>
|
|
|
|
<literallayout>
|
|
{{{
|
|
<replaceable>your error message here</replaceable>
|
|
}}}
|
|
</literallayout>
|
|
|
|
<para>Submitters are advised to trim inline pastes and logs to
|
|
what's really relevant to the report, as otherwise overly large
|
|
ticket pages can become unmanageable. Long output, such as the
|
|
full log from a port build, should be added as an attachment, not
|
|
pasted inline. See <guilabel>I have files to attach to this
|
|
ticket</guilabel> below.</para>
|
|
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis role="strong">Type:</emphasis> There are five types of
|
|
tickets.</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><emphasis role="strong">defect</emphasis> - The default; any port/MacPorts
|
|
build/runtime failures and/or documentation corrections.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis role="strong">enhancement</emphasis> - Tickets, with or without
|
|
patches, created to enhance something that isn't failing its
|
|
intended purpose.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis role="strong">update</emphasis> - Tickets, with or without
|
|
patches, involving updating a port to a newer upstream
|
|
version.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis role="strong">submission</emphasis> - Tickets created to submit
|
|
Portfiles for software not currently available in MacPorts.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis role="strong">request</emphasis> - Tickets created to request
|
|
the creation of a new port.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis role="strong">Priority:</emphasis> Assign a priority level to the
|
|
ticket.</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><emphasis role="strong">High</emphasis> - Reserved for the use of MacPorts
|
|
team members, as they are the best fit to determine which
|
|
reports warrant a higher priority over others.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis role="strong">Normal</emphasis> - The default. For normal port
|
|
failures, non-critical enhancement requests, non-critical port
|
|
failures.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis role="strong">Low</emphasis> - For mostly cosmetic improvements,
|
|
documentation corrections/improvements, etc.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis role="strong">Not set</emphasis> - Anything that doesn't fit the
|
|
categories high, normal, or low.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis role="strong">Milestone:</emphasis> Leave this blank. MacPorts
|
|
developers will set this to the version of MacPorts that contains
|
|
a fix for the ticket when they commit a change. Note that this is
|
|
only meaningful for changes in MacPorts itself, since changes to
|
|
ports are continuously provided to users. If the milestone is
|
|
<emphasis role="strong">MacPorts Future</emphasis> no version of MacPorts with
|
|
the fix has been released yet.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis role="strong">Component:</emphasis> Set what part of the MacPorts
|
|
Project the ticket is to be filed against.</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><emphasis role="strong">base</emphasis> - Tickets related to MacPorts base
|
|
code.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis role="strong">guide</emphasis> - Documentation enhancements and
|
|
error corrections, or patches to the MacPorts Guide.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis role="strong">ports</emphasis> - Tickets related to
|
|
ports.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis role="strong">server/hosting</emphasis> - For MacPorts hosting
|
|
& server-side issues.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis role="strong">website</emphasis> - MacPorts website enhancements
|
|
and error corrections.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis role="strong">wiki</emphasis> - MacPorts Wiki enhancements and
|
|
error corrections.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis role="strong">Version:</emphasis> Select the MacPorts version you
|
|
are using when it is applicable.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis role="strong">Keywords:</emphasis> Type any keywords that might
|
|
help when searching for tickets. It is not useful to list words here
|
|
that already appear elsewhere in the ticket. Keywords also serve as
|
|
tags; for example, use <quote>tiger</quote> if reporting a bug that
|
|
only affects Mac OS X 10.4, <quote>haspatch</quote> if a fix is attached
|
|
to the ticket, <quote>maintainer</quote> if you are the port's
|
|
maintainer, or <quote>LP64</quote> if reporting an issue that only
|
|
affects 64-bit platforms.</para>
|
|
|
|
<para>See
|
|
<link xlink:href="https://trac.macports.org/wiki/TicketsKeywordGuidelines">the
|
|
TicketsKeywordGuidelines wiki page</link> for a clickable list
|
|
of all keywords.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<emphasis role="strong">Cc:</emphasis> Anyone else besides the ticket reporter
|
|
and assignee who would like to be kept involved in the development
|
|
of the ticket. Multiple email addresses or GitHub usernames should
|
|
be separated with a comma and a space (e.g., <literal>neverpanic,
|
|
you@example.org, maintainer@macports.org</literal>).</para>
|
|
|
|
<para>
|
|
When reporting port-related tickets, make sure you add the port
|
|
maintainers email address or GitHub username to the
|
|
<emphasis role="strong">Cc:</emphasis> field so they are notified of the ticket
|
|
(unless you have commit access, then see <guilabel>Assign
|
|
To:</guilabel> below). You can obtain the email address or GitHub
|
|
username of the port maintainer by running <command>port info
|
|
--maintainers <replaceable>[port]</replaceable></command></para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<emphasis role="strong">Assign To:</emphasis>
|
|
For tickets on ports, enter the email address or GitHub username of
|
|
the port's maintainer (use <command>port info
|
|
<replaceable>[port]</replaceable></command> to find this). If
|
|
multiple maintainers are listed, enter the first maintainer's email
|
|
address or GitHub username here and enter the remaining
|
|
maintainers' email addresses or GitHub usernames in the
|
|
<emphasis role="strong">Cc</emphasis> field. Exclude the email address
|
|
<email>openmaintainer@macports.org</email> if it appears. If the
|
|
maintainer's email address is
|
|
<email>nomaintainer@macports.org</email>, leave the field
|
|
blank.</para>
|
|
|
|
<para>
|
|
Only project members and the reporter of a ticket can edit this field.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis role="strong">Port:</emphasis> For tickets on ports, enter the
|
|
name of the port (or ports, space-separated, when multiple are
|
|
affected).</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis role="strong">I have files to attach to this ticket:</emphasis>
|
|
Use this checkbox to attach files to the ticket immediately after
|
|
you create it. Or you can attach files later using the
|
|
<emphasis role="strong">Attach File</emphasis> button.</para>
|
|
<para>If the file you are attaching is larger than 256 KiB, please
|
|
compress it with bzip2 or gzip first to save space on the server and
|
|
bandwidth for those downloading it, as
|
|
Trac will not preview files above that size anyway.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
</section>
|
|
|
|
<section xml:id="project.github">
|
|
<title>Using Git and GitHub</title>
|
|
|
|
<para>The MacPorts project uses the
|
|
<link xlink:href="https://git-scm.com/">Git distributed version
|
|
control system</link> to manage the code for the entire
|
|
project. Our master repositories are hosted on
|
|
<link xlink:href="https://github.com/">GitHub</link>.</para>
|
|
|
|
<para>
|
|
We maintain
|
|
<link
|
|
xlink:href="https://github.com/macports">
|
|
public repositories</link>
|
|
for almost all our
|
|
project code and documentation, including a GitHub
|
|
repository for the
|
|
<link xlink:href="https://github.com/macports/macports-base">
|
|
MacPorts system itself</link>,
|
|
for the <link
|
|
xlink:href="https://github.com/macports/macports-ports">MacPorts
|
|
ports</link>,
|
|
and <link
|
|
xlink:href="https://github.com/macports/macports-guide">even for
|
|
the guide you are reading right now</link>.
|
|
</para>
|
|
|
|
<para>
|
|
If you're not familiar with Git and need an introduction, we
|
|
recommend the book
|
|
<link
|
|
xlink:href="https://git-scm.com/book/en/v2">Pro Git, by Scott
|
|
Chacon and Ben Straub</link>.
|
|
The book is available for free
|
|
online, and is published under a Creative Commons license.
|
|
</para>
|
|
|
|
<para>
|
|
You should feel free to fork any of our code repositories, make
|
|
improvements to the code, and contribute them back to us via a
|
|
GitHub pull request. We are grateful for improvements to
|
|
absolutely everything, including new ports, fixes to ports,
|
|
improvements to our base software, improvements to our
|
|
documentation and our web site, or anything else you see.
|
|
</para>
|
|
|
|
<para>
|
|
The main steps for submitting a pull request are:
|
|
</para>
|
|
<orderedlist>
|
|
<listitem><para>Make your changes in your own Git repository:</para>
|
|
<orderedlist>
|
|
<listitem><para>Fork the appropriate repository, say
|
|
<link xlink:href="https://github.com/macports/macports-ports">macports-ports</link>.</para></listitem>
|
|
<listitem><para>Create a branch for your changes.</para></listitem>
|
|
<listitem><para>Make your changes.</para>
|
|
<para>For changes to ports and code, please follow the
|
|
information elsewhere in this guide, and test your changes
|
|
carefully.</para>
|
|
<para>Changes to Portfiles should also pass <command>port lint</command>.</para></listitem>
|
|
<listitem><para>Commit your changes to your branch, making sure
|
|
to follow the <link xlink:href="https://trac.macports.org/wiki/CommitMessages">
|
|
MacPorts standard for commit messages</link>.</para></listitem>
|
|
<listitem><para>Be sure to rebase your changes so as to
|
|
minimize the number of commits. Ideally, you should have just
|
|
one.</para>
|
|
<para>(There are exceptions. If you have several unrelated fixes, or
|
|
you're changing multiple packages, etc., you might need more
|
|
than one commit. The point is to minimize them,
|
|
ideally with one commit per logical change.)</para></listitem>
|
|
</orderedlist>
|
|
</listitem>
|
|
<listitem><para>Push the change branch to your own GitHub repository.</para></listitem>
|
|
<listitem><para>Make a pull request from your branch in your own
|
|
git repository to the appropriate MacPorts repository.</para>
|
|
<para>You can do this on the appropriate GitHub
|
|
page. For example, you can request a pull of a Portfile on
|
|
<link
|
|
xlink:href="https://github.com/macports/macports-ports/pulls">
|
|
the macports-ports repository pull request page</link>.</para></listitem>
|
|
<listitem><para>Go through the process of waiting for the CI
|
|
system to build your new port, receiving feedback from our team,
|
|
possibly being asked to make changes to your requested
|
|
pull, and making those changes. (If you are asked for additional
|
|
changes, please squash them to avoid unnecessary
|
|
commits.)</para></listitem>
|
|
</orderedlist>
|
|
|
|
<para> We try to process pull requests very quickly. If you do not
|
|
see activity on your request within a few days, please feel free
|
|
to get in touch with us on the
|
|
<email>macports-dev@lists.macports.org</email> mailing list to
|
|
request a review and/or commit. Please include a link to the pull
|
|
request in your email.</para>
|
|
</section>
|
|
|
|
<section xml:id="project.contributing">
|
|
<title>Contributing to MacPorts</title>
|
|
|
|
<para>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
|
|
<link xlink:href="https://github.com/macports/macports-ports/pulls">GitHub</link>,
|
|
in which case no Trac ticket is required.
|
|
</para>
|
|
|
|
<para>
|
|
<emphasis>
|
|
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.
|
|
</emphasis>
|
|
</para>
|
|
|
|
<!-- Should we have similar sections about committing to base sources and
|
|
documentation, or alternatively add this to the following? -->
|
|
|
|
<section xml:id="project.contributing.new">
|
|
<title>New Ports</title>
|
|
|
|
<para>Ports are contributed by following these steps. See the <link
|
|
linkend="project.tickets">Ticket Submission Guidelines</link> for
|
|
a description of all fields.</para>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>Please run
|
|
<programlisting><prompt>%%</prompt> <userinput>port lint --nitpick $portname</userinput></programlisting>
|
|
where <userinput>$portname</userinput> is the name of the port you
|
|
are submitting. Please fix any warnings and errors.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Either submit the new port through
|
|
<link xlink:href="https://github.com/macports/macports-ports/pulls">a pull request on GitHub</link>...</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>...or create a Trac ticket.</para>
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>Set the type to <emphasis role="strong">submission</emphasis>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Set the component to <emphasis role="strong">ports</emphasis>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Set the <emphasis role="strong">port</emphasis> field to the name of the new port.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Attach the <filename>Portfile</filename> and any required
|
|
patchfiles to the ticket.</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>If your ticket or pull request doesn't receive any attention within a few days
|
|
you may send an email to
|
|
<email>macports-dev@lists.macports.org</email> and request a
|
|
review and/or commit. Please include a link to the ticket or pull request.</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</section>
|
|
|
|
<section xml:id="project.contributing.updates">
|
|
<title>Port Enhancements</title>
|
|
|
|
<para>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
|
|
<filename>Portfile</filename>. See the <link
|
|
linkend="project.tickets">Ticket Submission Guidelines</link> for
|
|
a description of all fields.</para>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>Create a <filename>Portfile</filename> patch with your changes.
|
|
See <link linkend="development">Portfile Development</link> for
|
|
more information on how to edit Portfiles.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Please run
|
|
<programlisting><prompt>%%</prompt> <userinput>port lint --nitpick $portname</userinput></programlisting>
|
|
where <userinput>$portname</userinput> is the name of the port you
|
|
modified. Please fix any warnings and errors before submitting your
|
|
changes.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Either submit the port update through
|
|
<link xlink:href="https://github.com/macports/macports-ports/pulls">a pull request on GitHub</link>...</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>...or create a Trac ticket.</para>
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>Set the type to <emphasis role="strong">enhancement</emphasis> for
|
|
miscellaneous enhancements, to <emphasis role="strong">defect</emphasis> for bug
|
|
fixes, or to <emphasis role="strong">update</emphasis> for version updates.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Set the component to <emphasis role="strong">ports</emphasis>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Set the <emphasis role="strong">port</emphasis> field to the name of the port you want to change.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
Put the maintainer's email address or GitHub username into the
|
|
<emphasis role="strong">Cc</emphasis> field. You can use
|
|
<programlisting><prompt>%%</prompt> <userinput>port info --maintainer $portname</userinput></programlisting>
|
|
where <userinput>$portname</userinput> is the name of the port you
|
|
want to modify. Note that
|
|
<email>openmaintainer@macports.org</email> and
|
|
<email>nomaintainer@macports.org</email> are not real people and should thus not be Cc'd.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Attach your Portfile patch file and any new or changed patch
|
|
files to the ticket.</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>If your ticket or pull request doesn't receive any attention within a few days
|
|
you may send an email to
|
|
<email>macports-dev@lists.macports.org</email> and request a
|
|
review and/or commit. Please include a link to the ticket or pull request.</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</section>
|
|
|
|
<section xml: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 and a GitHub account.</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 <link
|
|
xlink:href="https://trac.macports.org/">MacPorts Trac</link>,
|
|
(you'll log in with your GitHub account).</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
|
|
open pull requests in GitHub
|
|
(or 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 knowledge 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.macports.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: </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 and GitHub username, grouped together
|
|
with curly braces. Email addresses should be written in the form
|
|
<userinput>domain.tld:localpart</userinput>. (The address is
|
|
obfuscated to prevent email harvesters from automatically grabbing
|
|
your address.) For GitHub usernames, prefix your username with an
|
|
<literal>@</literal> sign. For example, if your email address is
|
|
<literal>julesverne@example.org</literal> and your GitHub username
|
|
is <literal>jverne</literal>, your entry on the
|
|
<option>maintainers</option> line should read
|
|
<literal>{example.org:julesverne @jverne}</literal>.</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 and 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 or GitHub username.</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 -ru $(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>If you are only changing the maintainer,
|
|
<link
|
|
xlink:href="https://github.com/macports/macports-ports/pulls">file
|
|
a pull request on GitHub</link>.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>You may also
|
|
<link
|
|
xlink:href="https://trac.macports.org/newticket">file a new ticket in
|
|
Trac</link> to change the maintainer, though GitHub pull requests are preferred.
|
|
Set <emphasis role="strong">type</emphasis> to
|
|
<emphasis role="strong">enhancement</emphasis>. Leave the
|
|
<emphasis role="strong">milestone</emphasis> field empty. If you added yourself
|
|
as co-maintainer, add the other maintainers in the
|
|
<emphasis role="strong">Cc</emphasis> field. Finally, fill in the
|
|
<emphasis role="strong">port</emphasis> field, set <emphasis role="strong">keywords</emphasis>
|
|
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 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
|
|
<emphasis role="strong">keywords</emphasis> to <userinput>haspatch</userinput> on
|
|
existing tickets.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>If your pull request or ticket doesn't receive any attention within a few days
|
|
you may send an email to
|
|
<email>macports-dev@lists.macports.org</email> and request
|
|
a review and/or commit. Please include a link to the pull
|
|
request or ticket.</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
|
|
<para>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
|
|
<email>macports-dev@lists.macports.org</email> list.</para>
|
|
</section>
|
|
</section>
|
|
|
|
<section xml:id="project.update-policies">
|
|
<title>Port Update Policies</title>
|
|
|
|
<para>Port maintainers normally are given commit privileges to the
|
|
Git repository so they can make updates to their own ports as
|
|
described in <xref linkend="project.membership" />.
|
|
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.</para>
|
|
|
|
<section xml:id="project.update-policies.nonmaintainer">
|
|
<title>Non-Maintainer Port Updates</title>
|
|
|
|
<para>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:</para>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>If a port's maintainer is
|
|
<email>nomaintainer@macports.org</email>, you may feel free to make
|
|
updates and/or take maintainership of the port.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>If a port's maintainer contains the address
|
|
<email>openmaintainer@macports.org</email>, this means that the
|
|
author allows minor updates to the port by other committers without
|
|
contacting them
|
|
first. But permission should still be sought for major
|
|
changes.</para>
|
|
<para>Committers are expected to investigate as thoroughly as
|
|
necessary to confirm that an update is in fact minor. Some
|
|
projects have made quite major changes with only a tiny change
|
|
to the version number. And of course a committer should always
|
|
verify that a port not only builds but works correctly after a
|
|
change, before pushing it.</para>
|
|
<para>Pull requests for maintained ports should not be merged
|
|
by anyone other than
|
|
their creator or the port maintainer until the 72-hour timeout
|
|
period has passed, even if the port is openmaintainer. This is
|
|
because the change is either from a non-committer, or from a
|
|
committer who could have just pushed the change directly, and
|
|
by opening a PR is signalling a desire to have the change
|
|
reviewed by the maintainer.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Create patch file(s) as necessary, attach them to a Trac
|
|
ticket, and assign the ticket to the maintainer (or Cc the
|
|
maintainer, if you are unable to assign tickets).</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Wait for a response from the maintainer. The maintainer should
|
|
apply the patches and close the ticket within 72 hours.</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
|
|
<para>However, for maintained ports without
|
|
<email>openmaintainer@macports.org</email>, there are some conditions
|
|
under which maintainer permission may be waived:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>If the maintainer does not respond within 72 hours, you or
|
|
another committer may review the patches and update the port. The log
|
|
message of this commit must explain that you are taking advantage of
|
|
maintainer timeout and include a reference to the ticket. If you are
|
|
not a committer you may send an email to
|
|
<email>macports-dev@lists.macports.org</email> and request the
|
|
updates be committed.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>A port is abandoned by its current maintainer. A port against
|
|
which a Port Abandoned ticket has been filed (see below) can be
|
|
updated without contacting the maintainer.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>A critical port is broken that affects many users.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
|
|
<section xml:id="project.update-policies.abandonment">
|
|
<title>Port Abandonment</title>
|
|
|
|
<para>A port may be considered abandoned if any of the following apply:</para>
|
|
<itemizedlist>
|
|
<listitem><para>A bug has not been acknowledged for more than three weeks
|
|
after a ticket is filed.</para></listitem>
|
|
<listitem><para>All tickets (and/or pull requests) filed against the port
|
|
have been resolved
|
|
with no input from the maintainer, after the 72-hour timeout,
|
|
for a significant period of time (at least three weeks). This
|
|
needs to involve a reasonable number of tickets; one timeout
|
|
doesn't make a port abandoned.</para></listitem>
|
|
<listitem><para>The listed maintainer address bounces, and no alternate way
|
|
of contacting the maintainer is known.</para></listitem>
|
|
</itemizedlist>
|
|
<para>If you wish to initiate the Port Abandonment
|
|
protocol and optionally volunteer as the new maintainer:</para>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>File a new Trac ticket with the summary line: [Port
|
|
Abandoned] <emphasis role="strong">portname</emphasis>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>The ticket should be assigned to the maintainer. Non-macports team members should Cc the maintainer.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Set the ticket Type to Defect.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>In the Description field, refer to any unacknowledged ticket(s).</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>In the Port field, indicate which port is abandoned.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>The Port Abandoned ticket may be closed when the new
|
|
maintainer is assigned, and the original ticket(s) with the updates may
|
|
be resolved as usual. The former maintainer should be removed from all other tickets on
|
|
which they were assigned as owner. The Port Abandoned ticket should stay open
|
|
for the usual 72-hour timeout period, to give the maintainer one last chance
|
|
to indicate that they have not actually abandoned the port.</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</section>
|
|
</section>
|
|
|
|
<section xml:id="project.docs">
|
|
<title>Updating Documentation</title>
|
|
|
|
<section xml:id="project.docs.guide">
|
|
<title>Updating the Guide</title>
|
|
|
|
<para>
|
|
The sources for this guide are kept in a <link xlink:href="https://github.com/macports/macports-guide">
|
|
Git repository on GitHub</link>. If you spot any error or outdated information, you are
|
|
encouraged to submit a pull request following the steps outlined below.
|
|
</para>
|
|
|
|
<para>
|
|
We use a triangular workflow to carry changes from contributors to the
|
|
project. You get the latest guide source code from the main repository
|
|
on GitHub, updating your own "cloned" copy of the repository on your
|
|
workstation. You make changes on your workstation, in a Git branch. You
|
|
push the Git branch with your changes to your "forked" copy of the
|
|
repository in your own GitHub account. Then GitHub helps turn that
|
|
branch into a "pull request". MacPorts developers can review and
|
|
discuss the pull request with you, and finally decide whether to
|
|
accept it. This workflow is described in GitHub's guide,
|
|
<link xlink:href="https://guides.github.com/activities/forking/">
|
|
<citetitle>Forking Projects</citetitle></link>.
|
|
</para>
|
|
|
|
<section xml:id="project.docs.guide.one-time">
|
|
<title>Setting Up the Parts of the Workflow</title>
|
|
|
|
<para>Follow these one-time steps to set up the parts of the workflow.</para>
|
|
|
|
<procedure>
|
|
<step>
|
|
<para>With your web browser, log in to GitHub.
|
|
Go to this guide's main Git repository at
|
|
<link xlink:href="https://github.com/macports/macports-guide" />.</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>Fork your own copy of the main guide repository.
|
|
Click the <guibutton>Fork</guibutton> button, at the top-right of
|
|
the repository window.
|
|
A dialogue may appear: "Where should we fork macports-guide?"
|
|
Select your GitHub username. A message appears,
|
|
"Forking macports/macports-base. It should only take a few seconds."
|
|
Then GitHub moves you to a page labelled,
|
|
"<replaceable>username</replaceable>/macports-guide, forked from
|
|
macports/macports-guide".
|
|
This page shows your "forked" copy of the repository, in your
|
|
own GitHub account.
|
|
</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>On your workstation's command line, clone a copy of
|
|
the main guide repository. Start in a directory which can contain
|
|
the working directory for your local "clone" copy.</para>
|
|
|
|
<programlisting><!-- [use comments to make programlisting ignore indents]
|
|
--><prompt>$</prompt> <userinput>git clone https://github.com/macports/macports-guide.git</userinput>
|
|
<!-- --><prompt>$</prompt> <userinput>cd macports-guide</userinput>
|
|
<!-- --><prompt>$</prompt> <userinput>git remote add <replaceable>username</replaceable> https://github.com/<replaceable>username</replaceable>/macports-guide.git</userinput>
|
|
<!-- --></programlisting>
|
|
</step>
|
|
|
|
<step>
|
|
<para>Install the required ports:</para>
|
|
|
|
<programlisting><prompt>$</prompt> <userinput>sudo port install libxml2 libxslt docbook-xsl-ns docbook-xml-5.0</userinput></programlisting>
|
|
</step>
|
|
</procedure>
|
|
</section>
|
|
|
|
<section xml:id="project.docs.guide.each-time">
|
|
<title>Proposing a Change</title>
|
|
|
|
<para>For each change you want to make, follow these steps through the
|
|
triangular workflow. In general, for one pass through this workflow,
|
|
make only one change or set of related changes, in one area of
|
|
the documentation.
|
|
When changing different things, it is preferable to propose separate
|
|
pull requests.</para>
|
|
|
|
<procedure>
|
|
<step>
|
|
<para>From your workstation's command line, within your local
|
|
repository directory, switch to your <literal>master</literal>
|
|
branch. Then, pull the latest contents of the master repository
|
|
to make your repository current.</para>
|
|
|
|
<programlisting><!-- [use comments to make programlisting ignore indents]
|
|
--><prompt>$</prompt> <userinput>cd macports-guide</userinput>
|
|
<!-- --><prompt>$</prompt> <userinput>git checkout master</userinput>
|
|
<!-- --><prompt>$</prompt> <userinput>git pull origin</userinput>
|
|
<!-- --></programlisting>
|
|
</step>
|
|
|
|
<step>
|
|
<para>Create a Git branch off the <literal>master</literal> branch
|
|
to hold your changes. The <replaceable>branch-name</replaceable> is
|
|
a concise string which describes the effect of your change. Generally,
|
|
use words of ASCII letters and digits, separated by underscore
|
|
<literal>'_'</literal> or dash <literal>'-'</literal>,
|
|
e.g. <userinput>clarify_branch_creation_steps</userinput>.
|
|
(See <link xlink:href="https://git-scm.com/docs/git-check-ref-format">
|
|
<citetitle>git check-ref-format</citetitle></link> for detailed
|
|
limitations.)
|
|
If your change fixes a Trac ticket, include the ticket number in
|
|
the branch name, e.g. <userinput>configure-compiler-60331</userinput>.
|
|
</para>
|
|
|
|
<programlisting><!-- [use comments to make programlisting ignore indents]
|
|
--><prompt>$</prompt> <userinput>git checkout -b <replaceable>branch-name</replaceable></userinput>
|
|
<!-- --></programlisting>
|
|
</step>
|
|
|
|
<step>
|
|
<para>Make your changes to the file in the
|
|
<filename>guide/xml/</filename> directory that corresponds to the
|
|
section you want to make changes to.</para>
|
|
|
|
<programlisting><!-- [use comments to make programlisting ignore indents]
|
|
--><prompt>$</prompt> <userinput>$EDITOR guide/xml/<replaceable>guide.xml</replaceable></userinput>
|
|
<!-- --></programlisting>
|
|
</step>
|
|
|
|
<step>
|
|
<para>Verify your changes are still valid XML.
|
|
If the <command>make validate</command> command reports
|
|
errors, fix the XML sources until you see no more error
|
|
messages.</para>
|
|
|
|
<programlisting><!-- [use comments to make programlisting ignore indents]
|
|
--><prompt>$</prompt> <userinput>make validate</userinput>
|
|
<!-- --></programlisting>
|
|
</step>
|
|
|
|
<step>
|
|
<para>Convert the guide to HTML, and proofread the new version in
|
|
your browser.</para>
|
|
|
|
<programlisting><!-- [use comments to make programlisting ignore indents]
|
|
--><prompt>$</prompt> <userinput>make guide</userinput>
|
|
<!-- --><prompt>$</prompt> <userinput>open guide/html/index.html</userinput>
|
|
<!-- --></programlisting>
|
|
</step>
|
|
|
|
<step>
|
|
<para>Commit your changes to the local branch and describe your
|
|
changes in the commit message. See also our wiki page, <link
|
|
xlink:href="https://trac.macports.org/wiki/CommitMessages">
|
|
<citetitle>CommitMessages</citetitle></link>,
|
|
which explains how to write good commit messages.</para>
|
|
|
|
<programlisting><!-- [use comments to make programlisting ignore indents]
|
|
--><prompt>$</prompt> <userinput>git commit -a</userinput>
|
|
<!-- --></programlisting>
|
|
</step>
|
|
|
|
<step>
|
|
<para>Push your local branch to your fork of the guide's repository
|
|
on GitHub. <replaceable>username</replaceable> is your GitHub
|
|
user name, under which your fork resides.</para>
|
|
|
|
<programlisting><!-- [use comments to make programlisting ignore indents]
|
|
--><prompt>$</prompt> <userinput>git push <replaceable>username</replaceable></userinput>
|
|
<!-- --></programlisting>
|
|
</step>
|
|
|
|
<step>
|
|
<para>Next, turn your branch into a "pull request" (PR) on GitHub.
|
|
</para>
|
|
|
|
<para>With your web browser, go to this guide's main Git repository
|
|
at <link xlink:href="https://github.com/macports/macports-guide" />.
|
|
</para>
|
|
|
|
<para>GitHub will likely show you a message that a branch on your
|
|
forked repo, with your <replaceable>branch-name</replaceable>, "had
|
|
recent pushes". There is a green button,
|
|
<guibutton>Compare & pull request</guibutton>. Push this button.
|
|
</para>
|
|
|
|
<para>If GitHub does not show you that message, create the pull request
|
|
yourself. Click on the "Pull requests" tab. Click on the green button,
|
|
<guibutton>New pull request</guibutton>. The page changes to say
|
|
"Compare changes", and there are a pair of buttons,
|
|
"base: master" and "compare: master".
|
|
Click on the "compare: master" button, on the right. A dialogue
|
|
appears, "Choose a head ref".
|
|
Type your GitHub username, followed by colon <literal>':'</literal>.
|
|
The two buttons become four, with the rightmost button reading "compare:".
|
|
Click on the "compare:" button. The list of your branches appears.
|
|
Click on the branch which you want to turn into a pull request.
|
|
A green <guibutton>Create pull request</guibutton> button
|
|
appears, slightly further down the page. Click on this button.
|
|
</para>
|
|
|
|
<para>A dialogue appears. The first line of your commit message
|
|
is in the title, and the rest of your commit message is in the body.
|
|
Edit these as necessary, then confirm. Your pull request now
|
|
appears in the list of pull requests.</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>Now, monitor your GitHub account for messages.
|
|
MacPorts developers may comments and discussion about your pull
|
|
request. Respond to comments as necessary.</para>
|
|
|
|
<para>You may want to modify your proposed change. Modify it by
|
|
repeating the "make your changes" step above, and all the subsequent
|
|
steps through pushing your branch to your fork on GitHub.
|
|
GitHub will incorporate changes to your fork into the pull request.
|
|
</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>Once the MacPorts developers are satisfied with your pull
|
|
request, they will merge it with the main guide respository.</para>
|
|
</step>
|
|
</procedure>
|
|
</section>
|
|
</section>
|
|
</section>
|
|
|
|
<section xml:id="project.membership">
|
|
<title>MacPorts Membership</title>
|
|
|
|
<para>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:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Contributing new ports.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Fixing bugs in existing ports.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Volunteering as a maintainer of non-maintained ports.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Involvement on MacPorts development and/or user support mailing lists.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Contributing with documentation.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>To apply for MacPorts commit rights, send a brief email to the
|
|
PortMgr team at <email>macports-mgr@lists.macports.org</email> entitled
|
|
"Commit access: <replaceable>Your Name</replaceable>" with the
|
|
following contents:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>a description of your application and why you think you deserve
|
|
commit rights. Include evidence of contributions to MacPorts as described
|
|
above; at best add direct links to Trac tickets or Trac searches that
|
|
make the review easier for the PortMgr team.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>your github username. This will be used as the identity the
|
|
"handle", as part of your <literal><replaceable>handle</replaceable>@macports.org</literal>
|
|
alias.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>a real e-mail address to which you'd like your MacPorts alias to forward.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>The PortMgr team will consider all applications and provide an appropriate
|
|
response as soon as they get to it.</para>
|
|
|
|
</section>
|
|
|
|
<section xml:id="project.portmgr">
|
|
<title>The PortMgr Team</title>
|
|
|
|
<para>The MacPorts PortMgr team is the steering group for The MacPorts
|
|
Project. Its membership is usually determined by public elections among
|
|
project members; the current members of the team can be found on the
|
|
<link xlink:href="https://trac.macports.org/wiki/MacPortsDevelopers">MacPorts
|
|
Developers wiki page</link>.</para>
|
|
|
|
<para>They are responsible for matters such as:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>approving new project members (i.e., granting commit
|
|
rights);</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>setting general guidelines for the project;</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>dispute resolution;</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>managing the projects infrastructure; and</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>engineering releases.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
</section>
|
|
</chapter>
|