From owner-freebsd-doc@freebsd.org Mon Oct 9 07:22:16 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 71BB5E27D6F for ; Mon, 9 Oct 2017 07:22:16 +0000 (UTC) (envelope-from russ.haley@gmail.com) Received: from mailman.ysv.freebsd.org (unknown [127.0.1.3]) by mx1.freebsd.org (Postfix) with ESMTP id EA5256E202 for ; Mon, 9 Oct 2017 07:22:15 +0000 (UTC) (envelope-from russ.haley@gmail.com) Received: by mailman.ysv.freebsd.org (Postfix) id D0719E27D6C; Mon, 9 Oct 2017 07:22:15 +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 CFBF1E27D6B; Mon, 9 Oct 2017 07:22:15 +0000 (UTC) (envelope-from russ.haley@gmail.com) Received: from mail-lf0-x230.google.com (mail-lf0-x230.google.com [IPv6:2a00:1450:4010:c07::230]) (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 E5D836E1ED; Mon, 9 Oct 2017 07:22:14 +0000 (UTC) (envelope-from russ.haley@gmail.com) Received: by mail-lf0-x230.google.com with SMTP id p184so25970681lfe.12; Mon, 09 Oct 2017 00:22:14 -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=aa68ur1QhLH2dhaYbbuO0xamTIzIICyUSar62dW/0bQ=; b=Y2a/aojJiNkkckWYasl/cCrvzX4rC29SGyVleIIIoTa3zsGN7r0QB822iy2PmQR4dG u4BYSgTHTbgMKemxfyC9J6sJiGZEvBWnGZGOBSYRFwVwS5MoceRPGKHBkJ8es+78jOsl yeq6SWYr1q5o519gidQQhege3bgW9+CkllBDLHvGz3L4oS8QBL8VDR4qs93kksGqXL0J I5U5YK8G+RbS4rGx4jf4h7CbUrGnrUiy3BxOZUFmvjS6VJaIPKm1jxk8E7h877hgeCp8 uWa9lO/hRn1dMGGYoCZrbZkIc4vq51oFJMXZWqTnO0mrZ+kbv1uYB6wYLdsug2ZADAlO GIpA== 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=aa68ur1QhLH2dhaYbbuO0xamTIzIICyUSar62dW/0bQ=; b=MaPu3BknH9RPSMpZj3+EHVwjE60/x1/RD+PfUlETQSF+xzUaZuG2pAR6vEGak7SNJP fb9y9OM2SdGAfsQ0wQltZVgd110yuoia3vgzITxLPyDtYdgfNYnVXKkd9h4Ewif2uX3e gHxK4wqIqfx2JmrUrAiyvUE7ZnlHKvS+JapX5517Udoak6V+bnStw7OCudj+Svdbbt3j TQgiTLkcb6Lv4qUVMYX2e/FsJw4HicpEdBBBKu6eLYAwofXR+q0MyURd+bGRjdS0R/LL +ui0pjXpHt1IcUhtweaNaTiVKYxJeMO9jTJk6psCR60f8zj38fZy9s1UWs5Riz7Z50qD sIeg== X-Gm-Message-State: AMCzsaXCiMQrFCvaQHXzJRAQ3J6KobgAjz3D0csRSPQlKGyzT5lqkuSQ UedOQMCiwbqzkxiC5TgnevRe+C5aAAhWpd9BNerESg== X-Google-Smtp-Source: AOwi7QBcezMJ+cDR0Hz5bMrZBGnyKYHCy6Lp3YThZPMZV4Xp42fnw+X+AWqEAouWQ3hknPm3XuvrR+q49ctH006zb1o= X-Received: by 10.25.234.66 with SMTP id i63mr3503713lfh.188.1507533732810; Mon, 09 Oct 2017 00:22:12 -0700 (PDT) MIME-Version: 1.0 Received: by 10.46.14.2 with HTTP; Mon, 9 Oct 2017 00:22:11 -0700 (PDT) In-Reply-To: References: <8a3e663a-d94f-0ef7-bbc7-8ebaa111f6dd@FreeBSD.org> <7b2f2464-5c35-e24a-2047-838c1a9e96a3@FreeBSD.org> From: Russell Haley Date: Mon, 9 Oct 2017 00:22:11 -0700 Message-ID: Subject: Re: Porters Handbook section 4.4 To: Warren Block Cc: koobs@freebsd.org, doc@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: Mon, 09 Oct 2017 07:22:16 -0000 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... > > Russ Hi, So I got a good chunk of work done moving koobs=E2=80=99 description into t= he 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 think t= he 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 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 s= hould 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... Thanks, Russ