Aspnetcore.docs: Adding a third-party community project to the official docs

[ivaylokenov]

Copy pasted from https://github.com/aspnet/AspNetCore/issues/14381 as @Rick-Anderson said.

Hi, guys! I didn’t know where I can ask my question so I decided to open an issue here.

One of my projects has been referenced as a community project in the Readme.md file in the old Mvc repository and currently in the Mvc folder for more than 2 years now. It can be found here: https://github.com/ivaylokenov/MyTested.AspNetCore.Mvc. The project is a testing library providing easy fluent API with strongly-type support for asserting controllers, models, services, routes, pipeline and more. A lot of built-in mocks are included out of the box - database, session, cache, options, authentication, etc. An example test looks like this:

c# // Tests a route for correct route values, // and validates whether the controller action // with an authenticated user and the provided data // returns redirect result to a specific action, // while resolving services from the `TestStartup` class. MyMvc .Pipeline() .ShouldMap("/My/Action/1") .To<MyController>(c => c.Action(1)) .Which(controller => controller .WithUser() .WithData(MyDataProvider.GetMyModels())) .ShouldReturn() .Redirect(redirect => redirect .To<AnotherController>(c => c.AnotherAction()));

However, ever since the ASP.NET Core team moved all repositories into one place, the link kind of got lost as it is not on the main page. I noticed quite a huge decrease of traffic coming from GitHub.

Yesterday, while I was reading your documentation pages, I saw you reference some third-party projects there, for example:

• https://docs.microsoft.com/en-gb/aspnet/core/host-and-deploy/health-checks?view=aspnetcore-3.0#prerequisites
  
  
  
  • https://docs.microsoft.com/en-gb/aspnet/core/test/load-tests?view=aspnetcore-3.0#third-party-tools
  
  

Are there any requirements for adding a link to my GitHub repository, and a small sample code from it in there (with a visible alert that it’s a third party package and Microsoft does not support it)?

I can open a small pull-request in the documentation repository, if that’s OK for you.

My project is in very healthy state. It has two sponsor companies, and I am currently negotiating with two more. I am the only core contributor, but I have a team of 10 volunteers, who help a lot in their free time. Bits for version 3.0 are ready and working with the latest final release. I will publish them to NuGet in one-two weeks.

What are your thoughts on my question?

Thank you for reading!

Kind regards!

[Rick-Anderson]

@ivaylokenov looks good to me. We need permission from @danroth27 to link to non-MSFT content. We can create a discussion issue in the repo with an introduction to your testing library and likes to your code. We can probably sneak in links to the discussion issue without @danroth27 noticing.

@guardrex can you suggest where we should add links to said discussion issue or straight link to his repo?

cc @scottaddie

[guardrex]

I'll wait before remarking given that @danroth27 has said on a few occasions that linking to things that MS doesn't control is a concern ... not a deal breaker, of course ... I've just seen a few external links dropped or prevented on that basis.

[danroth27]

I'm very much in favor of promoting related community projects, so I think having links to related projects at the bottom of some of our articles is fine, but I'd prefer not to have sample code or docs for other projects in our docs except for the few cases where we've have setup specific partnerships (ex IdentityServer, Swagger). I just don't want to become the one place where everyone in the ecosystem wants to put their docs.

[guardrex]

The corollary page is probably ...

https://docs.microsoft.com/aspnet/core/mvc/overview

promoting related community projects

The following are just thoughts, probably rhetorical in nature. I'm just calling out a few potential concerns.

What about security? Should readers be told explicitly that 3rd party projects haven't been verified safe for use by MS, that use of such technology is potentially not performant, and that MS isn't promoting or recommending the technology?

Adding links to 3rd party will be time-consuming. It's burdensome given the workload if the docs team starts receiving many requests to have their 3rd party thing listed and they don't want to submit the PR. Even if they do submit the PR, I can _absolutely guarantee to you_ after handling our Blazor.Docs Community Projects section that they won't set the links up correctly (e.g., alphabetical order, formatted correctly, proper grammatical phrasing, following the style manual guidelines, and avoiding the use of wildly over-the-top marketing language). We'll end up having to edit most submissions. :point_left: I'll wager any amount 💰 that I'm correct on that point after living it. :smile: lol

What about fairness? There must be _thousands_ of projects. Who gets in? Who doesn't? If some folks are going to be denied, shouldn't the criteria for inclusion be explicitly stated somewhere? What is the criteria? I'm just say'in. Fair's fair.

"Fair's fair." :smile: lol ... I just had an '80's flashback moment to ......

_Fair is fair!_ - Billie Jean Davy (Helen Slater) - The Legend of Billie Jean ©1985 Sony Pictures Entertainment

[ivaylokenov]

Thank you! 🙏