Topic: API review process & meetings (11 votes)

[karelz]

Talking points:

• API review process documented
  • The doc needs a refresh
• Multi-staged review
  1. Area owner/expert drives with community initial design into 'api-ready-for-review' - happens in open, mainly on GitHub
     • Key goal: Clarify intent, alternatives, filter out APIs which clearly don't belong into CoreFX
     • API-design-group not involved by design, to scale
     • Observation: For some difficult design discussions (HashCode, PriorityQueue) it would be more efficient to do ad-hoc calls with interested community members even on this API design level. Question: Ideas / thoughts?
     • Problem: Area owners are often hesitant to say 'no, this is not good idea' (push back results in lots of time on explanations).
     • Problem: We marked many "this doesn't sound right, but maybe we are missing something" APIs as api-needs-work + up-for-grabs, asking question. We plan to review the list of 323 such issues and close them more aggresively if there is no response for long time and we do not see clear win (we will be ready to reopen if we made mistake or the discussion restarts).
  2. API-design-group 'final' review - happens behind closed doors
     • Key value: applying consistency across all BCL, using years of experience
     • API review meetings with API-design-group every Tue, 1-2h (GitHub query) + 0-2h on specific APIs (e.g. Span, etc.)
     • Closed doors by design - it is safe environment to express doubts, questions, mention unannounced dates, products, etc. Experience from other groups tells us having these discussion in the open would add significant (5x) overhead, leading to less APIs being approved.
• We want to make the process transparent, despite the fact that part of it is behind closed door (from good reasons listed above)
  • Any ideas, suggestions?
  • Would it help to record one of such meetings and publish it on youtube? (we can take the "watch what and how you're saying" one time)

[shmuelie]

Observation: For some difficult design discussions (HashCode, PriorityQueue) it would be more efficient to do ad-hoc calls with interested community members even on this API design level. Question: Ideas / thoughts?

They should be recorded and linked to from the issue (and maybe summed up there too)

[tannergooding]

The APIs are behind closed doors, but I don't necessarily think that means the meeting notes need to be.

The C#/VB LDM are similarly behind closed doors, but there has been some active effort to ensure notes are published for each meeting (ex: https://github.com/dotnet/csharplang/blob/master/meetings/2017/LDM-2017-06-14.md).

Perhaps @MadsTorgersen can shed some light as to the overhead of taking and publishing meeting notes.

[MadsTorgersen]

@tannergooding: We find that the closed door/open notes combo works well for us. It provides the benefits of the closed doors described above, while recording the problems, decisions and rationale for the public. We did C# design notes like these throughout the whole lifetime of the language (except for a period of time during Windows 8 where leak paranoia was at its highest), and they prove very valuable both in real time (communicate intent, get feedback) and in the future (rediscover reasons for design decisions to see if they still hold).

The main issue is that they are quite a lot of work to do. Part of the challenge is that I am both note taker and meeting leader (and active participant and contributor), so the notes taken during the meeting are quite rudimentary, and need lots of post-processing. Sometimes cleaning and publishing the notes ends up taking as much time as the meeting they represent. It is a well-known gripe in the community that I am often behind on this process, and as a stopgap measure I have swallowed my pride and started making the raw notes public, announcing in an issue when I've gotten around to cleaning them up.

I think this work is definitely worth my time, though. I'm just saying it is a significant investment. There may be some mitigating steps you can take, like having the meeting leader and note taker be different people.

[karelz]

We just published today's API review discussion recording - see #28

[akoeplinger]

@karelz why in CoreFx instead of https://github.com/dotnet/apireviews ?

[karelz]

First, because I didn't know about the repo. Second, because this is the place where I made the promise.

@terrajobst is apireviews repo the right place for "GitHub Triage" API reviews (as you call them), or do you want to save it only for larger API reviews?

[terrajobst]

I think it makes sense to use apireviews for both API reviews and our triage, as triage tends to focus on API related questions.

[karelz]

Discussed in standup on 2017/9/22 - see #29 for more details and recording link.

[karelz]

Note that we started streaming API reviews live every Tue 10-12am PT.
See https://github.com/dotnet/apireviews for more details.