Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Contributing guide: Add information about WinUI's API spec discussions #3312

Merged
merged 4 commits into from
Sep 24, 2020

Conversation

Felix-Dev
Copy link
Contributor

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.

@ghost ghost added the needs-triage Issue needs to be triaged by the area owners label Sep 22, 2020
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).
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 StephenLPeters added documentation An issue with existing documentation or a request for documenation of a new topic team-Controls Issue for the Controls team and removed needs-triage Issue needs to be triaged by the area owners labels Sep 22, 2020
CONTRIBUTING.md Outdated Show resolved Hide resolved
CONTRIBUTING.md Outdated Show resolved Hide resolved
CONTRIBUTING.md Outdated Show resolved Hide resolved
@StephenLPeters
Copy link
Contributor

/azp run

@StephenLPeters
Copy link
Contributor

@anawishnoff FYI

@azure-pipelines
Copy link

Azure Pipelines successfully started running 1 pipeline(s).

@MikeHillberg
Copy link
Contributor

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.

@Felix-Dev
Copy link
Contributor Author

Felix-Dev commented Sep 24, 2020

@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.

@anawishnoff anawishnoff merged commit a9713df into microsoft:master Sep 24, 2020
@Felix-Dev Felix-Dev deleted the patch-1 branch September 24, 2020 14:55
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation An issue with existing documentation or a request for documenation of a new topic team-Controls Issue for the Controls team
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants