Azure-rest-api-specs: Open Source the Wiki required for contributing to API Specifications

[tombuildsstuff]

👋

Honestly I'm not sure where I should be making this feature request - but here we are.

Occasionally during PR Review the Wiki in this repository is linked too to provide more contextual information about why specific validation failures happen - however unfortunately it's Private:

Whilst the bulk of the changes in this repository are sent by Microsoft Employees - third-parties also contribute to this repository to fix issues where the API Response doesn't match the API Definition (for example #6917 and #7246) - as such the Specifications for the API Specifications (for want of a better word 😄) are frequently linked to in PR's (for example https://github.com/Azure/azure-rest-api-specs/pull/7246#issuecomment-534811713) - and thus I believe the contents of that Wiki appear to be required to be able to effectively contribute to this repository.

Since this information isn't available, third-party PR's often fall by the way-side, since the build is broken with no means of determining why (for example #6917, #7246, #2880, #2645 and #757) - which leads to wasted effort on both third-parties (sending the PR) and Microsoft's front (having to review it, and then close said PR's) - meaning the API Specification remains outdated.

As it appears the contents of this Wiki are required to being able to contribute to this repository - would it be possible for this Wiki to be open-sourced?

It's worth noting this is also linked to in the readme which this issue's tracking: https://github.com/Azure/azure-rest-api-specs/issues/4770 - so other users have noticed the same issue, but not raised an issue about it

Thanks!

[yungezz]

HI @raych1 could you pls help to find a public place for https://github.com/Azure/adx-documentation-pr/wiki/Semantic-and-Model-Violations-Reference? thanks.

[raych1]

@tombuildsstuff @yungezz , the document is moved to here, please check. I close this issue and feel free to re-open if there's still any questions.

[tombuildsstuff]

@raych1 thanks for open sourcing that specific page - but unfortunately this issue/question isn't resolved (since that's just one of the pages available) - as such would you mind re-opening this? Thanks!

[raych1]

@tombuildsstuff , sounds good. I re-open this issue and follow up with team mates to find a public place to host those pages.

[mozehgir]

Hey @tombuildsstuff
I have open sourced some of the other relevant pages as well

Please also note that the wiki that was always being referenced is being deprecated on our end and we have decoupled the internal and external information.

Let me know if you have any more questions. :)

Thanks

[tombuildsstuff]

@mozehgir it's still references in the getting started guide fwiw: https://github.com/Azure/azure-rest-api-specs#getting-started

There's a couple of pages (which were previously public in this repository or a repository linked to from this repository) that I was looking for specifically:

1 - the breaking change guidelines - which it looks like is here: https://github.com/Azure/adx-documentation-pr/wiki/Breaking-changes-guidelines
2 - the broader ARM API Specification (e.g. the API should behave in this manner) - which is helpful for folks looking to learn the "why's" of the Azure API's

If those are still available would it be possible to open-source/link to those from the Wiki?

Thanks!

[mozehgir]

Hey @tombuildsstuff

I have updated the getting started guide and open sourced the breaking changes guidelines. Thanks for pointing them out.

Regarding the ARM API specification, I am not aware of any such document other than this one. Hope this helps.

[Simran-B]

This is still not fully resolved. If you open a pull request, there's a popup that link to CONTRIBUTING.md (contributing guidelines):

That document looks like this:

and it links to https://github.com/Azure/adx-documentation-pr/wiki which is private.

The README.md of this repo has this to offer:

External Contributors can get started here

but there is zero information in the getting started document about formal aspects:

• Are external contributions accepted?
• Under what terms/license?
• Do I need to sign a CLA?
• Are there any requirements regarding branch names, PR description, unit tests etc.