Porters Handbook section 4.4

[Russell Haley]

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 at 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 at gmail.com> wrote:
>> > On Fri, Sep 29, 2017 at 7:58 AM, Warren Block <wblock at wonkity.com> 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