[Development] (To what extent) Should we start the API change review earlier ?

[Edward Welbourne]

Volker Hilsheimer (9 May 2023 17:01) wrote:
> The primary purpose of the header review is to catch *technical*
> mistakes - BC or SC breakages - rather than to discuss API design,
> naming, or style.

Some technical errors are future-readiness: as long as we have BC and SC
commitments, we have to think about whether what we design today will
leave us with a BC or SC constraint preventing us from improving on
today's design later, when new requirements surface or we discover any
limitations of the initial design.  Consequently, discussions of API
design, naming and even style can be relevant to determining whether we
have made a technical error in the present design.

> So starting the header review process when we still expect changes
> might not be useful. I think starting it when we are in beta makes
> sense.

We certainly can't close a review until after FF, even if we do start
one before.  The advantage of starting early is to give more time for
the conversations to happen and the consequent fixes to be sorted out.

> But the reality is that the header review got rather conflated with
> API review (and, as far as template code in headers is concerned, even
> implementation review) in the last iterations. And while that is
> sometimes ok, the header review isn’t the right process to discuss the
> design of more complex frameworks.

Obviously the best time to review a new API or a change to API is when
it is first introduced, long before FF or the API change review.  All
the same, the latter can bring more eyes to the change and more insights
into potential problems with the change.  The initial change was
typically reviewed by folk working closely with the particular part of
the code-base; the API change review is apt to bring the change to the
attention of potential clients of the new API, or to folk who've
previously designed similar-shaped APIs for other purposes, who may have
valuable insights into the new design.

OTOH, when we're all rushing headlong towards the deadline of FF, an
early start to the API change review might be of limited value, simply
because relevant folk are too busy to have those conversations.  And the
part of the process which has been slow at recent releases has been
getting all the modules signed off by their respective Maintainers; it's
not really clear to me that an earlier start would help with that.

	Eddy.