aspnetcore icon indicating copy to clipboard operation
aspnetcore copied to clipboard

Published 20 hours ago • verified publisher icon dotnet

[release/7.0] Fixing XML documentation

Open github-actions[bot] opened this issue 3 years ago • 1 comments

Backport of #44511 to release/7.0

/cc @brunolins16

Fixing XML documentation

Description

Updates some api comments to correctly be processed and show in the Learn Portal

Fixes #44428

Customer Impact

Without the change the documentation is really bad and only include empty bullets.

Eg.: image

Regression?

  • [ ] Yes
  • [X] No

Risk

  • [ ] High
  • [ ] Medium
  • [X] Low

The change only updates the API documentation that will reflect in the Learn portal.

Verification

  • [X] Manual (required)
  • [X] Automated

Packaging changes reviewed?

  • [ ] Yes
  • [ ] No
  • [X] N/A

github-actions[bot] avatar Oct 13 '22 13:10 github-actions[bot]

Hi @github-actions[bot]. Please make sure you've updated the PR description to use the Shiproom Template. Also, make sure this PR is not marked as a draft and is ready-to-merge.

To learn more about how to prepare a servicing PR click here.

ghost avatar Oct 14 '22 17:10 ghost

@danmoseley I assume we can skip shiproom for this since it's just changing doc comments.

adityamandaleeka avatar Oct 18 '22 22:10 adityamandaleeka

At this stage the concern might be the risk of any change. How close are we to final build?

danmoseley avatar Oct 19 '22 02:10 danmoseley

At this stage the concern might be the risk of any change. How close are we to final build?

I am not sure how close we are but @dougbu might have more information.

brunolins16 avatar Oct 20 '22 04:10 brunolins16

I believe we've got a final GA build. Given this isn't servicing approved and we're in the middle of the repo stack, I suggest waiting for 7.0.1 unless @mmitche is enthusiastic.

dougbu avatar Oct 20 '22 17:10 dougbu

discussed in tactics, and at this point we want to take for 7.0.1. however, I want to check -- is there a documentation update in servicing? ie., would this even have an effect in docs if we don't take in GA?

danmoseley avatar Oct 20 '22 17:10 danmoseley

Not sure when the Learn Portal gets updated. However, wouldn't this PR improve the IntelliSense experience❔

dougbu avatar Oct 20 '22 17:10 dougbu

Not sure when the Learn Portal gets updated. However, wouldn't this PR improve the IntelliSense experience❔

No. The IntelliSense experience is not broken right now.

brunolins16 avatar Oct 20 '22 18:10 brunolins16

Can you find out when the portal is updated and whether a change post GA would even make any difference? If not, we wouldn't take this (and the linked one - maybe we should have combined the PR's)

danmoseley avatar Oct 20 '22 20:10 danmoseley

Can you find out when the portal is updated and whether a change post GA would even make any difference?

Who has this action item❔ xakep139 doesn't seem to work in Microsoft.

dougbu avatar Oct 20 '22 20:10 dougbu

@Rick-Anderson likely knows the answer to that^

adityamandaleeka avatar Oct 20 '22 21:10 adityamandaleeka

Can you find out when the portal is updated and whether a change post GA would even make any difference? If not, we wouldn't take this (and the linked one - maybe we should have combined the PR's)

The /dotnet/api doc's aren't changed post GA unless we order a refresh, which is easy to do. AFAIK, that would only impact the 7.0 API docs. cc @v-alje @gewarren

Rick-Anderson avatar Oct 20 '22 22:10 Rick-Anderson

unless we order a refresh, which is easy to do.

Is that a well exercised, well understood process? I'm just wondering whether we'd be doing something "unusual" by requesting this on a servicing release, and that would mean it would potentially create some problem.

Incidentally, when do you normally start to throw up docs for the next release? Eg., as soon as .NET 8 preview 1? I ask because presumably when those are up, they will include the "corrected" docs.

danmoseley avatar Oct 20 '22 22:10 danmoseley

Is that a well exercised, well understood process? I'm just wondering whether we'd be doing something "unusual" by requesting this on a servicing release, and that would mean it would potentially create some problem.

Updating for a service release is the same process as for a preview or full release. The configurations are currently set to pull in the changes for the latest preview version. Once the full release publishes, we will need to remove preview from the configuration then it will be the latest packages until previews for 8 publish. When the NuGet packages for 8 publish, we will need to lock in 7 to the latest service release and manually update the version numbers in the configuration file as needed.

Yes, once we pick up the packages for 8, the text in the XML content of those NuGet packages will replace the older documentation.

v-alje avatar Oct 20 '22 23:10 v-alje

OK, sounds like there's indeed benefit in including these two PRs in 7.0.1. No objections from me.

danmoseley avatar Oct 21 '22 00:10 danmoseley

OK, sounds like there's indeed benefit in including these two PRs in 7.0.1. No objections from me.

OK, I will work to have both PRs merged when 7.0.1. Thanks

brunolins16 avatar Oct 21 '22 02:10 brunolins16

@dotnet/aspnet-build since branch is open, can someone help me with this.

brunolins16 avatar Nov 02 '22 05:11 brunolins16

7.0 in this repo isn't open yet, there are some issues with the branding PR. We'll merge this once that's resolved

wtgodbe avatar Nov 02 '22 16:11 wtgodbe