Porters Handbook section 4.4

[Benjamin Kaduk]

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