jehops/git_ports_journal

git_ports_journal's Issues

General comments (audience, organization, and content)

• What is your audience? In "Cloning the ports tree", for instance, "We can start by scanning the list of requested ports on the FreeBSD Wiki." suggests a would-be contributor who doesn't already have a specific first port in mind, but is that the most common case? (I definitely had a specific one, but I may not be the typical beginning port maintainer.) See also https://docs.freebsd.org/en/articles/contributing/#ports-contributing.
• What knowledge of git do you expect? For contributors who never used git before, I'd also add choosing a flavor or package to install and general git setup, like setting the contributor name and email address, perhaps in a "Setting up git" section before "Cloning the ports tree".
• The introduction is about git use in general, but doesn't say as much as it should (IMO) about its use with the FreeBSD ports repository. At a minimum, I'd mention the use of branches for quarterly snapshots. Also, the last introduction seems to focus sometimes on overall process and committers and sometimes on port maintainers, but without saying when it address each, which is probably confusing to a beginning port maintainer. I'd also add that FreeBSD used "main" for the shared development branch instead of "master" as many projects do.
• Putting the ports repo in /usr/ports in your examples (starting with "Cloning the ports tree" and I expect throughout the article) directly contradicts what the Porter's Handbook says to do (see eg, https://docs.freebsd.org/en/books/porters-handbook/upgrading/#git-diff) so for consistency and POLA I would avoid that and put it somewhere under the user's homedir instead, eg ~/ports.
• I'd move the one-time setup steps from "First Commit" to "Cloning the ports tree".
• In "Testing", I'd also mention porttools, which I found useful both to create a port skeleton and for a test harness lighter than poudriere, but deadlines or word count requirements may prevent adding this.
• I'd remove the whole "If you want to serve packages to remote hosts" section, which seems off-topic for a port maintainer and is described in https://docs.freebsd.org/en/books/handbook/ports/#ports-poudriere. (On a tangent: that section of the handbook could use instructions for setting up a webserver on the package repository host. Would you object to me - or someone™ - using your text as the basis for that?)
• If word count permits, the paragraph about updating the port would also point to MFH for backporting critical fixes (eg; security) to the latest quarterly branch.

Line edit comments without wording suggestions

• "A typical workflow is to create a new branch (off of the main branch) to develop some new feature or to fix a bug." Specify: typical for which use cases? The uses you list may not be typical for port maintainers, as most of that happens upstream.
• "If you are using ZFS and do not already have a dedicated dataset for the ports tree, create one now." Uh, why? I know poudriere likes ZFS best, but why a separate dataset? That would definitely drag in more ZFS than I would have been comfortable with then on top of the ports and git do learning curves, so I wouldn't recommend it unless there are strong pros, in which case I would at least summarize those.
• /usr/ports for the ports repository: I don't do that (I use something under ~ instead) and would not recommend it for reasons that go beyond personal taste. "If you would like to work on the ports tree as an unprivileged user, you can make the directory writable for your user or group." feels like bad advice to me, and if left at all should include a security disclaimer and a list of pros.
• "zfs compression can be turned off for the zroot/usr/ports/distfiles dataset" Remove (together with the additional dataset creation) if you decided not to ZFS earlier.
• "git -C /usr/ports fetch freebsd" More /usr/ports to remove if you decide to change that.
• Accessibility: I don't see references to emacs_git_log.png or ports_git_log.png in your draft, but if you include one or both later (or if I missed them), make sure to provide a meaningful alternate text description or equivalent in-text narrative.
• "poudriere ports -c -m null -M /usr/ports" /usr/ports again.
• "807099e08e33 www/nyxt: (WIP) Fix QL_DEPENDS" Consistency: use either that or the earlier QL_DEPS unless the difference is deliberate.
• "git rebase -i HEAD~7" Safety: wouldn't "git rebase -i main nyxt" do the same without making you count and risk miscounting? (6! 6 commits! Hahaha!)