From eikemeier@fillmore-labs.com  Mon May 17 13:17:55 2004
Return-Path: <eikemeier@fillmore-labs.com>
Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125])
	by hub.freebsd.org (Postfix) with ESMTP id 4705016A589
	for <freebsd-gnats-submit@FreeBSD.org>; Mon, 17 May 2004 13:17:55 -0700 (PDT)
Received: from fillmore.dyndns.org (port-212-202-49-130.reverse.qsc.de [212.202.49.130])
	by mx1.FreeBSD.org (Postfix) with ESMTP id D095343D3F
	for <freebsd-gnats-submit@FreeBSD.org>; Mon, 17 May 2004 13:17:53 -0700 (PDT)
	(envelope-from eikemeier@fillmore-labs.com)
Received: from [172.16.0.2] (helo=fillmore-labs.com)
	by fillmore.dyndns.org with esmtp (Exim 4.34; FreeBSD)
	id 1BPoYQ-00048M-Su
	for freebsd-gnats-submit@FreeBSD.org; Mon, 17 May 2004 22:17:53 +0200
Message-Id: <40A91DDB.3080203@fillmore-labs.com>
Date: Mon, 17 May 2004 22:17:31 +0200
From: Oliver Eikemeier <eikemeier@fillmore-labs.com>
To: freebsd-gnats-submit@FreeBSD.org
Subject: Clarification that port names should not contain version numbers

>Number:         66775
>Category:       docs
>Synopsis:       [patch] clarification to committer's guide that port names should not contain version numbers
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    roam
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          change-request
>Submitter-Id:   current-users
>Arrival-Date:   Mon May 17 13:20:17 PDT 2004
>Closed-Date:    Wed Apr 25 13:24:00 GMT 2007
>Last-Modified:  Wed Apr 25 13:24:00 GMT 2007
>Originator:     Oliver Eikemeier
>Release:        FreeBSD 4.10-STABLE i386
>Organization:
Fillmore Labs - http://www.fillmore-labs.com
>Environment:
System: FreeBSD nuuk.fillmore-labs.com 4.10-STABLE

>Description:

Ports documentation should state more clearly that the version number of a
port should not be part of its name.
 
>How-To-Repeat:
>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."
>Release-Note:
>Audit-Trail:

From: Kirill Ponomarew <krion@voodoo.oberon.net>
To: Oliver Eikemeier <eikemeier@fillmore-labs.com>
Cc: freebsd-gnats-submit@FreeBSD.org
Subject: Re: docs/66775: Clarification that port names should not contain version numbers
Date: Mon, 17 May 2004 22:33:08 +0200

 --FLPM4o+7JoHGki3m
 Content-Type: text/plain; charset=us-ascii
 Content-Disposition: inline
 Content-Transfer-Encoding: quoted-printable
 
 Hi,
 
 On Mon, May 17, 2004 at 10:17:31PM +0200, Oliver Eikemeier wrote:
 =20
 > The Committers Guide
 >   <http://www.freebsd.org/doc/en_US.ISO8859-1/articles/committers-guide/p=
 orts.html#Q12.2.3.>
 > has the following sentence:
 >=20
 >   "Upgrade the copied port to the new version (remember to change the POR=
 TNAME=20
 >    so there are not duplicate ports with the same name)."
 >=20
 > Which should probably read
 >=20
 >   "Upgrade the copied port to the new version (remember to change the LAT=
 EST_LINK=20
 >    so there are not duplicate ports with the same name)."
 >=20
 > 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
 
 --FLPM4o+7JoHGki3m
 Content-Type: application/pgp-signature
 Content-Disposition: inline
 
 -----BEGIN PGP SIGNATURE-----
 Version: GnuPG v1.2.4 (FreeBSD)
 
 iD8DBQFAqSGEQC1G6a60JuURAstuAKDgeLlMc7Sk9HERjsmmct2iKMH3dACcCGev
 QLvCSiNe5PGB6HMf5wXnS74=
 =2Ba/
 -----END PGP SIGNATURE-----
 
 --FLPM4o+7JoHGki3m--
Responsible-Changed-From-To: freebsd-doc->linimon 
Responsible-Changed-By: linimon 
Responsible-Changed-When: Mon May 17 14:10:12 PDT 2004 
Responsible-Changed-Why:  
I'm probably the logical choice for this. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=66775 
Responsible-Changed-From-To: linimon->freebsd-doc 
Responsible-Changed-By: linimon 
Responsible-Changed-When: Wed Jun 30 02:22:16 GMT 2004 
Responsible-Changed-Why:  
I don't seem to be getting around to this. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=66775 

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>
 
                    <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>

From: Peter Pentchev <roam@ringlet.net>
To: Aasmund Eikli <inter@o12a.com>
Cc: bug-followup@FreeBSD.org
Subject: Re: docs/66775: Clarification that port names should not contain version numbers
Date: Mon, 9 Aug 2004 15:31:08 +0300

 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.

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"?
 
 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
 > 

From: Oliver Eikemeier <eikemeier@fillmore-labs.com>
To: Aasmund Eikli <inter@o12a.com>
Cc: freebsd-gnats-submit@FreeBSD.org
Subject: Re: docs/66775: Clarification that port names should not contain version numbers
Date: Tue, 10 Aug 2004 16:02:21 +0200

 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
 
Responsible-Changed-From-To: freebsd-doc->roam 
Responsible-Changed-By: trhodes 
Responsible-Changed-When: Fri Aug 20 04:02:14 GMT 2004 
Responsible-Changed-Why:  
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. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=66775 

From: dfilter@FreeBSD.ORG (dfilter service)
To: bug-followup@FreeBSD.org
Cc:  
Subject: Re: docs/66775: commit references a PR
Date: Wed, 25 Apr 2007 13:13:29 +0000 (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"
 
State-Changed-From-To: open->closed 
State-Changed-By: roam 
State-Changed-When: Wed Apr 25 13:23:00 UTC 2007 
State-Changed-Why:  
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! 

http://www.freebsd.org/cgi/query-pr.cgi?pr=66775 
>Unformatted:
