From owner-freebsd-doc@freebsd.org Wed Oct 11 18:24:02 2017 Return-Path: Delivered-To: freebsd-doc@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 D139EE331C5 for ; Wed, 11 Oct 2017 18:24:02 +0000 (UTC) (envelope-from russ.haley@gmail.com) Received: from mailman.ysv.freebsd.org (mailman.ysv.freebsd.org [IPv6:2001:1900:2254:206a::50:5]) by mx1.freebsd.org (Postfix) with ESMTP id A72537184C for ; Wed, 11 Oct 2017 18:24:02 +0000 (UTC) (envelope-from russ.haley@gmail.com) Received: by mailman.ysv.freebsd.org (Postfix) id A374EE331C3; Wed, 11 Oct 2017 18:24:02 +0000 (UTC) Delivered-To: doc@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 A2D76E331C2; Wed, 11 Oct 2017 18:24:02 +0000 (UTC) (envelope-from russ.haley@gmail.com) Received: from mail-lf0-x236.google.com (mail-lf0-x236.google.com [IPv6:2a00:1450:4010:c07::236]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (Client CN "smtp.gmail.com", Issuer "Google Internet Authority G2" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 0DB4271849; Wed, 11 Oct 2017 18:24:02 +0000 (UTC) (envelope-from russ.haley@gmail.com) Received: by mail-lf0-x236.google.com with SMTP id g70so3058548lfl.3; Wed, 11 Oct 2017 11:24:01 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=mime-version:in-reply-to:references:from:date:message-id:subject:to :cc; bh=w7+iFepqIXtCOI0Mh+ZbFvTVPu2euoraZshU6RgIUd8=; b=UVR8LugddFjvsfX1Mw7wMyD93XCw1eVGKp+8aP5XeSgD+G/QnhtV+PmkD+bd6ZgXau 7sZrWhls65zkqniVVO5kVZf73WlSsclb7sH5775pBqTjQfQY1cbSm8Skl+j0QuMJHJ43 4EtRZU2If/uN8dIuT0O5gTRVrlL52HEewIFX3Y+hNjb/P0eAeUq9jkM44hZr+ChUSjmN 631R+bGyPbENYKBM2AZOZl2gTrOe93EiP7HWIMNZNPrV0PBACsCozUAta8AL1j0sUKYU sslehEfX9l0GyojJSKZ3JzWjGjsUcr7/neuJ+p3THnmx0cGg6mRvJC90N2Iipanmh77u 0QsA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:in-reply-to:references:from:date :message-id:subject:to:cc; bh=w7+iFepqIXtCOI0Mh+ZbFvTVPu2euoraZshU6RgIUd8=; b=mheEBQOJ/Wg7pDXB50R3GOH0BU8/94ip0FM1dgaIFrNBBRh38x+3M8Z237gccJQSVU nKwLyxw2fVhPqbu8CxPg6N/W0M8tFJXM/IhSY1Fmzs3UDsss7VwNwcus9WW4l7fy+nDe XCRJsZ/1pAGbHvSrO/qbvG85bkfT6dCyK+Dmo80cz6Cy6YJ1zzcQRpABCVDJppUqKuNT eKb05bArKI8yA22gPij5MCRFP/5Fbg58DnFDk87Tole8+aWz6w3Puq8A94wJztsLxqG6 OcP4DSYhRnJ2s/LJkZFlzq7TpwESwJNURF+KpByILIIVb1gznrIa+P6DMdjnYcS3b/6n xO9w== X-Gm-Message-State: AMCzsaVAv7fq4s6jq7oZC9fYnzsJt0qt28MDWb9YDOTDnuL+Jt6E5eJ6 lUcJ92fy/5EIkd/iy3QUapJhWvcHJWO4RhYugh4= X-Google-Smtp-Source: ABhQp+Rt+LrCDrW4IwwlHIAxF81C9aAfux5rWapyayGjxFUjG4xzwiSAAr9DU1DZlhrHvDOQHPo9AfQpnhnBVuesdGI= X-Received: by 10.25.19.196 with SMTP id 65mr139247lft.221.1507746239903; Wed, 11 Oct 2017 11:23:59 -0700 (PDT) MIME-Version: 1.0 Received: by 10.46.14.2 with HTTP; Wed, 11 Oct 2017 11:23:58 -0700 (PDT) In-Reply-To: <20171009224825.GM96685@kduck.kaduk.org> References: <8a3e663a-d94f-0ef7-bbc7-8ebaa111f6dd@FreeBSD.org> <7b2f2464-5c35-e24a-2047-838c1a9e96a3@FreeBSD.org> <20171009224825.GM96685@kduck.kaduk.org> From: Russell Haley Date: Wed, 11 Oct 2017 11:23:58 -0700 Message-ID: Subject: Re: Porters Handbook section 4.4 To: Benjamin Kaduk Cc: Warren Block , doc@freebsd.org, koobs@freebsd.org, freebsd-ports@freebsd.org Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable X-Content-Filtered-By: Mailman/MimeDel 2.1.23 X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 11 Oct 2017 18:24:02 -0000 Here is chapter 1 in an odt since it's a new work and I wanted to bang it out without formatting. I'll add it to the sources after I get a good start on Chapter 2 and post a patch. I assume phabricator the preferred tool for commenting on documents? Russ On Mon, Oct 9, 2017 at 3:48 PM, Benjamin Kaduk wrote: > On Mon, Oct 09, 2017 at 12:22:11AM -0700, Russell Haley wrote: >> On Mon, Oct 2, 2017 at 9:21 AM, Russell Haley wro= te: >> > On Fri, Sep 29, 2017 at 7:58 AM, Warren Block wro= te: >> >> 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=E2=80=99 description int= o the >> correct format and then started looking at how everything hangs >> together. I don=E2=80=99t want to offend anyone on this list, but I thin= k 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 >> =E2=80=98section=E2=80=99 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=E2=80=99s 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