git: cdc7bf43fe - main - porters-handbook: document move of WWW from pkg-descr to Makefile
- Go to: [ bottom of page ] [ top of archives ] [ this month ]
Date: Wed, 07 Sep 2022 19:42:00 UTC
The branch main has been updated by se (ports, src committer):
URL: https://cgit.FreeBSD.org/doc/commit/?id=cdc7bf43fe7d33f904b6d78eef466bc25e59cb7c
commit cdc7bf43fe7d33f904b6d78eef466bc25e59cb7c
Author: Stefan Eßer <se@FreeBSD.org>
AuthorDate: 2022-09-07 06:52:08 +0000
Commit: Stefan Eßer <se@FreeBSD.org>
CommitDate: 2022-09-07 19:20:42 +0000
porters-handbook: document move of WWW from pkg-descr to Makefile
Review D36434 will add support for a WWW macro in the ports' Makefiles
instead of at the end of the pkg-descr files to the ports framework.
This will make the WWW entries accessible to more tools (e.g. portgrep)
and will make it easier to maintain them (e.g. to find stale URLs).
Adding WWW: lines at the end of pkg-descr files is deprecated and will
be warned about by a forthcoming commit to portlint.
Follow-up commits will update all ports to conform with this new
style.
Approved by: rene, carlavilla (earlier version)
Differential Revision: https://reviews.freebsd.org/D36369
---
.../books/porters-handbook/makefiles/_index.adoc | 29 ++++++++++++++++++++++
.../en/books/porters-handbook/plist/_index.adoc | 1 +
.../porters-handbook/porting-samplem/_index.adoc | 1 +
.../porters-handbook/quick-porting/_index.adoc | 19 ++------------
.../en/books/porters-handbook/special/_index.adoc | 12 +++++++++
5 files changed, 45 insertions(+), 17 deletions(-)
diff --git a/documentation/content/en/books/porters-handbook/makefiles/_index.adoc b/documentation/content/en/books/porters-handbook/makefiles/_index.adoc
index 10a76f01da..005eb99dfb 100644
--- a/documentation/content/en/books/porters-handbook/makefiles/_index.adoc
+++ b/documentation/content/en/books/porters-handbook/makefiles/_index.adoc
@@ -1145,6 +1145,7 @@ DISTNAME= ${PORTNAME}-${ISCVERSION}
MAINTAINER= mat@FreeBSD.org
COMMENT= BIND DNS suite with updated DNSSEC and DNS64
+WWW= https://www.isc.org/bind/
LICENSE= ISCL
@@ -2515,6 +2516,34 @@ COMMENT= Cat chasing a mouse all over the screen
The COMMENT variable immediately follows the MAINTAINER variable in the [.filename]#Makefile#.
+[[makefile-www]]
+== Project website
+
+Each port should point to a website that provides more information about the software.
+
+Whenever possible, this should be the official project website maintained by the developers of the software.
+
+[.programlisting]
+....
+WWW= https://ffmpeg.org/
+....
+
+But it can also be a directory or resource in the source code repository:
+
+[.programlisting]
+....
+WWW= https://sourceforge.net/projects/mpd/
+....
+
+The WWW variable immediately follows the COMMENT variable in the [.filename]#Makefile#.
+
+If the same content can be accessed via HTTP and HTTPS, the URL starting with `https://` shall be used.
+If the URI is the root of the website or directory, it must be terminated with a slash.
+
+This information used to be placed into the last line of the [.filename]#pkg-descr# file.
+It has been moved into the Makefile for easier maintenance and processing.
+Having a `WWW:` line at the end of the [.filename]#pkg-descr# file is deprecated.
+
[[licenses]]
== Licenses
diff --git a/documentation/content/en/books/porters-handbook/plist/_index.adoc b/documentation/content/en/books/porters-handbook/plist/_index.adoc
index aa027f16c7..08f90bea8c 100644
--- a/documentation/content/en/books/porters-handbook/plist/_index.adoc
+++ b/documentation/content/en/books/porters-handbook/plist/_index.adoc
@@ -248,6 +248,7 @@ PKGNAMEPREFIX= p5-
MAINTAINER= perl@FreeBSD.org
COMMENT= Building machine
+WWW= https://search.cpan.org/dist/Machine-Build
USES= perl5
USE_PERL5= configure
diff --git a/documentation/content/en/books/porters-handbook/porting-samplem/_index.adoc b/documentation/content/en/books/porters-handbook/porting-samplem/_index.adoc
index 2a247922c2..8a67e9be99 100644
--- a/documentation/content/en/books/porters-handbook/porting-samplem/_index.adoc
+++ b/documentation/content/en/books/porters-handbook/porting-samplem/_index.adoc
@@ -88,6 +88,7 @@ PATCH_DIST_STRIP= -p1
"ports@FreeBSD.org".]
MAINTAINER= asami@FreeBSD.org
COMMENT= DVI Previewer for the X Window System
+WWW= http://xdvi.sourceforge.net/
[license -- should not be empty]
LICENSE= BSD2CLAUSE
diff --git a/documentation/content/en/books/porters-handbook/quick-porting/_index.adoc b/documentation/content/en/books/porters-handbook/quick-porting/_index.adoc
index 18cd48110c..b296b2bdcd 100644
--- a/documentation/content/en/books/porters-handbook/quick-porting/_index.adoc
+++ b/documentation/content/en/books/porters-handbook/quick-porting/_index.adoc
@@ -85,6 +85,7 @@ MASTER_SITES= ftp://ftp.cs.columbia.edu/archives/X11R5/contrib/
MAINTAINER= youremail@example.com
COMMENT= Cat chasing a mouse all over the screen
+WWW= http://www.daidouji.com/oneko/
.include <bsd.port.mk>
....
@@ -118,27 +119,11 @@ On the other hand, the content of [.filename]#pkg-descr# must be longer than the
A well-written [.filename]#pkg-descr# describes the port completely enough that users would not have to consult the documentation or visit the website to understand what the software does, how it can be useful, or what particularly nice features it has.
Mentioning certain requirements like a graphical toolkit, heavy dependencies, runtime environment, or implementation languages help users decide whether this port will work for them.
-Include a URL to the official WWW homepage.
-Prepend _one_ of the websites (pick the most common one) with `WWW:` (followed by single space) so that automated tools will work correctly.
-If the URI is the root of the website or directory, it must be terminated with a slash.
-
[NOTE]
====
-If the listed webpage for a port is not available, try to search the Internet first to see if the official site moved, was renamed, or is hosted elsewhere.
+The URL that used to be included as the last line of the [.filename]#pkg-descr# file has been moved to the [.filename]#Makefile#.
====
-This example shows how [.filename]#pkg-descr# looks:
-
-[.programlisting]
-....
-This is a port of oneko, in which a cat chases a poor mouse all over
-the screen.
- :
-(etc.)
-
-WWW: http://www.oneko.org/
-....
-
[[porting-pkg-plist]]
=== [.filename]#pkg-plist#
diff --git a/documentation/content/en/books/porters-handbook/special/_index.adoc b/documentation/content/en/books/porters-handbook/special/_index.adoc
index 369632c78b..3a76c90467 100644
--- a/documentation/content/en/books/porters-handbook/special/_index.adoc
+++ b/documentation/content/en/books/porters-handbook/special/_index.adoc
@@ -607,6 +607,7 @@ CATEGORIES= devel
MAINTAINER= tobik@FreeBSD.org
COMMENT= Display statistics about your code
+WWW= https://github.com/XAMPPRocky/tokei/
USES= cargo
USE_GITHUB= yes
@@ -651,6 +652,7 @@ CATEGORIES= devel
MAINTAINER= tobik@FreeBSD.org
COMMENT= Display statistics about your code
+WWW= https://github.com/XAMPPRocky/tokei/
USES= cargo
USE_GITHUB= yes
@@ -821,6 +823,7 @@ CATEGORIES= benchmarks
MAINTAINER= dmgk@FreeBSD.org
COMMENT= Tiny program that sends some load to a web application
+WWW= https://github.com/rakyll/hey/
LICENSE= APACHE20
LICENSE_FILE= ${WRKSRC}/LICENSE
@@ -847,6 +850,7 @@ CATEGORIES= devel
MAINTAINER= tobik@FreeBSD.org
COMMENT= Remote repository management made easy
+WWW= https://github.com/x-motemen/ghq/
USES= go:modules
USE_GITHUB= yes
@@ -896,6 +900,7 @@ CATEGORIES= devel
MAINTAINER= tobik@FreeBSD.org
COMMENT= Remote repository management made easy
+WWW= https://github.com/x-motemen/ghq/
USES= go:modules
USE_GITHUB= yes
@@ -976,6 +981,7 @@ CATEGORIES= devel
MAINTAINER= haskell@FreeBSD.org
COMMENT= Shell script analysis tool
+WWW= https://www.shellcheck.net/
USES= cabal
@@ -1597,6 +1603,7 @@ MASTER_SITES= GNOME
MAINTAINER= kwm@FreeBSD.org
COMMENT= Interactive tool for performing search and replace operations
+WWW= http://regexxer.sourceforge.net/
USES= gettext gmake localbase:ldflags pathfix pkgconfig tar:xz
GNU_CONFIGURE= yes
@@ -3399,6 +3406,7 @@ CATEGORIES= devel www pear
MAINTAINER= example@domain.com
COMMENT= PEAR Date and Time Zone Classes
+WWW= https://pear.php.net/package/Date/
USES= pear
@@ -3446,6 +3454,7 @@ CATEGORIES= devel www pear
MAINTAINER= horde@FreeBSD.org
COMMENT= Horde Core Framework libraries
+WWW= https://pear.horde.org/
OPTIONS_DEFINE= KOLAB SOCKETS
KOLAB_DESC= Enable Kolab server support
@@ -3570,6 +3579,7 @@ CATEGORIES= devel
MAINTAINER= john@doe.tld
COMMENT= Python sample module
+WWW= https://pypi.org/project/sample/
RUN_DEPENDS= ${PYTHON_PKGNAMEPREFIX}six>0:devel/py-six@${PY_FLAVOR}
@@ -4228,6 +4238,7 @@ CATEGORIES= whatever
MAINTAINER= john@doe.tld
COMMENT= Sample
+WWW= https://github.com/lua_sample/sample/
RUN_DEPENDS= ${LUA_REFMODLIBDIR}/lpeg.so:devel/lua-lpeg@${LUA_FLAVOR}
@@ -4251,6 +4262,7 @@ PKGNAMEPREFIX= ${LUA_PKGNAMEPREFIX}
MAINTAINER= john@doe.tld
COMMENT= Sample
+WWW= https://github.com/lua_sample/sample/
USES= lua:module