Bug 255424 - ports.7: Document makesum
Summary: ports.7: Document makesum
Status: In Progress
Alias: None
Product: Documentation
Classification: Unclassified
Component: Manual Pages (show other bugs)
Version: Latest
Hardware: Any Any
: --- Affects Only Me
Assignee: Fernando Apesteguía
URL:
Keywords:
Depends on:
Blocks:
 
Reported: 2021-04-26 15:06 UTC by Mateusz Piotrowski
Modified: 2021-05-06 14:58 UTC (History)
3 users (show)

See Also:


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description Mateusz Piotrowski freebsd_committer 2021-04-26 15:06:57 UTC
Perhaps it is a good idea to document "make makesum" in the manual page.
Comment 1 Fernando Apesteguía freebsd_committer 2021-04-29 09:37:50 UTC
makeplist is not documented either. I think we could rename this PR to review and add all missing targets.

Sounds good?
Comment 2 Yuri Pankov freebsd_committer 2021-04-29 09:45:36 UTC
I would expect ports(7) to be more for end users, and not port maintainers, i.e. you don't usually use makesum or makeplist targets while installing/updating ports.
Comment 3 Mateusz Piotrowski freebsd_committer 2021-04-29 09:52:25 UTC
(In reply to Yuri Pankov from comment #2)
I agree. Maybe we can review ports(7) and move all the port maintainer-related bits to the handbooks. When it comes to makesum and makeplist though, I'd actually keep add them to ports(7) anyway. Users often modify ports a bit when they try things out, on more often than never they edit distinfo manually.
Comment 4 Yuri Pankov freebsd_committer 2021-04-29 10:17:53 UTC
Currently I don't see any developer target in there, only a mention of developer documentation at the bottom; everything in there is targetting end users (listing dependencies, installing/removing ports).

Wonder if we could instead add a link at the top, "For developer's targets, variables, or general documentation in case you want to *modify* port, please see <porters-handbook-link>".  'makesum' target is dependent on other things that are better be known even if you just try things out :)
Comment 5 Fernando Apesteguía freebsd_committer 2021-05-06 14:58:39 UTC
Maybe the only case for makesum is when upstream is known for silently re-rolling distribution files without bumping the version. End users might want to just "make makesum" and continue with their lives :-)

Adding a pointer to the PHB looks like a good option here. Otherwise it would be more consistent to add something like "The following targets are meant for port developers:"

* makeplist
* makesum
* stage-qa
...
...