Contributing guide: Add information about WinUI's API spec discussions #3312
Conversation
ghost
added
the
CONTRIBUTING.md
Outdated
|
|
||
| Before new features will be implemented the WinUI team will do a thorough API spec discussion (API review). This can range from a single new API to an entire new control featuring dozens of new APIs. Joining such a spec discussion is a great opportunity for developers to help ensuring that new WinUI APIs will look and feel natural and are a joy to work with. In addition, spec discussions are the follow-up to feature proposals and will go into much finer details than the initial proposal. As such, taking part in these discussions gives developers the chance to be involved in the complete development process of new WinUI features - from their initial high-level inception right down to specific implementation/behavior details. | ||
|
|
||
| These discussions will be take place in their own [repository](https://github.com/microsoft/microsoft-ui-xaml-specs). While API specs for feature proposals will typically be linked to in the specific proposal on the WinUI repository, not all active API specs will immediately be mentioned there. Thus, if you don't want to miss out on them, we recommend that you [watch the repository](https://docs.github.com/en/enterprise/2.15/user/articles/watching-and-unwatching-repositories). |
There was a problem hiding this comment.
An API spec not (initially) mentioned by the team on the WinUI repo for example is the Application and Windowing Spec for WinUI 3. The spec could only be discovered by a community member if they were watching the specs repo or another member of the community mentioned it to them.
StephenLPeters
added
documentation
|
/azp run |
|
@anawishnoff FYI |
|
Azure Pipelines successfully started running 1 pipeline(s). |
|
Thank you for updating this Felix. Do you see any benefit to having the separate repo? There originally was some reasoning to it being separate, but at this point I think it would be better as a specs directory of this repo. |
|
@MikeHillberg I do think having a separate "specs" repo harms community input. For example, the specs repo has just one-fifth of the repo watchers the WinUI repo has, yet the APIs being discussed/reviewed there are vitally important to many (future) WinUI customers, such as the WinUI 3 Application and Windowing APIs. However, the WinUI repo is the advertised repo for the WinUI product and thus the forefront of community involvement. Not the specs repo. As a result, many community members, who might be watching the WinUI repo but not the specs repo, will miss out on these dicsussions or have to learn about them otherwise (twitter, linked to from WinUI repo,...). Another point is that we have already seen quite a few cases where new APIs were proposed as a result of discussions happening in PRs/bug discussions for WinUI. If I recall correctly, some examples would be the IndexPath spec or the TreeView SelectionChanged spec. In other words, a lot of the basics would already be discussed in the WinUI repo but the final formalization would happen in the specs repo. So we have a repo separation here even though the major work (discovering an API gap & thinking about some (initial) API design to close that gap) is already happening in the WinUI repo, which thus creates a "soft" border between the WinUI repo and the WinUI specs repo. And if that "border" is a fluent one, it raises the question if its actually needed. It sounds natural to me if all steps of feature development - from the high-level inception, to the in-detail API discussion and last but not least the actual feature implemenation - would take place in the same repo. Feature proposals and implementation already happen in the WinUI repo. API spec discussions could, too. As you have mentioned, we could create a "specs" folder in the root of the WinUI repository and move the API spec discussions there. Project Reunion, for example, is using that very structure and it appears to work just fine to me. Having said all this, I think you are raising a good question here and I for one think we should move the API spec discussions into the WinUI repo. That way, all the steps of feature development will happen in the same repo - and easily discoverable. |
API spec discussions - which take place in their own repo - have not yet been mentioned in the Contributing doc. This could stifle community input especially when a new API spec has not been mentioned on the WinUI repo. This PR seeks to remedy this.