ENB: Clarifying Leo's API

[Edward K. Ream]

Recent PRs have introduced breaking changes into Leo's API. This Engineering Notebook post discusses the steps I am taking to ensure that the recent changes are sound.

Background

Issue #4800 will document all breaking changes. This issue will be pre-writing for the Leo 6.8.10 documentation in LeoDocs.leo.

PR #4801 will fix all glitches that I discover while reviewing the changed API.

Fixing potential problems

I didn't fully understand the implications of the PRs that changed Leo's annotations. #4800 explains why changing the values returned by (some) functions/methods does indeed constitute a breaking change.

So I must now thoroughly review all functions/methods whose return values have changed. The general procedure:

First, diff all core files, comparing the "devel" and "main" branches using this script:

from leo.commands import editFileCommands as efc

efc.GitDiffController(c).diff_two_revs(
    rev1='main',  # Old
    rev2='devel',  # New
    # Optional path, relative to the git directory.
    path='leo/core',
)

Second, for each of the 40 changed files, find the functions/methods whose annotated return values have changed.

Third, for each function/method whose return value has changed, do a cff to find all calls to the changed routine.

Fourth, for each such call, make sure that all tests on the returned value are pythonic rather than tests on None.

Many checks

There is a lot of work to be done. The PR will likely contain one or more commits for many of the routines whose returned values have changed. Each commit will change (in calling routines) old tests (tests on None) to pythonic tests. All such commits fix potential bugs.

Other commits will clean called (changed) routines as suggested by the cffs. For example, the PR changes g.openUrlHelper. It now always returns None because no caller ever used its return value. This change removes a subtle confusion.

Summary

Only recently have I come to understand the full extent of the checking required to ensure that previous PRs have not introduced bugs. It will take a week or more to perform those checks carefully.

That work is much more than mere drudgery. It has already uncovered significant improvements to Leo's API.

For more than a decade, I have said that all parts of Leo's API were available to writers of scripts and plugins. But has been a somewhat hollow statement because the API wasn't clearly defined. Now it is.

All of your questions, comments, and suggestions are welcome.

​Edward