Rework the section on proposing a new category. Some of the text
comes from the Committer's Guide, where it really didn't belong.
This commit is contained in:
Mark Linimon
parent
45ab797c4f
commit
a9ca7de11f
Notes:
svn2git
2020-12-08 03:00:23 +00:00
svn path=/head/; revision=23309
1 changed files with 120 additions and 17 deletions
|
|
@ -1290,23 +1290,6 @@ PORTEPOCH= 1</programlisting>
|
|||
the first category. See <link
|
||||
linkend="choosing-categories">below</link> for more
|
||||
discussion about how to pick the right categories.</para>
|
||||
|
||||
<para>If your port truly belongs to something that is different from
|
||||
all the existing ones, you can even create a new category name. In
|
||||
that case, please send mail to the &a.ports; to propose a new
|
||||
category. However, in general, until there are more than a
|
||||
handful of ports which could be reclassified into the category
|
||||
you propose, you will probably be turned down.</para>
|
||||
|
||||
<note><para>Occasionally someone proposes reorganizing the categories
|
||||
with either a 2-level structure, or some other kind of keyword
|
||||
structure. To date, nothing has come of any of these proposals
|
||||
because, while they are very easy to make, the effort involved to
|
||||
retrofit the entire existing ports collection with any kind of
|
||||
reorganization is daunting to say the very least. Please read
|
||||
the history of these proposals in the mailing list archives before
|
||||
you post this idea; furthermore, you should be prepared to be
|
||||
challenged to offer a working prototype.</para></note>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="porting-categories">
|
||||
|
|
@ -1966,6 +1949,126 @@ PORTEPOCH= 1</programlisting>
|
|||
This causes unnecessary and undesirable bloat in the master
|
||||
source repository.</para>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="proposing-categories">
|
||||
<title>Proposing a new category</title>
|
||||
|
||||
<para>As the Ports Collection has grown over time, various new
|
||||
categories have been introduced. New categories can either
|
||||
be <emphasis>virtual</emphasis> categories—those that do
|
||||
not have a corresponding subdirectory in the ports tree—
|
||||
or <emphasis>physical</emphasis> categories—those that
|
||||
do. The following text dicusses the issues involved in creating
|
||||
a new physical category so that you can understand them before
|
||||
you propose one.</para>
|
||||
|
||||
<para>Our existing practice has been to avoid creating a new
|
||||
physical category unless either a large number of ports would
|
||||
logically belong to it, or the ports that would belong to it
|
||||
are a logically distinct group that is of limited general
|
||||
interest (for instance, categories related to spoken human
|
||||
languages), or preferably both.</para>
|
||||
|
||||
<para>The rationale for this is that such a change creates a
|
||||
<ulink url="&url.articles.committers-guide;/#ports">
|
||||
fair amount of work</ulink> for both the committers and also
|
||||
for all users who track changes to the Ports Collection. In
|
||||
addition, proposed category changes just naturally seem to
|
||||
attract controversy. (Perhaps this is because there is no
|
||||
clear consensus on when a category is <quote>too big</quote>,
|
||||
nor whether categories should lend themselves to browsing (and
|
||||
thus what number of categories would be an ideal number), and
|
||||
so forth.)</para>
|
||||
|
||||
<para>Here is the procedure:</para>
|
||||
|
||||
<procedure>
|
||||
<step>
|
||||
<para>Propose the new category on &a.ports;. You should
|
||||
include a detailed rationale for the new category,
|
||||
including why you feel the existing categories are not
|
||||
sufficient, and the list of existing ports proposed to move.
|
||||
(If there are new ports pending in
|
||||
<application>GNATS</application> that would fit this
|
||||
category, list them too.) If you are the maintainer and/or
|
||||
submitter, respectively, mention that as it may help you
|
||||
to make your case.</para>
|
||||
</step>
|
||||
|
||||
<step>
|
||||
<para>Participate in the discussion.</para>
|
||||
</step>
|
||||
|
||||
<step>
|
||||
<para>If it seems that there is support for your idea,
|
||||
file a PR which includes both the rationale and the list
|
||||
of existing ports that need to be moved. Ideally, this
|
||||
PR should also include patches for the following:</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para><filename>Makefile</filename>s for the
|
||||
new ports once they are repocopied</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><filename>Makefile</filename> for the
|
||||
new category</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><filename>Makefile</filename> for the
|
||||
old ports' categories</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><filename>Makefile</filename>s for ports
|
||||
that depend on the old ports</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>(for extra credit, you can include the other
|
||||
files that have to changes, as per the procedure
|
||||
in the Committer's Guide.)</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</step>
|
||||
|
||||
<step>
|
||||
<para>Since it affects the ports infrastructure and involves
|
||||
not only performing repo-copies but also possibly running
|
||||
regression tests on the build cluster, the PR should be
|
||||
assigned to the &a.portmgr;.</para>
|
||||
</step>
|
||||
|
||||
<step>
|
||||
<para>If that PR is approved, a committer will need to follow
|
||||
the rest of the procedure that is
|
||||
<ulink url="&url.articles.committers-guide;/#ports">
|
||||
outlined in the Committer's Guide</ulink>.</para>
|
||||
</step>
|
||||
</procedure>
|
||||
|
||||
<para>Proposing a new virtual category should be similar to
|
||||
the above but much less involved, since no ports will
|
||||
actually have to move. In this case, the only patches to
|
||||
include in the PR would be those to add the new category to the
|
||||
<makevar>CATEGORIES</makevar>s of the affected ports.</para>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="proposing-reorg">
|
||||
<title>Proposing reorganizing all the categories</title>
|
||||
|
||||
<para>Occasionally someone proposes reorganizing the categories
|
||||
with either a 2-level structure, or some other kind of keyword
|
||||
structure. To date, nothing has come of any of these proposals
|
||||
because, while they are very easy to make, the effort involved to
|
||||
retrofit the entire existing ports collection with any kind of
|
||||
reorganization is daunting to say the very least. Please read
|
||||
the history of these proposals in the mailing list archives before
|
||||
you post this idea; furthermore, you should be prepared to be
|
||||
challenged to offer a working prototype.</para>
|
||||
</sect2>
|
||||
</sect1>
|
||||
|
||||
<sect1 id="makefile-distfiles">
|
||||
|
|
|
|||
Loading…
Reference in a new issue