Date: Wed, 11 Oct 2017 11:23:58 -0700 From: Russell Haley <russ.haley@gmail.com> To: Benjamin Kaduk <bjk@freebsd.org> Cc: Warren Block <wblock@wonkity.com>, doc@freebsd.org, koobs@freebsd.org, freebsd-ports@freebsd.org Subject: Re: Porters Handbook section 4.4 Message-ID: <CABx9NuTw-_VEPDEwc6TKxsNCO2TuJrNKZfdHBf1wWye2_5Rn4w@mail.gmail.com> In-Reply-To: <20171009224825.GM96685@kduck.kaduk.org> References: <CABx9NuSC=tVieJ=dk6%2BFucvfEfNGHCRMuHcy%2BNxo9QW%2BtS8-gA@mail.gmail.com> <8a3e663a-d94f-0ef7-bbc7-8ebaa111f6dd@FreeBSD.org> <CABx9NuS6ie6fVwMh68wpRmRE6MsuGDfKQgLdVVZaeL_HJrKVOg@mail.gmail.com> <7b2f2464-5c35-e24a-2047-838c1a9e96a3@FreeBSD.org> <CABx9NuTUmeSU8yYkiYpR2vGYkhTV_MiHuNJYqZvLwJ9Q97B8Zg@mail.gmail.com> <alpine.BSF.2.21.1709290857480.9561@wonkity.com> <CABx9NuQrAsEXAXXmtZePQwn_x0Q7UywA73eggQW1mtDHmFdxxg@mail.gmail.com> <CABx9NuTqYh9A06vgALA6J3fB-_%2BMc5ZvR9Y4RYF7uh_wU4FSPg@mail.gmail.com> <20171009224825.GM96685@kduck.kaduk.org>
next in thread | previous in thread | raw e-mail | index | archive | help
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 <bjk@freebsd.org> 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 <russ.haley@gmail.com> wro= te: >> > On Fri, Sep 29, 2017 at 7:58 AM, Warren Block <wblock@wonkity.com> 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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?CABx9NuTw-_VEPDEwc6TKxsNCO2TuJrNKZfdHBf1wWye2_5Rn4w>