gh-94635: Frame sqlite3 how-to headings as such & move default adapters to Reference

[CAM-Gerlach]

As discussed in #94635 and heavily inspired by #94677 , rename the sqlite3 library documentation's "How-to" section headings in the form of "How-to ..." per Diataxis, and also move the Default Adapters and Converters section to the Reference, where it better belongs (as it simply describe the module's contents/behavior rather than stating how to do anything).

I wasn't sure what to do about "Adapter and Converter Recipes", so I've left it along for now. Any ideas?

• Issue: Restructure the sqlite3 docs table-of-contents #94635

[erlend-aasland]

LGTM, with some nits. I suggest to leave the adapter paragraphs as they are for this PR; we can discuss how to handle them after landing this.

(I took the liberty to sync with main; hope you don't mind.)

[CAM-Gerlach]

(I took the liberty to sync with main; hope you don't mind.)

Per project/org-wide policy in the Spyder org and other projects I'm involved with (and personally as well), we strongly prefer rebases to merges to update the base branch. However, a big part of that is the fact that those projects historically always used merges rather than squashes for pull requests, though in recognition of the inevitably of many contributors having poor commit hygiene and the cost-benefit of dealing with it otherwise, we've begun to use more squash-merging in those cases instead (thanks largely due to my own advocacy and experiences with squashing on Python-org projects, despite being one of the biggest advocates for proper commit hygiene and pre-merge rebase cleanup on PRs). Merges instead of rebases for updating the base branch can create huge problems for authors, reviewers and committers in that workflow, which are much less of a concern when squashing.

Still, it makes navigating commit diffs, blame and history locally on the command line, even with --graph, much less straightforward than otherwise (as well as being more noisy for reviewers, though that's less so lately at least with Refined GitHub filtering them out). Is there a strategy, e.g. some options to git log, to deal with this?

Also, when I do have to merge for some reason, I always make sure to give the merge commit an actually useful commit message rather than a rather unhelpful statement simply that there was a merge, without any meaningful information about why it was done or what it updated.

[erlend-aasland]

For CPython, git merge --no-ff main is strongly preferred to rebase, mainly since the GitHub UI does not play well with rebases.

[erlend-aasland]

Is there a strategy, e.g. some options to git log, to deal with this?

Yes, there is. I'll find it when I'm back at my computer.

[CAM-Gerlach]

For CPython, git merge --no-ff main is strongly preferred to rebase

Why --no-ff? If a clean fast forward merge is possible, it would seem optimal to just do that, to minimize the noise that pure non-interacting update merges cause in the history locally and on GitHub, as well as the need to write a decent commit message (or accept the rather unmeaningful and noisy default).

mainly since the GitHub UI does not play well with rebases.

I'm not totally sure what's being referred to here beyond the natural consequences of rebases (e.g. not seeing outdated check runs), at least as a Refined GitHub user. Might you be able to be more specific (out of curiosity), if it isn't too much trouble?

Yes, there is. I'll find it when I'm back at my computer.

It would also be nice to know any tricks for making rebase -i not an absolute nightmare once a merge is performed, though that's somewhat orthagonal to the CPython repo workflow and perhaps is best discussed out of band.

[erlend-aasland]

Why --no-ff?

Because it creates a merge commit, which is automatically hidden in the GitHub UI is the only thing that'll remain visible in the GitHub UI -- the commits to main inbetween the branching and the merging are automatically hidden by the GitHub UI; this means that all you'll see in the PR history is the "sync-with-main-merge-commit". If you'd fast-forwarded, you'd mess up the git history in the PR ;)

[CAM-Gerlach]

Because it creates a merge commit, which is automatically hidden in the GitHub UI;

Not for me, even with Refined GitHub (and certainly not without it before)—is there some setting I'm missing?

If you'd fast-forwarded, you'd mess up the git history in the PR ;)

Oh how so? I'm not sure what this looks like, exactly.

[erlend-aasland]

I'm not totally sure what's being referred to here beyond the natural consequences of rebases (e.g. not seeing outdated check runs), at least as a Refined GitHub user. Might you be able to be more specific (out of curiosity), if it isn't too much trouble?

Sure; with rebases, you'll lose older commits, which imply losing track of earlier workflow runs, and also losing track of earlier review comments and discussions, both very frustrating inconveniences specifically when it comes to reviewing code changes. This is why a lot of core devs will frown upon and nitpick about rebases.

There is one exception though: if one opens a draft PR, it is ok to rebase the PR until it is marked as ready for review. Once that is done, one should treat the PR as being under review, so further syncs with main should be done using git merge --no-ff.

[erlend-aasland]

Is there a strategy, e.g. some options to git log, to deal with this?

Yes, there is. I'll find it when I'm back at my computer.

# List commits like the GitHub UI does
$ git log --oneline --first-parent
# Only list merge commits (syncs with main); note that this is not possible if you rebase
$ git log --oneline --merges

To list the commits in this PR like the GitHub UI does, do:

$ git log --oneline --first-parent 8dc623169e4db60e5e92d816e9a16290ff5306bb~..HEAD
6aa271cc5c (HEAD -> sqlite3-doc-cleanup-final-headings) Merge branch 'main' into sqlite3-doc-cleanup-final-headings
5eb1abca3e Reframe How-To section headers in terms of how-to per Diataxis
8dc623169e sqlite3 doc: Move default adapters and converters to Reference section

Because it creates a merge commit, which is automatically hidden in the GitHub UI;

Not for me, even with Refined GitHub (and certainly not without it before)—is there some setting I'm missing?

Ah, I was a little bit unclear; it is not the merge commit that is hidden, it is the commits to main since you opened your branch till the merge that are hidden. The merge commit itself is the only thing that is shown in the GitHub UI. Let me try to be more clear and use this PR as an example.

• This PR was created three days ago, containing a two commits: 8dc6231, and 5eb1abc
• Yesterday, I merged gh-96121: Merge sqlite3.Row examples #96122, which created commit 18b1782 in main; that commit created a conflict, which, for this PR, needed to be resolved. The conflict was resolved with merge commit 6aa271c.

The effect of this is that this PR now consists of three commits, two "regular" commits, and a merge commit. You can confirm this visually by clicking the commits tab in the UI for this PR. The merge commit makes sure I can still easily inspect the previous workflow runs via the PR UI; a rebase would have removed this possibility.

You can inspect commits, for example using git show:

# Is 6aa271cc5c a merge commit?
$ git show 6aa271cc5c
commit 6aa271cc5c502237fb41c14f147425f09f82f5e4 (HEAD -> sqlite3-doc-cleanup-final-headings)
Merge: 5eb1abca3e 18b1782192
Author: Erlend E. Aasland <erlend.aasland@innova.no>
Date:   Mon Aug 22 13:50:02 2022 +0200

    Merge branch 'main' into sqlite3-doc-cleanup-final-headings

[...]
# Yes, it is: see the second line that starts with "Merge:"

If you'd fast-forwarded, you'd mess up the git history in the PR ;)

Oh how so? I'm not sure what this looks like, exactly.

Thinking about it, a --ff-only is in practice never possible with PR's (because main is changed so quickly in CPython); you'll always end up with merge commits. In other words, trying to git merge --ff will end up as a git merge --no-ff, no matter how hard you try; the git history will be just fine :) Also, if main was not touched, a git merge --ff will just tell you that there is nothing to be done.

[erlend-aasland]

It would also be nice to know any tricks for making rebase -i not an absolute nightmare once a merge is performed[...]

Say, if I'd created three new commits on-top of the merge commit, I'd simply do rebase -i HEAD~3, and for example squash them before pushing to the PR.

A better solution may be to find the nearest merge commit and rebase onto that. For example:

$ git log --oneline --merges -n 1                                            
6aa271cc5c Merge branch 'main' into sqlite3-doc-cleanup-final-headings
$ git rebase -i 6aa271cc5c
Successfully rebased and updated refs/heads/sqlite3-doc-cleanup-final-headings.
$

For convenience, you can then alias those operations so you'd have shortcuts for show-me-the-last-merge and rebase-onto-the-last-merge.

[CAM-Gerlach]

which imply losing track of earlier workflow runs,

Yeah, mentioned that one previously, though it varies by PR how many outdated runs are lost track of here (often only one, which is then re-run on the same rebased commit), and how useful they really are. As a reviewer and maintainer, there are a few specific cases where this can be inconvenient, but at least in my experience it is relatively uncommon that I actually actually need this—but maybe its more common for CPython, I imagine on non-docs PRs.

also losing track of earlier review comments and discussions,

Oh, really? If so that's really not good, but I've always kept a careful eye on this and I don't believe I've seen ever review comments actually disappear after rebases. They can be marked Outdated, but as far as I've been able to tell in my impromptu testing, at least nowadays that is based only on whether the content of the line(s) in question actually changed (which should be the same whether there is a merge or a rebase).

To list the commits in this PR like the GitHub UI does, do

Ah, --first-parent was what I was looking for—thanks!

Ah, I was a little bit unclear; it is not the merge commit that is hidden, it is the commits to main since you opened your branch till the merge that are hidden.

Oh, you were just referring to that (i.e. what I was looking for a local equivalent of, i.e. --first-parent)—sorry if I myself was a bit unclear and used up your time writing a detailed explanation.

Thinking about it, a --ff-only is in practice never possible with PR's

Ah yeah, "fast forwarding" after both main and the PR had actual commits would in fact be what git rebase main essentially does.

Say, if I'd created three new commits on-top of the merge commit, I'd simply do rebase -i HEAD~3, and for example squash them before pushing to the PR.

Oh, I didn't meant rebasing after the merge which is essentially trivial; what I was referring to was rebases (fixup, reorder, etc) to the commits before it, or mixing both, which is something we had to do quite a bit for various reasons to PR branches (copyright, changes to binary files, bad commits, poor commit hygiene, etc) when not using squash merges. But as mentioned, that's not really relevant for CPython which does (and on which I'd normally avoid any non-update rebasing and make any changes as separate commits to avoid any problems for reviewers, of course), so if you do have any ideas on that (beyond just cherry-picking and/or basically undoing the merge commit and doing a clean rebase instead) feel free to send them over Discord—I've wandered far enough off topic as it is. And most of that is more easily avoided by just doing a squash merge, which is what we tend to do more these days.

[erlend-aasland]

Ah yeah, "fast forwarding" after both main and the PR had actual commits would in fact be what git rebase main essentially does.

Not exactly; a rebase onto a new base always creates new commits (aka rewrites history). A fast-forward merge does not rewrite history, nor does a non-fast-forward merge. If you try to do a git merge --ff main from a CPython branch after main and your branch has changed, the merge will end up as a non-ff merge (with a merge commit); not as a rebase.

Oh, I didn't meant rebasing after the merge which is essentially trivial; what I was referring to was rebases (fixup, reorder, etc) to the commits before it, or mixing both [...]

Aha. No, that's always painful.

[erlend-aasland]

sorry if I myself was a bit unclear and used up your time writing a detailed explanation.

No problem; I enjoy nerding about git :)

[erlend-aasland]

Sorry for all the git noise, Ezio! I'm ready to land this, but since CAM requested a review from you, I'll hold it until you've given your thumbs up. Thanks, both of you 🙏🏻

[CAM-Gerlach]

Sorry for all the git noise, Ezio! I'm ready to land this, but since CAM requested a review from you, I'll hold it until you've given your thumbs up. Thanks, both of you 🙏🏻

Sorry as well, mostly my fault rather than Erlend's, heh. Approve/merge at your discretion; I applied the first two suggestions and a somewhat different one for the third, but also wanted to give you another chance to chime in.

Not exactly; a rebase onto a new base always creates new commits (aka rewrites history). A fast-forward merge does not rewrite history, nor does a non-fast-forward merge. If you try to do a git merge --ff main from a CPython branch after main and your branch has changed, the merge will end up as a non-ff merge (with a merge commit); not as a rebase.

Sorry, I wasn't clear—what I meant was if there was such a thing as a "fast forward" when both branches have additional commits (i.e. a pull request updating the base branch), it would be functionally equivalent to a rebase, not a merge—which is what you are saying as well.

[ezio-melotti]

LGTM

[miss-islington]

Thanks @CAM-Gerlach for the PR, and @erlend-aasland for merging it 🌮🎉.. I'm working now to backport this PR to: 3.10, 3.11.
🐍🍒⛏🤖

[miss-islington]

Sorry, @CAM-Gerlach and @erlend-aasland, I could not cleanly backport this to 3.11 due to a conflict.
Please backport using cherry_picker on command line.
cherry_picker 6bda5b85b53443f3467865fbf85cbe72932e7cd6 3.11

[miss-islington]

Sorry @CAM-Gerlach and @erlend-aasland, I had trouble checking out the 3.10 backport branch.
Please backport using cherry_picker on command line.
cherry_picker 6bda5b85b53443f3467865fbf85cbe72932e7cd6 3.10

[bedevere-bot]

GH-96226 is a backport of this pull request to the 3.11 branch.

[bedevere-bot]

GH-96227 is a backport of this pull request to the 3.10 branch.