Bug 66775

Summary:	[patch] clarification to committer's guide that port names should not contain version numbers
Product:	Documentation	Reporter:	Oliver Eikemeier <eikemeier>
Component:	Books & Articles	Assignee:	Peter Pentchev <roam>
Status:	Closed FIXED
Severity:	Affects Only Me
Priority:	Normal
Version:	Latest
Hardware:	Any
OS:	Any

Description Oliver Eikemeier 2004-05-17 21:20:17 UTC

Ports documentation should state more clearly that the version number of a
port should not be part of its name.

Fix: 

The Committers Guide
  <http://www.freebsd.org/doc/en_US.ISO8859-1/articles/committers-guide/ports.html#Q12.2.3.>
has the following sentence:

  "Upgrade the copied port to the new version (remember to change the PORTNAME 
   so there are not duplicate ports with the same name)."

Which should probably read

  "Upgrade the copied port to the new version (remember to change the LATEST_LINK 
   so there are not duplicate ports with the same name)."

since changing the ports name is usually a bad idea.

Also there is is new tool chkmodules, which could be called before or after operations
on modules: 

env PORTSDIR=/path/to/ports CVSROOT=/path/to/cvsroot /path/to/ports/Tools/scripts/chkmodules.pl


The Porter's Handbook
  <http://www.freebsd.org/doc/en_US.ISO8859-1/books/porters-handbook/makefile-naming.html#PORTING-PKGNAME>
should contain something about port names, like:

  "The version number should not be part of the ports name (PORTNAME), if you 
   have a port of apache httpd 2.1, use
     PORTNAME=apache
     PORTVERSION=2.1
   and set
     LATEST_LINK=${PKGNAMEPREFIX}apache21${PKGNAMESUFFIX}
   to avoid conflicts with other versions of apache ports."

Comment 1 krion 2004-05-17 21:33:08 UTC

Hi,

On Mon, May 17, 2004 at 10:17:31PM +0200, Oliver Eikemeier wrote:
 
> The Committers Guide
>   <http://www.freebsd.org/doc/en_US.ISO8859-1/articles/committers-guide/ports.html#Q12.2.3.>
> has the following sentence:
> 
>   "Upgrade the copied port to the new version (remember to change the PORTNAME 
>    so there are not duplicate ports with the same name)."
> 
> Which should probably read
> 
>   "Upgrade the copied port to the new version (remember to change the LATEST_LINK 
>    so there are not duplicate ports with the same name)."
> 
> since changing the ports name is usually a bad idea.


There are cases when ports have to be renamed, I don't think
LATEST_LINK could help in this situation.  Why don't propose to
use both, depending on purpose ?

-Kirill

Comment 2 Mark Linimon freebsd_committer

2004-05-17 22:10:12 UTC

Responsible Changed
From-To: freebsd-doc->linimon

I'm probably the logical choice for this.

Comment 3 Mark Linimon freebsd_committer

2004-06-30 03:22:16 UTC

Responsible Changed
From-To: linimon->freebsd-doc

I don't seem to be getting around to this.

Comment 4 Aasmund Eikli 2004-07-31 21:52:16 UTC

Doc diffs to reflect suggestions:

--- article.sgml        Tue Jul 27 16:34:49 2004
+++ article.sgml        Sat Jul 31 15:35:56 2004
@@ -2418,7 +2418,9 @@
                   <step>
                     <para>Upgrade the copied port to the new version 
(remember
                       to change the <makevar>PORTNAME</makevar> so there
-                     are not duplicate ports with the same name).</para>
+                     are not duplicate ports with the same name).
+                     Alternatively, change <makevar>LATEST_LINK</makevar>
+                     depending on the purpose.</para>
                   </step>

                   <step>

and

--- book.sgml   Sat Jul 31 15:40:21 2004
+++ book.sgml   Sat Jul 31 15:52:11 2004
@@ -1064,7 +1064,10 @@
             <literal>Data::Dumper</literal> module becomes
             <literal>p5-Data-Dumper</literal>.  If the software in question
             has numbers, hyphens, or underscores in its name, you may 
include
-           them as well (like <literal>kinput2</literal>).</para>
+           them as well (like <literal>kinput2</literal>).
+           Make sure that the <makevar>PORTNAME</makevar> variable and the
+           <makevar>PORTVERSION</makevar> variable contains the name 
and the
+           version number of the port respectively. You should not mix 
the two.</para>
         </listitem>

         <listitem>

Comment 5 Peter Pentchev 2004-08-09 13:31:08 UTC

On Sat, Jul 31, 2004 at 09:00:45PM +0000, Aasmund Eikli wrote:
> The following reply was made to PR docs/66775; it has been noted by GNATS.
> 
> From: Aasmund Eikli <inter@o12a.com>
> To: freebsd-gnats-submit@FreeBSD.org
> Cc:  
> Subject: Re: docs/66775: Clarification that port names should not contain
>  version numbers
> Date: Sat, 31 Jul 2004 22:52:16 +0200
> 
>  Doc diffs to reflect suggestions:
>  
>  --- article.sgml        Tue Jul 27 16:34:49 2004
>  +++ article.sgml        Sat Jul 31 15:35:56 2004
>  @@ -2418,7 +2418,9 @@
>                     <step>
>                       <para>Upgrade the copied port to the new version 
>  (remember
>                         to change the <makevar>PORTNAME</makevar> so there
>  -                     are not duplicate ports with the same name).</para>
>  +                     are not duplicate ports with the same name).
>  +                     Alternatively, change <makevar>LATEST_LINK</makevar>
>  +                     depending on the purpose.</para>
>                     </step>

I think that 'remmeber to change the PORTNAME' and 'change LATEST_LINK'
clauses should be at the same level of "nesting" (parenthesized or not)
to avoid confusion - this way, it might seem that changing LATEST_LINK
is an alternative to upgrading the port :)  How about something like
this instead?

Index: doc/en_US.ISO8859-1/articles/committers-guide/article.sgml
===================================================================
RCS file: /home/ncvs/doc/en_US.ISO8859-1/articles/committers-guide/article.sgml,v
retrieving revision 1.207
diff -u -r1.207 article.sgml
--- doc/en_US.ISO8859-1/articles/committers-guide/article.sgml	8 Aug 2004 13:43:53 -0000	1.207
+++ doc/en_US.ISO8859-1/articles/committers-guide/article.sgml	9 Aug 2004 12:21:10 -0000
@@ -2431,9 +2431,10 @@
 
 		<procedure>
 		  <step>
-		    <para>Upgrade the copied port to the new version (remember
-		      to change the <makevar>PORTNAME</makevar> so there
-		      are not duplicate ports with the same name).</para>
+		    <para>Upgrade the copied port to the new version.  Remember
+		      to change either the <makevar>PORTNAME</makevar> or
+		      the <makevar>LATEST_LINK</makevar> variable so there
+		      are not duplicate ports with the same name.</para>
 		  </step>
 
 		  <step>

>  --- book.sgml   Sat Jul 31 15:40:21 2004
>  +++ book.sgml   Sat Jul 31 15:52:11 2004
>  @@ -1064,7 +1064,10 @@
>               <literal>Data::Dumper</literal> module becomes
>               <literal>p5-Data-Dumper</literal>.  If the software in question
>               has numbers, hyphens, or underscores in its name, you may 
>  include
>  -           them as well (like <literal>kinput2</literal>).</para>
>  +           them as well (like <literal>kinput2</literal>).
>  +           Make sure that the <makevar>PORTNAME</makevar> variable and the
>  +           <makevar>PORTVERSION</makevar> variable contains the name 

ITYM 'contain' here, since both variables form the sentence subject :)

>  and the
>  +           version number of the port respectively. You should not mix 
>  the two.</para>

A minor point, but I've gathered the impression that two spaces are
preferred before the start of a new sentence.  How about this?

Index: doc/en_US.ISO8859-1/books/porters-handbook/book.sgml
===================================================================
RCS file: /home/dcvs/doc/en_US.ISO8859-1/books/porters-handbook/book.sgml,v
retrieving revision 1.476
diff -u -r1.476 book.sgml
--- doc/en_US.ISO8859-1/books/porters-handbook/book.sgml	9 Aug 2004 11:51:37 -0000	1.476
+++ doc/en_US.ISO8859-1/books/porters-handbook/book.sgml	9 Aug 2004 12:29:31 -0000
@@ -1071,7 +1071,11 @@
 	    <literal>Data::Dumper</literal> module becomes
 	    <literal>p5-Data-Dumper</literal>.  If the software in question
 	    has numbers, hyphens, or underscores in its name, you may include
-	    them as well (like <literal>kinput2</literal>).</para>
+	    them as well (like <literal>kinput2</literal>).  Make sure that
+	    the <makevar>PORTNAME</makevar> and
+	    <makevar>PORTVERSION</makevar> variables contain the name and
+	    the version of the port respectively.  You should not mix the
+	    two.</para>
 	</listitem>
 
 	<listitem>

Thanks for your work on this :)

G'luck,
Peter

-- 
Peter Pentchev	roam@ringlet.net    roam@cnsys.bg    roam@FreeBSD.org
PGP key:	http://people.FreeBSD.org/~roam/roam.key.asc
Key fingerprint	FDBA FD79 C26F 3C51 C95E  DF9E ED18 B68D 1619 4553
This sentence would be seven words long if it were six words shorter.

Comment 6 Aasmund Eikli 2004-08-10 10:13:00 UTC

Looks good!

A very minor point though, shouldnt "not duplicate ports" be "no 
duplicate ports"?

I'm new at this, so probably very rusty.

Cheers
Aasmund

Peter Pentchev wrote:
> On Sat, Jul 31, 2004 at 09:00:45PM +0000, Aasmund Eikli wrote:
> 
>>The following reply was made to PR docs/66775; it has been noted by GNATS.
>>
>>From: Aasmund Eikli <inter@o12a.com>
>>To: freebsd-gnats-submit@FreeBSD.org
>>Cc:  
>>Subject: Re: docs/66775: Clarification that port names should not contain
>> version numbers
>>Date: Sat, 31 Jul 2004 22:52:16 +0200
>>
>> Doc diffs to reflect suggestions:
>> 
>> --- article.sgml        Tue Jul 27 16:34:49 2004
>> +++ article.sgml        Sat Jul 31 15:35:56 2004
>> @@ -2418,7 +2418,9 @@
>>                    <step>
>>                      <para>Upgrade the copied port to the new version 
>> (remember
>>                        to change the <makevar>PORTNAME</makevar> so there
>> -                     are not duplicate ports with the same name).</para>
>> +                     are not duplicate ports with the same name).
>> +                     Alternatively, change <makevar>LATEST_LINK</makevar>
>> +                     depending on the purpose.</para>
>>                    </step>
> 
> 
> I think that 'remmeber to change the PORTNAME' and 'change LATEST_LINK'
> clauses should be at the same level of "nesting" (parenthesized or not)
> to avoid confusion - this way, it might seem that changing LATEST_LINK
> is an alternative to upgrading the port :)  How about something like
> this instead?
> 
> Index: doc/en_US.ISO8859-1/articles/committers-guide/article.sgml
> ===================================================================
> RCS file: /home/ncvs/doc/en_US.ISO8859-1/articles/committers-guide/article.sgml,v
> retrieving revision 1.207
> diff -u -r1.207 article.sgml
> --- doc/en_US.ISO8859-1/articles/committers-guide/article.sgml	8 Aug 2004 13:43:53 -0000	1.207
> +++ doc/en_US.ISO8859-1/articles/committers-guide/article.sgml	9 Aug 2004 12:21:10 -0000
> @@ -2431,9 +2431,10 @@
>  
>  		<procedure>
>  		  <step>
> -		    <para>Upgrade the copied port to the new version (remember
> -		      to change the <makevar>PORTNAME</makevar> so there
> -		      are not duplicate ports with the same name).</para>
> +		    <para>Upgrade the copied port to the new version.  Remember
> +		      to change either the <makevar>PORTNAME</makevar> or
> +		      the <makevar>LATEST_LINK</makevar> variable so there
> +		      are not duplicate ports with the same name.</para>
>  		  </step>
>  
>  		  <step>
> 
>> --- book.sgml   Sat Jul 31 15:40:21 2004
>> +++ book.sgml   Sat Jul 31 15:52:11 2004
>> @@ -1064,7 +1064,10 @@
>>              <literal>Data::Dumper</literal> module becomes
>>              <literal>p5-Data-Dumper</literal>.  If the software in question
>>              has numbers, hyphens, or underscores in its name, you may 
>> include
>> -           them as well (like <literal>kinput2</literal>).</para>
>> +           them as well (like <literal>kinput2</literal>).
>> +           Make sure that the <makevar>PORTNAME</makevar> variable and the
>> +           <makevar>PORTVERSION</makevar> variable contains the name 
> 
> 
> ITYM 'contain' here, since both variables form the sentence subject :)
> 
> 
>> and the
>> +           version number of the port respectively. You should not mix 
>> the two.</para>
> 
> 
> A minor point, but I've gathered the impression that two spaces are
> preferred before the start of a new sentence.  How about this?
> 
> Index: doc/en_US.ISO8859-1/books/porters-handbook/book.sgml
> ===================================================================
> RCS file: /home/dcvs/doc/en_US.ISO8859-1/books/porters-handbook/book.sgml,v
> retrieving revision 1.476
> diff -u -r1.476 book.sgml
> --- doc/en_US.ISO8859-1/books/porters-handbook/book.sgml	9 Aug 2004 11:51:37 -0000	1.476
> +++ doc/en_US.ISO8859-1/books/porters-handbook/book.sgml	9 Aug 2004 12:29:31 -0000
> @@ -1071,7 +1071,11 @@
>  	    <literal>Data::Dumper</literal> module becomes
>  	    <literal>p5-Data-Dumper</literal>.  If the software in question
>  	    has numbers, hyphens, or underscores in its name, you may include
> -	    them as well (like <literal>kinput2</literal>).</para>
> +	    them as well (like <literal>kinput2</literal>).  Make sure that
> +	    the <makevar>PORTNAME</makevar> and
> +	    <makevar>PORTVERSION</makevar> variables contain the name and
> +	    the version of the port respectively.  You should not mix the
> +	    two.</para>
>  	</listitem>
>  
>  	<listitem>
> 
> Thanks for your work on this :)
> 
> G'luck,
> Peter
>

Comment 7 Oliver Eikemeier 2004-08-10 15:02:21 UTC

Aasmund Eikli wrote:

> From: Aasmund Eikli <inter@o12a.com>
> To: Peter Pentchev <roam@ringlet.net>
> Cc: bug-followup@freebsd.org
> Subject: Re: docs/66775: Clarification that port names should not 
> contain
>  version numbers
> Date: Tue, 10 Aug 2004 11:13:00 +0200
>
>  Looks good!
>
>  A very minor point though, shouldnt "not duplicate ports" be "no
>  duplicate ports"?
> [...]
>  Peter Pentchev wrote:
>>
>> Index: doc/en_US.ISO8859-1/articles/committers-guide/article.sgml
>> ===================================================================
>> RCS file: /home/ncvs/doc/en_US.ISO8859-1/articles/committers-
>> guide/article.sgml,v
>> retrieving revision 1.207
>> diff -u -r1.207 article.sgml
>> --- doc/en_US.ISO8859-1/articles/committers-guide/article.sgml	8 Aug 2004 
>> 13:43:53 -0000	1.207
>> +++ doc/en_US.ISO8859-1/articles/committers-guide/article.sgml	9 Aug 2004 
>> 12:21:10 -0000
>> @@ -2431,9 +2431,10 @@
>>
>>  		<procedure>
>>  		  <step>
>> -		    <para>Upgrade the copied port to the new version (remember
>> -		      to change the <makevar>PORTNAME</makevar> so there
>> -		      are not duplicate ports with the same name).</para>
>> +		    <para>Upgrade the copied port to the new version.  Remember
>> +		      to change either the <makevar>PORTNAME</makevar> or
>> +		      the <makevar>LATEST_LINK</makevar> variable so there
>> +		      are not duplicate ports with the same name.</para>
>>  		  </step>

As said before, I would prefer suggesting to change LATEST_LINK only, 
and PORTNAME only in rare cases. The reader might get the impression 
that `apache-1.3' and `apache-2.0' have the same name, although they 
don't.

>> Index: doc/en_US.ISO8859-1/books/porters-handbook/book.sgml
>> ===================================================================
>> RCS file: /home/dcvs/doc/en_US.ISO8859-1/books/porters-
>> handbook/book.sgml,v
>> retrieving revision 1.476
>> diff -u -r1.476 book.sgml
>> --- doc/en_US.ISO8859-1/books/porters-handbook/book.sgml	9 Aug 2004 11:51:
>> 37 -0000	1.476
>> +++ doc/en_US.ISO8859-1/books/porters-handbook/book.sgml	9 Aug 2004 12:29:
>> 31 -0000
>> @@ -1071,7 +1071,11 @@
>>  	    <literal>Data::Dumper</literal> module becomes
>>  	    <literal>p5-Data-Dumper</literal>.  If the software in question
>>  	    has numbers, hyphens, or underscores in its name, you may 
>> include
>> -	    them as well (like <literal>kinput2</literal>).</para>
>> +	    them as well (like <literal>kinput2</literal>).  Make sure that
>> +	    the <makevar>PORTNAME</makevar> and
>> +	    <makevar>PORTVERSION</makevar> variables contain the name and
>> +	    the version of the port respectively.  You should not mix the
>> +	    two.</para>
>>  	</listitem>

Same here. Perhaps `The version number should not be part of PORTNAME 
(like apache-2.0), except when the original distribution explicitly name 
it that way (like libxml2-2.6).'

-Oliver

Comment 8 Tom Rhodes freebsd_committer

2004-08-20 05:02:14 UTC

Responsible Changed
From-To: freebsd-doc->roam

Switch this to Peter as he not only commented and provided a patch, 
but him and originator (Oliver eik@) are both ports committers and 
should be able to close this together.

Comment 9 dfilter service freebsd_committer

2007-04-25 14:13:29 UTC

roam        2007-04-25 13:13:23 UTC

  FreeBSD doc repository

  Modified files:
    en_US.ISO8859-1/articles/committers-guide article.sgml 
    en_US.ISO8859-1/books/porters-handbook book.sgml 
  Log:
  Describe and recommend the use of the LATEST_LINK variable in
  the Committer's Guide ports repo-copy section and in the package naming
  section of the Porter's Handbook.  In the end, I wrote something that
  turned out quite a bit different and somewhat more long-winded than
  the suggestions in the PR, but LATEST_LINK was not documented anywhere
  until now, so there :)
  
  PR:             66775
  Submitted by:   eik
  
  Revision  Changes    Path
  1.261     +15 -3     doc/en_US.ISO8859-1/articles/committers-guide/article.sgml
  1.826     +44 -6     doc/en_US.ISO8859-1/books/porters-handbook/book.sgml
_______________________________________________
cvs-all@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/cvs-all
To unsubscribe, send any mail to "cvs-all-unsubscribe@freebsd.org"

Comment 10 Peter Pentchev freebsd_committer

2007-04-25 14:23:00 UTC

State Changed
From-To: open->closed

I have just committed a description of LATEST_LINK to the Porter's Handbook 
and recommendations of its use both there and in the Committer's Guide. 
Thanks for bringing this up and for the suggestions, and sorry it took 
me so long!