[Bug 272795] FreeBSD Handbook section 4.5.1 could be better.

https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=272795

            Bug ID: 272795
           Summary: FreeBSD Handbook section 4.5.1 could be better.
           Product: Documentation
           Version: Latest
          Hardware: Any
                OS: Any
            Status: New
          Severity: Affects Many People
          Priority: ---
         Component: Website
          Assignee: doc@FreeBSD.org
          Reporter: bicknell@ufp.org

I gather portsnap has been deprecated and docs updated recently, however that
has left some confusing bits:

1) Under https://docs.freebsd.org/en/books/handbook/ports/#ports-using, section
4.5.1:

- "use one of the following methods to install it", but then only a single
method (git) follows.

2) There is no instruction on what users who previously used portsnap or svn
should do to convert to the newly supported git method.  If it is as simple as
blow away /usr/ports and check out via git that should be spelled out in a
"migrating" section.

3) Perhaps a doc bug, perhaps a feature request: `pkg` defaults to quarterly
branches, but does not seem to output which quarterly branch it is on.  See
example pkg -d output below.  git seems to need a specific year + quarter (e.g.
2023Q2) tag.  I'm not seeing a simple programatic way to keep the two in sync.

- Maybe the git repo could have a tag "quarterly" like packages do that is
moved forward once a quarter so the checkout can always just be of quarterly?
- Maybe pkg can emit the quarter it is tracking (e.g. new command `pkg
quarter`), ideally in the same format that git needs it (e.g. "git clone
https://git.FreeBSD.org/ports.git -b `pkg quarter` /usr/ports" would work).
- Maybe `pkg update` could have an option in the config file of "keep ports in
sync" where it spawns an update to the ports tree if a quarterly boundary is
crossed?
- Maybe the daily/weekly/monthly periodic could have a new option of "keep
ports and packages in sync" where the periodic script automatically updates the
ports tree to match the pkg quarter.

Use case: I prefer to install from packages, but from time to time I need to
build a single bit of software from ports either because there is no package or
because I need to customize a build time option.  I suspect there are many like
me, and today we have to manage two update methods and hope to keep the trees
in sync.  With the new quarterly thing it should be much easier for software to
just do the right thing and not have humans have to run around and remember
this stuff.



Output below, which quarter is it updating to?  I dunno!
(From FreeBSD 13.2-RELEASE with pkg-1.19.2.)

# pkg -d update
DBG(1)[6448]> pkg initialized
Updating FreeBSD repository catalogue...
DBG(1)[6448]> PkgRepo: verifying update for FreeBSD
DBG(1)[6448]> Pkgrepo, begin update of '/var/db/pkg/repo-FreeBSD.sqlite'
DBG(1)[6448]> Request to fetch
pkg+http://pkg.FreeBSD.org/FreeBSD:13:amd64/quarterly/meta.conf
DBG(1)[6448]> opening libfetch fetcher
DBG(1)[6448]> Fetch > libfetch: connecting
DBG(1)[6448]> Fetch: fetching from:
http://pkgmir.geo.freebsd.org/FreeBSD:13:amd64/quarterly/meta.conf with opts
"i"
DBG(1)[6448]> Request to fetch
pkg+http://pkg.FreeBSD.org/FreeBSD:13:amd64/quarterly/packagesite.pkg
DBG(1)[6448]> opening libfetch fetcher
DBG(1)[6448]> Fetch > libfetch: connecting
DBG(1)[6448]> Fetch: fetching from:
http://pkgmir.geo.freebsd.org/FreeBSD:13:amd64/quarterly/packagesite.pkg with
opts "i"
DBG(1)[6448]> Request to fetch
pkg+http://pkg.FreeBSD.org/FreeBSD:13:amd64/quarterly/packagesite.txz
DBG(1)[6448]> opening libfetch fetcher
DBG(1)[6448]> Fetch > libfetch: connecting
DBG(1)[6448]> Fetch: fetching from:
http://pkgmir.geo.freebsd.org/FreeBSD:13:amd64/quarterly/packagesite.txz with
opts "i"
FreeBSD repository is up to date.
All repositories are up to date.

-- 
You are receiving this mail because:
You are the assignee for the bug.