From owner-freebsd-ports@freebsd.org Mon Oct 9 22:53:41 2017 Return-Path: Delivered-To: freebsd-ports@mailman.ysv.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) by mailman.ysv.freebsd.org (Postfix) with ESMTP id A1B78E3E539; Mon, 9 Oct 2017 22:53:41 +0000 (UTC) (envelope-from kaduk@mit.edu) Received: from dmz-mailsec-scanner-6.mit.edu (dmz-mailsec-scanner-6.mit.edu [18.7.68.35]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id 2F0C983D90; Mon, 9 Oct 2017 22:53:40 +0000 (UTC) (envelope-from kaduk@mit.edu) X-AuditID: 12074423-497ff70000003974-16-59dbfcbf16ed Received: from mailhub-auth-4.mit.edu ( [18.7.62.39]) (using TLS with cipher DHE-RSA-AES256-SHA (256/256 bits)) (Client did not present a certificate) by dmz-mailsec-scanner-6.mit.edu (Symantec Messaging Gateway) with SMTP id F0.5C.14708.FBCFBD95; Mon, 9 Oct 2017 18:48:32 -0400 (EDT) Received: from outgoing.mit.edu (OUTGOING-AUTH-1.MIT.EDU [18.9.28.11]) by mailhub-auth-4.mit.edu (8.13.8/8.9.2) with ESMTP id v99MmU6g030457; Mon, 9 Oct 2017 18:48:31 -0400 Received: from kduck.kaduk.org (24-107-191-124.dhcp.stls.mo.charter.com [24.107.191.124]) (authenticated bits=56) (User authenticated as kaduk@ATHENA.MIT.EDU) by outgoing.mit.edu (8.13.8/8.12.4) with ESMTP id v99MmPdG032045 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NOT); Mon, 9 Oct 2017 18:48:28 -0400 Date: Mon, 9 Oct 2017 17:48:25 -0500 From: Benjamin Kaduk To: Russell Haley Cc: Warren Block , doc@freebsd.org, koobs@freebsd.org, freebsd-ports@freebsd.org Subject: Re: Porters Handbook section 4.4 Message-ID: <20171009224825.GM96685@kduck.kaduk.org> References: <8a3e663a-d94f-0ef7-bbc7-8ebaa111f6dd@FreeBSD.org> <7b2f2464-5c35-e24a-2047-838c1a9e96a3@FreeBSD.org> MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Disposition: inline Content-Transfer-Encoding: 8bit In-Reply-To: User-Agent: Mutt/1.8.3 (2017-05-23) X-Brightmail-Tracker: H4sIAAAAAAAAA+NgFprKKsWRmVeSWpSXmKPExsUixG6nrnvgz+1IgylTmCymftzJarHp8FtG i64fj5ksrk34zWbx65SHA6vHjE/zWTx2zrrL7nGk4xFjAHMUl01Kak5mWWqRvl0CV8bWpQeZ C2YrVNyfHdTAuF+yi5GTQ0LARGLZon2MILaQwGImiR9rYrsYuYDsDYwS69adYoVwrjBJTGvY xQxSxSKgInGz/TUTiM0moCbxeG8zK4gtIqAhsWTzFzYQm1kgV2Lj6y1gNcICmhL32vawgNi8 QNum34QZ2ski8erdLVaIhKDEyZlPWCCa1SX+zLsEtIwDyJaWWP6PAyIsL9G8dTbYDZwCgRLX Z/wDKxcVUJaYt28V2wRGwVlIJs1CMmkWwqRZSCYtYGRZxSibklulm5uYmVOcmqxbnJyYl5da pGuml5tZopeaUrqJERz6Lso7GF/2eR9iFOBgVOLhXTD5dqQQa2JZcWXuIUZJDiYlUd6E30Ah vqT8lMqMxOKM+KLSnNTiQ4wSHMxKIrzO94FyvCmJlVWpRfkwKWkOFiVx3m1BuyKFBNITS1Kz U1MLUotgsjIcHEoSvMUgQwWLUtNTK9Iyc0oQ0kwcnCDDeYCG9/0CGV5ckJhbnJkOkT/FqCgl znsRpFkAJJFRmgfXC0pNEtn7a14xigO9Isx7CaSKB5jW4LpfAQ1mAhrMWHwDZHBJIkJKqoFR +ZxGySfh+c+dL999LV69vmfJzuLC7E35k7+VNb255Gh34kdImrj9takbrHZU/5TZGfjLmFUj UNpFJpC5Qn/u1llnFOyjGf6cr1B4ccM4v2n3XrNSi9dXFkkwn3+TzjxBKuzyiqrF/xgnRKT6 MN18umPR8XW1jp+PP8xsKo784Sy9Zs4toVQeJZbijERDLeai4kQAi3f3HCgDAAA= X-BeenThere: freebsd-ports@freebsd.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: Porting software to FreeBSD List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 09 Oct 2017 22:53:41 -0000 On Mon, Oct 09, 2017 at 12:22:11AM -0700, Russell Haley wrote: > On Mon, Oct 2, 2017 at 9:21 AM, Russell Haley wrote: > > On Fri, Sep 29, 2017 at 7:58 AM, Warren Block wrote: > >> On Mon, 25 Sep 2017, Russell Haley wrote: > >> > >>> Thanks! I'll play with this on the weekend. > >> > >> > >> Please create a review at https://reviews.freebsd.org/ and add me as a > >> reviewer. > >> > >> Thanks! > > > > Will do. Just a progress update: I got the handbook sources and found > > the section in chapter.xml. I created a Geany project with everyone's > > raw notes and the sources. To be continued... IIRC Warren had volunteered to help get that text committed, but if not, feel free to add me to the phabricator review when it's ready. > > Hi, > > So I got a good chunk of work done moving koobs’ description into the > correct format and then started looking at how everything hangs > together. I don’t want to offend anyone on this list, but I think the > organisation and some of the English in the first 4 chapters needs > work. I know how hard it is to create content from nothing (and how > easy it is to be critical), so my hat is off to the original content Given how deep a tangle of patchwork and incremental change on top of incremental change it is, it's unsurprising that the overall organization of things does not make the best of sense. > creators. However, what I would like to propose is this: > > 1) Re-write the introduction to describe what the ports system is and > point to the correct references in the handbook for running ports. I > would also include reference to how to use subversion (handbook) and > the correct repository names. I would also point users to websvn. I > would indicate that the pkg system works off of the ports and include > some other helpful links such as freshports, github and the build > system. I would include a paragraph about how bugillza can be searched > for issues for ports and also describe how phabricator is used to > submit new patches to the ports system. Finally, it should be > emphasised that anyone can create a new port for their software and > submit it to the system. > > 2) The second chapter should be a description of how the ports system > works. This description can be found in the how things work section of > chapter 4. Include further description of the make files and where > they can be found. A note should be made that while the makefiles are > source code, they are well documented at the top and can be referenced > when needed for more information. Chapter 2 should describe how > additional targets can be created (content also from chapter 4). > > 3) Chapter 3 should remain and should be renamed Port Files Overview > (or something to that effect). The first page should outline the files > and involved. Most of them are quite simple and dedicating an entire > ‘section’ to each step is cumbersome. Section 3.1 and 3.2 should be > combined and beefed up (not sure the name yet). Section 3.3. and 3.4 > should be combined and called Validation and Verification (or > something to that effect). A description of what portlint does should > be added. The new "V&V" section should describe why testing is > important and what things to pay attention to, as well as reference > the do’s and don't s section. > > 4) Chapter 4 should be called adding or updating ports. It should > briefly describe what should be done to create a new port and then > describe the processes as outlined by koobs'. The manual porting > instructions should be removed. > > If there is any interest in me doing this, please speak up now as I > might be able to take a day off this week and bash it out in one > sitting. Okay, it's late... This sounds like a pretty good strategy, especially the part where we actually introduce the subject matter! I don't want to tell you to take a day off, but would be happy to see something like this appear eventually. Thanks for putting these thoughts together, Ben