Migrate from github to cgit.f.o/doc

[debdrup]

Following up on #323, it is now possible to migrate from github to cgit.f.o/doc, but there's a couple of things that need to be addressed before this can happen, if it is to happen.

First, we need to address the elephant in the room, which is that there's no longer any pull requests.

For commiters, means they'll need approval for adding to the status report folder - this can, and should, be a blanket approval for any file which isn't _index.adoc (doceng@ may need to approve this?).
It it helped along by the tooling available, in that textproc/rubygem-asciidoctor can serve as a linter, and reviews.f.o can be used as a staging area for collaborative entries, which itself is helped along by src/tools/tools/git/git-arc.sh and it's manual page which are available simply by doing make build and make install

For contributors, this means suggesting either using reviews.f.o for easy feedback from the status report team, or collaboration with other contributors, or the use of git format-patch to craft patches can be sent via email, as this creates mailbox format patch (which can be applied with git am) that keeps the all the relevant meta-data.

All of the necessary information should be collected in status/howto.adoc which should be accessible from here or somewhere equally centrally located. @sergio-carlavilla should probably be involved, since at present the howto doesn't appear to work.

[debdrup]

It occurs to me that the move to cgit.f.o also involves changing how folders are named, since they will likely need to be named report-$YEAR-$START-$YEAR-$END so that the URI stays consistent with how URIs are presently made from the old .html files generated using the DocBook format.

[pauamma]

If you go with the reviews.f.o option, it would be nice if you added me to whichever group you choose for proofreaders/copy editors, or told me which so I can add myself if that's an option.

[sergio-carlavilla]

Well, when people start sending the reports we can start with this new approach.

[grahamperrin]

… at present the howto doesn't appear to work.

Fixed under recent FreeBSD bug report 267129.

Was there an earlier report?

[pauamma]

Preamble: people, YMMV.

I discovered this issue via #535 (comment).

… the elephant in the room, which is that there's no longer any pull requests. …

This is hugely disappointing. Demotivating.

For some current and potential future FreeBSD people: this might be more an eight-tonne mammoth, than a simple elephant.

If I had been steered towards Phabricator, instead of GitHub, I simply would not have reviewed submissions for recent quarterly status reports.

… reviews.f.o for easy feedback …

I find Phabricator horribly messy, not easy, for anything more than the simplest of changes to documentation.

I don't like Github's one-size-fits-all approach, and I couldn't stay away from Phabricator even if I was inclined to (too many reviews involving manual pages happen on it), but I have to agree: not all minds work the same, and we need people to address pull requests, because some find it easier to review on Github, and also because some find it easier to report on Github (not to mention that we're steering people there with the change-request button on our online documentation). I think that workflow badly needs streamlining, though. I distinctly remember items moving from Github to Bugzilla (for issues/problem reports) and to Phabricator (for pull requests), and that's giving us the worst of both pipelines, not to mention loss of context and the attendant consistency problems, like people taking a Phabricator review in the direction opposite the Github review went in. That's not helpful to anyone, starting with being disrespectful to the original reporter.

[grahamperrin]

Thanks, I'd like to say more, but here's not the place.

The opening "YMMV", to everyone, was intended to show respect for other people's points of view before expressing my own.

The place will probably be the workflow working group, which I'll follow, from a distance …

---

… whilst stepping quietly away from FreeBSD Project avenues that diverge too far away from my own. It was nice whilst it lasted.

[lsalvadore]

I have started a mail thread in the quarterly mailing list and the doceng mailing list. I will forward it to you @grahamperrin to include you in the conversation, and if you are interested in the quarterly status report team's work do not forget to join it officially, mainly by joining the mailing list (I think you need to ask postmaster@ to do at, for example through bugzilla) and the quarterly team on GitHub (that would give you commit privileges I think; of course this is less important if we end up moving everything to doc/).

Here is a short version of what are the motivations I see for the change:

• having the same files in two repositories (here and FreeBSD doc) is difficult to manage as it is better to keep them in sync;
• the Phabricator instance is self-hosted on the FreeBSD infrastructure, while this repository lives on GitHub.

I am open to discussion to improve the workflow differently, but I would really like to have to manage only one repository and I would prefer that it was hosted somewhere on the FreeBSD infrastructure.

A few more thoughts about Phabricator vs GitHub. As you probably all know, the FreeBSD doc repository is mirrored on GitHub and thus, it would still be possible to open pull requests for quarterly reports on https://github.com/freebsd/freebsd-doc/pulls and the files could still be reviewed after merging. The use of the GitHub in this case also has the advantage to provide a rendered version of the adoc files.
I would prefer to have Phabricator as main platform to submit reports because it is self-hosted, but if things work better on GitHub I am fine with pull requests on there too (moreover some submitters might already have a GitHub account and might not want to create a new account on Phabricator). The two repositories issue would still be solved, and this is the main issue.

So @grahamperrin, I do not think this change should refrain you from keeping up the good work you are doing here. You could just change https://github.com/freebsd/freebsd-quarterly into https://github.com/freebsd/freebsd-doc/tree/main/website/content/en/status .

I find Phabricator horribly messy, not easy, for anything more than the simplest of changes to documentation.

Different people have different tastes. Indeed, I find GitHub horribly messy and not easy for anything more thant the simplest of changes. In particular, I dislike the pull request mechanism using forks. And I am still searching the perfect way to merge properly a pull request (the easy green button will do the job, but never asks for which e-mail address I want to use so it uses the wrong one; the suggested command line instructions fix the e-mail address issue but do not act exactly as the green button...).

[grahamperrin]

@lsalvadore thanks, I should have paid proper attention to the dates here.

I reacted badly, stumbling into what seemed to be an end to PRs.

I should have put it on the timeline that includes the broader and more recent docs.freebsd.org encouragement to use pull requests (articles, books …) – around mid-December last year, if I recall correctly. My bad, for not getting the timeline. Sorry.

I have hidden #324 (comment) as outdated.

[bsdimp]

I'd like to also note that we have a lot of organic change in the project. Phab happened because we had nothing. github repos happened because I (and others) wanted to see how well or poorly that worked. We're discovering that the actual on the ground feelings are quite different than what some partisans said early in the debates, and learning that nuance is important.

And the reason to learn is so people like @lsalvadore can improve our work flow. One of the things the project has done well is resist the dogma of the day. This has lead us to some cool innovations, as well as several old, crunchy things that we do only from inertia. I'd love to see his work to make the doc work flow better from someone that's been doing it a lot through the different channels we have and understands the difficulties with the different aspects of things and experiments that have been run. I wish that there was such efforts for src, but we don't have someone leading that charge since I got burned out on it when I was in an especially difficult core team.

[grahamperrin]

Thanks Warner, thanks all. I'm still resisting the temptation to respond in detail. Apologies for the partial hijack.

Pau Amma: I can't agree entirely, because generally (not specific to FreeBSD or any other project), I don't recall ever feeling disrespected when a report from me that originated in one place shifted to some other place. I mean, if ever I had that feeling, it wasn't strong enough to be memorable for long.

A happy paradox: the punishment of a commit bit – with its requirement to use things such as git(1) – has caused me to learn more about GitHub than the command line. Some of this learning was through trial and error, which rarely bothers me.

Lorenzo: I think I know part of what you mean in your last sentence.

---

Towards reducing the noise that I began: whilst I'm not a fan of GitHub Discussions as a medium, https://github.com/orgs/community/discussions/ does seem like a good enough place to share experience, for anyone else who's interested. There's a pull requests category, and so on.

[pauamma]

I meant specifically the possibility that reviewers in Phabricator would take the review in a direction inconsistent with what it was on Github and the original submitter's intent. That is what I (would) find disrespectful, not just moving it.

[grahamperrin]

… the possibility that reviewers in Phabricator would take the review in a direction inconsistent with what it was on Github and the original submitter's intent. …

That's attributable more to people (including the original author) than to platforms.

A sense of disrespect should be less likely if the author can be prepared for the gamut of edits that might occur. If an intent is reasonably clear from the outset: the intent shouldn't become lost, or obscure, through the process of public review.

An edit that follows all or part of the style guide might seem ruthless, if the reader is not fully aware of the guide.

One problem with this guide (or with lack of awareness of the guide) is that it falls towards the end of a seventy-four-page book that's a primer; some people expect a primer to be less than one tenth of that length; the guide begins with conciseness as one of three goals; and I could easily reduce the forty-two-word paragraph about those goals to a single sentence of five words ;-) the sum of which is, on the other hand, more than one problem …

[pauamma]

That's attributable more to people (including the original author) than to platforms.

More than to specific platforms, true. More than to the presence of 2 different platforms in the workflow, not sure.

[lsalvadore]

I think pull request #584 is the last thing that needs to be done before archiving the repository. Am I forgetting anything?

[lsalvadore]

I have merged pull request #584. I am going to wait a few more days to see if anyone finds anything that still needs to be done on this repository, then request to archive it.

[lsalvadore]

Request sent: https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=269696 .