Coder Social home page Coder Social logo

vscode-docs-build's Introduction

Learn Validation

This extension enables you to run build validation on a Learn conceptual or reference repository at author time in VS Code. This means you can make sure your repo is free of validation issues before making a pull request.

Prerequisites

  • Install git.
  • Clone your Learn repo locally in VS Code.
  • All files in the repo must be saved when you are using the manually triggered validation.

How to use the Learn Validation extension

Manually triggered validation

  1. Open the root folder or any sub-folder of a Learn repository in VS Code with the extension installed.
  2. For the first time you use the extension, you will be asked to choose your user type between Microsoft employee and Public contributor before you can use full-repository validation.
  3. For Microsoft employee, you are required to sign in before using full-repository validation. You can click Learn Validation on the status bar then click Sign in from the drop-down menu to sign in.
  4. There are three ways to trigger the manual validation:
    1. After signing in, you can trigger a validation by clicking Validate when prompted. This will trigger the validation on the current opening workspace, so the files outside the current workspace will not be validated if you are on the sub-folder of a repository.
    2. You can click Learn Validation on the status bar then click Validate the current workspace from the drop-down menu to trigger the validation on the current workspace.
    3. You can right-click any file/folder inside the Explorer and select Validate this folder, if you click on the file, the validation will be applied to the folder contains the selected file, otherwise, the validation will be applied to the selected folder.
  5. Build validation will run locally and all results will be output to the Problems pane.

OAuth

Note: The first time you validate a repo, all the Learn build dependencies will be fetched and cached locally. Subsequent validation runs will be faster.

Real-time validation

  1. Open the root folder or any sub-folder of a or Learn repository in VS Code with the extension installed.
  2. For the first time you use the extension, you will be asked to choose your user type between Microsoft employee and Public contributor before you can use real-time validation.
  3. The real-time validation is enabled by default, you can disable it in the extension settings (Go to Settings -> Learn Validation -> Uncheck Real-time Validation: Automatically Enable). You will be asked to reload the extension after you disable real-time validation.

OAuth

  1. For Microsoft employee, the extension will check your sign-in status before real-time validation starts to work. If you haven't signed in or your credential expired, you will be asked to sign in. After sign-in succeeds, real-time validation will start automatically.
  2. With real-time validation enabled, you will see validation issues (if any) while you are working on the repository (eg. modifying files, creating files and deleting files etc.).

OAuth

Known issues

Inconsistent results between Learn Build validation and full-repository validation.

  • bookmark-not-found: The rendering information required to validate bookmarks in schema-based content isn't available publicly, so if you aren't signed in as a Microsoft employee you might not get all broken bookmark results.
  • author-not-found and ms-author-invalid: These validations require external API calls that aren't supported locally at this time, so no results will be returned for them.

Inconsistent results between real-time validation and full-repository validation.

These inconsistent results mainly come from two situations: the currently edited file needs validation results from other files and the currently edited file affects other files' validation results. The real-time validation now will only validates the open files. Therefore, some inconsistent results will show when the files related to these two situations are not opened.

Inconsistent results caused by the currently edited file needs validation results from other files:

  • publish-url-conflict
  • output-path-conflict
  • Content or Metadata uniqueness
    • duplicate-uid
    • xref-property-conflict
    • moniker-overlapping
    • duplicate-title
    • altText-duplicate
    • duplicate-h1
    • ...
  • bookmark-not-found
  • Validation on hierarchy (for example unit-no-module-parent)

Inconsistent results caused by the currently edited file affects other files' validation results:

  • xref-not-found
  • bookmark-not-found
  • circular-reference
  • include-not-found
  • file-not-found

Other situations:

  • Pull-request-only suggestions will be ignored by full-repository validation but will be reported by real-time validation.
  • Include files will not be validated before you open any file includes them.
  • .openpublishing.redirection.json will not be validated before you open any content file (.md or .yml).

Note: Validation is not available currently for workspaces with multiple folders.

Troubleshooting

You might encounter the following issues when using the extension.

Clone template repository or dependencies failed

When your validation fails with some error message like:

fatal: unable to access 'https://github.com/Microsoft/templates.docs.msft/': The requested URL returned error: 403
git-clone-failed Failure to clone the repository `https://github.com/Microsoft/templates.docs.msft#master`. This could be caused by an incorrect repository URL, please verify the URL on the Microsoft Learn Portal (https://ops.microsoft.com). This could also be caused by not having the proper permission the repository, please confirm that the GitHub group/team that triggered the build has access to the repository.
Restore done in 11.77s

  1 Error(s), 0 Warning(s), 0 Suggestion(s)
Error: running 'docfx restore' failed with exit code: 1

Please try the following solutions:

  1. Make sure you can access this repository https://github.com/Microsoft/templates.docs.msft on GitHub, if not, please join the Microsoft org by the this website, after that, try again.

  2. Try to clone the template repository in a separated terminal by running the following command:

    $ git clone https://github.com/Microsoft/templates.docs.msft
  3. If you have enabled 2FA on GitHub and you run into the following errors when you clone the repository, please follow these instructions.

    Cloning into 'templates.docs.msft'...
    Username for 'https://github.com': 928PJY
    Password tor 'https: //[email protected]':
    remote: Invalid username or password.
    fatal: Authentication failed for https://github. com/Microsoft/templates.docs.msft/'
  4. GitHub has recently enabled SSO on Microsoft-owned organizations. If you see the below errors, please follow the instructions there to enable SSO on your token so that local validation can pass through.

    fatal: unable to access 'https://github.com/Microsoft/templates.docs.msft/': The requested URL returned error: 403
    remote: The `microsoft' organization has enabled or enforced SAML SSO. To access
    remote: this repository, visit https://github.com/enterprises/microsoftopensource/sso?authorization_request=AEJANEWOPPW6YTNW5TYNW2K7OBDR3A5PN5ZGOYLONF5GC5DJN5XF62LEZYAF32PCVVRXEZLEMVXHI2LBNRPWSZGODVDHWBVPMNZGKZDFNZ2GSYLML52HS4DFVNHWC5LUNBAWGY3FONZQ
  5. If you see the below errors while cloning the template repository, this is caused by that you used the Git Credential Manager Core before GitHub enabled the SSO, and you need to re-authorize the application.

    $ git clone https://github.com/microsoft/templates.docs.msft.git
    Cloning into 'templates.docs.msft'...
    remote: The `microsoft' organization has enabled or enforced SAML SSO. To access
    remote: this repository, you must re-authorize the OAuth Application `Git Credential Manager`.
    fatal: unable to access 'https://github.com/microsoft/templates.docs.msft.git/': The requested URL returned error: 403

    Please follow the steps below to re-authorize, you can either:

    • Sign in with your browser.

      a. Go to Github application setting page.

      b. Go inside Git Credential Manager and click Revoke access.

      c. Retry to clone the repository in commander/ terminal.

      d. Select Sign in with your browser in the pop-up window.

    • Sign in with Personal Access Token.

      a. Go to Github token setting page.

      b. Generate a new token if you don't have one. Enter the note of the token, check repo in Select scopes section, and click Generate token.

      c. Enable the SSO for the token used in Git Credential Manager Core.

      OAuth

      d. Retry to clone the repository in commander/ terminal.

      e. Enter Personal Access Token in the pop-up window.

License

MIT

Privacy statements

For Microsoft employee: https://privacy.microsoft.com/en-US/data-privacy-notice
For Public contributor: https://privacy.microsoft.com/en-us/privacystatement

Key

Issue

File a issue

How to Contribute

Contribution guideline

Pipelines

Pipeline Description Trigger condition Status
vscode-docs-build-CodeCheck SDL related code check built on OneBranch PR created to main branch
or Code Merged into main branch
Build Status
vscode-docs-build-CodeTest Run Test and collect the test coverage on two platforms: Windows and MacOS PR created to main branch
or Code Merged into main branch
Build Status
vscode-docs-build-LGTM LGTM related check Code Merged into main branch Build Status
vscode-docs-build-Official Official release pipeline Manual trigger Build Status

Secrets management

Please reference the document Secrets managements for the detail

All contributions are welcome!

vscode-docs-build's People

Contributors

928pjy avatar herohua avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar

vscode-docs-build's Issues

Rea-time validation known issues

Known issues:

  • When the user opens one file, all diagnostics reported when building this file (some maybe not related to this file, like an issue in a toc that has no relation with this file). when the user closes the current file, all the diagnostics in the current file will be cleared, but others won't until the user explicitly open and close that file.
    The impact is limited for the following two reasons:
    • All the errors reported can be treated as related since it is a dependency when building this file, it can be improved by making the dependency build more accurate.
    • In most cases, the current repository should be perfect, all the new issues should be took care.

Ideas:

  • Currently, we have debounce mechanism, but we maybe we can assign different debounce windows for different event.

Public Contributor/Microsoft Employee setting

One has to go to the @ext:docsmsft.docs-build extension settings to switch from Microsoft Employee to Public Contributor, but that's not called out anywhere. I recommend that you call that out to folks in VS's extension message about making the selection so that they know where to set the User Type to Public Contributor if they accidentally set it to MS employee, as I did by mistake.

Error not show in `PROBLEM` tab

repository: https://github.com/MicrosoftDocs/microsoft-365-docs-pr

Channel output:

Building files done in 2.59s

output-path-conflict ./(0,0): Two or more files output to the same path 'microsoft-365/compliance/information-barriers-edit-segments-policies.raw.page.json': 'compliance/information-barriers-edit-segments-policies.md', 'compliance/information-barriers-edit-segments-policies.md [redirection]'

Build 'Microsoft-365-docs' done in 3.52s

  1 Error(s), 0 Warning(s), 0 Suggestion(s)

Support virtual workspaces

๐Ÿ‘‹ Hi there, Martin here, from the VS Code team.

Recently we've announced the Remote Repository feature that lets you browse and edit files and folders directly on GitHub.

Open Remote Repository... opens VSCode on a folder or workspace located on a virtual file system. We call this a virtual workspace. We observed that not all extension support this well, either because they can not, or they haven't thought about it.

It would be fantastic if you could test whether your extension can handle virtual workspaces:

Check out the Virtual Workspaces Extension Author Guide on how to do that.

When done, set the new virtualWorkspaces capability in your 'package.json'.

{
  "capabilities": {
    "virtualWorkspaces": true | false
  }
}
  • Use "virtualWorkspaces": true if your extension is prepared for virtual workspaces
  • Use "virtualWorkspaces": false if your extension should be disabled when a virtual workspace is opened

For questions and comments please use the Virtual Workspaces Tracking Issue.

Thanks for the support and the great work! โค๏ธ

Learn more button redirection link not right

Since the document URL of code reported from validation and build service is not the same, we cannot generate the right document URL for both of them.
for now it always redirect user to https://aka.ms/${diagnostic.code}

Support Workspace Trust

Hello ๐Ÿ‘‹ I'm from the VS Code team.

Recently, we have been exploring a security feature we refer to as Workspace Trust. This feature is intended to centralize and unify a security conscious decision required by a variety of VS Code features. With workspace trust, the user will be able to declare whether or not they trust the folder that is opened in VS Code before these features are executed.

Why you should care

Your extension is incredibly popular with VS Code users! We want to make sure that those users have a delightful experience with workspace trust and that includes extension authors deciding how much of their extension is supported in an untrusted workspace.

Workspace Trust experience

You can enable the feature with the following setting security.workspace.trust.enabled. Once enabled, you will see the following dialog when opening folders in VS Code.

Workspace Trust Startup Dialog

This dialog is important for allowing the user to make a decision early and understand the impact of their decision. Once you understand the feature, you may want to customize when to display the dialog using the setting security.workspace.trust.startupPrompt.

You can follow the development of Workspace Trust and provide feedback in issue #106488.

Workspace trust API

First off, all of what I am about to say can be found in issue #120251. That issue will include discussion of the feature and any updates to the feature.

The Workspace Trust extension API is now in stable. This allowed us to release the first cut of our guide for onboarding your extension to Workspace Trust. The API is small, so here is a quick look.

You can declare your extension to provide complete, partial or no support in untrusted workspaces using the untrustedWorkspaces capability in package.json.

The following example declares that the extension is supported completely in untrusted workspaces. In this case, the extension is enabled in untrusted workspaces.

"capabilities": {
  "untrustedWorkspaces": {
    "supported": true
  }
}

The next example declares that the extension is not supported in untrusted workspaces. In this case, the extension is disabled in untrusted workspaces.

"capabilities": {
  "untrustedWorkspaces": {
    "supported": false
  }
}

The third option is to declared limited support. There are three tools provided to you when you select the limited option.

First, if you have a setting that can be configured in the workspace but requires the workspace to be trusted in order to apply the workspace value, then you can include the setting using restrictedConfigurations array property in untrustedWorkspaces object. Doing so, VS Code will ignore the workspace value of these restricted settings when your extension reads these settings values using the VS Code Workspace Configuration API.

The following example declares the settings that are restricted in untrusted workspaces.

"capabilities": {
  "untrustedWorkspaces": {
    "supported": "limited",
    "restrictedConfigurations": [
      "markdown.styles"
    ]
  }
}

Next, you can also check and listen if the current workspace is trusted or not programmatically using the following API:

export namespace workspace {
  /**
   * When true, the user has explicitly trusted the contents of the workspace.
   */
  export const isTrusted: boolean;
  /**
   * Event that fires when the current workspace has been trusted.
   */
  export const onDidGrantWorkspaceTrust: Event<void>;
}

Lastly, you can hide commands or views declaratively with the isWorkspaceTrusted context key in your when clauses.

A far more detailed guide on how to onboard which will be updated as we receive feedback can be found in issue #120251.

Rollout plan

Workspace Trust will remain disabled for the month of May, but we are planning on enabling this by default in the future. To prepare for that day, we would love for you to try it out and provide feedback.

We'd love your feedback

Since this issue was created in an automated fashion, we won't be monitoring the responses in this issue (our notifications would explode!). Instead we ask you to drop questions, and feedback in issue #120251 as we've mentioned above.

We're excited to see what you do with workspace trust!

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.