Template packages in docs repo

[danieljurek]

Template packages do not need to be released to the docs site, but they're useful for validating our release pipelines. Future work should take this into account and probably:

• In the case of docs.ms -- where we're heading these changes will be checked directly into the docs main branch. Is there something we can do here to ensure that template ref docs don't go out? It's helpful to see what the changes would look like in an e2e test. Perhaps there's a way to ignore these or put them in a non-publishing place?
• In the case of githubio -- Is there a way to ignore these in the ToC?

[sima-zhu]

github IO read from release csv. If Hide=true, then we do not display it in toc. I believe current github pages have the right setup

[sima-zhu]

For docs.ms, our new approach is trying to sync with release csv, which filter out the package hide=true. It helps with this issue too.

[sima-zhu]

The template only got updates only through template release pipeline for testing purpose. If we do not want to have the template, then we can remove it from matadata/azure-template.json and ci-configs/preview.json

[sima-zhu]

We currently maintain the exclude list. We can put template over there. https://github.com/Azure/azure-sdk-for-python/blob/main/eng/scripts/Language-Settings.ps1#L196

[sima-zhu]

One feasible design

Two changes:

• Add template into the exclude list here: https://github.com/Azure/azure-sdk-for-python/blob/main/eng/scripts/Language-Settings.ps1#L196
• Add a step of removing template block from ci-config/preview.json|ci-config/latest.json in docindex dealing with main branch. https://github.com/Azure/azure-sdk-for-python/blob/main/eng/pipelines/docindex.yml

Covered cases:

	DailyUpdate	Release
In template testing	Comment out template from exclude list	1. Comment out template from exclude list 2. Add variable of skip removing step if necessary
Not in testing	Nothing	Nothing

[danieljurek]

@weshaggard and I discussed another option that helps us preserve commit history to show the change. Here's my view on how it could be implemented.

• Delete template from entries in /metadata folder in docs repo
• On publishing template for release pass TestPipeline (set to true in the case of Template pipelines) into git-push-changes.yml
• If TestPipeline is true then before push (inside of git-push-changes.yml):
  • Commit changes to git repo using the CommitMsg
  • Revert commit (this results in a new commit that cancels the previous commit out and leaves the repo unchanged)
  • Push changes

This means that the file state in the repo doesn't change but the template run makes the changes that would've been made. One can always look back through the commit history to see what the changes would've been.

We use a similar strategy with this when testing publishing updates to the vcpkg repository. In this case vcpkg is an active public git repository and we don't want our PRs to introduce noise. When we open a PR (opening PRs is how you release in vcpkg) we immediately close the PR once it's opened. This way we can see the effects of the system without cluttering contributors' experience: https://github.com/microsoft/vcpkg/pull/20081

[sima-zhu]

Template currently set 'Hide' to 'true'. Issue has been resolved. Closed the issue.