From 8889be74f1240287ecbe1e68ef33e214fa7de010 Mon Sep 17 00:00:00 2001 From: Travis Plunk Date: Fri, 14 Jul 2023 10:46:14 -0700 Subject: [PATCH 01/10] Remove spelling CI --- .vsts-ci/misc-analysis.yml | 5 ----- 1 file changed, 5 deletions(-) diff --git a/.vsts-ci/misc-analysis.yml b/.vsts-ci/misc-analysis.yml index b9e19a2a505..15b3277635b 100644 --- a/.vsts-ci/misc-analysis.yml +++ b/.vsts-ci/misc-analysis.yml @@ -46,8 +46,3 @@ stages: - checkout: ComplianceRepo - template: ci-compliance.yml@ComplianceRepo -- stage: markdown_spelling_lint - displayName: Markdown Spelling and Lint - dependsOn: [] - jobs: - - template: ./misc-analysis/mdSpell.yml From 3902de240cbe9cdc3fcb8873b3eeca39031d0080 Mon Sep 17 00:00:00 2001 From: Travis Plunk Date: Fri, 14 Jul 2023 10:47:44 -0700 Subject: [PATCH 02/10] Delete mdSpell.yml --- .vsts-ci/misc-analysis/mdSpell.yml | 56 ------------------------------ 1 file changed, 56 deletions(-) delete mode 100644 .vsts-ci/misc-analysis/mdSpell.yml diff --git a/.vsts-ci/misc-analysis/mdSpell.yml b/.vsts-ci/misc-analysis/mdSpell.yml deleted file mode 100644 index e9d046e5e96..00000000000 --- a/.vsts-ci/misc-analysis/mdSpell.yml +++ /dev/null @@ -1,56 +0,0 @@ -jobs: -- job: markdown - displayName: Markdown Spelling - - pool: - vmImage: ubuntu-20.04 - - variables: - - name: repoPath - value: $(Agent.BuildDirectory)/$(repoFolder) - - steps: - - checkout: self - clean: true - path: $(repoFolder) - - - checkout: ComplianceRepo - - - powershell: | - Get-ChildItem -Path env: - displayName: Capture Environment - condition: succeededOrFailed() - - - bash: | - curl -o- --progress-bar -L https://yarnpkg.com/install.sh | bash - displayName: Bootstrap Yarn - condition: succeededOrFailed() - - - bash: | - sudo yarn global add markdown-spellcheck@0.11.0 - displayName: Install mdspell - condition: succeededOrFailed() - - - bash: | - mdspell '**/*.md' '!**/Pester/**/*.md' '!**/dotnet-tools/**/*.md' --ignore-numbers --ignore-acronyms --report --en-us; - displayName: Test Spelling in Markdown - condition: succeededOrFailed() - workingDirectory: '$(repoPath)' - - - ${{ if not(contains(variables['SYSTEM.COLLECTIONURI'],'mscodehub')) }}: - - pwsh: | - Import-module ./build.psm1 - $path = Join-Path -Path $pwd -ChildPath './commonTestResults.xml' - $results = invoke-pester -Script ./test/common/markdown-lint -OutputFile $path -OutputFormat NUnitXml -PassThru - Write-Host "##vso[results.publish type=NUnit;mergeResults=true;runTitle=Markdown Lint;publishRunAttachments=true;resultFiles=$path;]" - if($results.TotalCount -eq 0 -or $results.FailedCount -gt 0) - { - throw "Markdown tests failed" - } - displayName: Run Markdown Lint Tests - condition: succeededOrFailed() - workingDirectory: '$(repoPath)' - - - template: dailyBuildCompliance.yml@ComplianceRepo - parameters: - sourceScanPath: '$(repoPath)/test/common' From 8d4ab576b61c5c8066c7d4e8b8857ef48c627f67 Mon Sep 17 00:00:00 2001 From: Travis Plunk Date: Fri, 14 Jul 2023 10:47:59 -0700 Subject: [PATCH 03/10] Delete markdown.yml --- .vsts-ci/misc-analysis/markdown.yml | 57 ----------------------------- 1 file changed, 57 deletions(-) delete mode 100644 .vsts-ci/misc-analysis/markdown.yml diff --git a/.vsts-ci/misc-analysis/markdown.yml b/.vsts-ci/misc-analysis/markdown.yml deleted file mode 100644 index b63e817ef35..00000000000 --- a/.vsts-ci/misc-analysis/markdown.yml +++ /dev/null @@ -1,57 +0,0 @@ -parameters: - - name: matrix - - name: dependsOn - -jobs: -- job: markdown - strategy: - matrix: ${{ parameters.matrix }} - maxParallel: 5 - - displayName: Markdown Link Verification - - dependsOn: ${{ parameters.dependsOn }} - - pool: - vmImage: ubuntu-20.04 - - variables: - - name: repoPath - value: $(Agent.BuildDirectory)/$(repoFolder) - - name: YARN_CACHE_FOLDER - value: $(Pipeline.Workspace)/.yarn - - name: YARN_GLOBAL_CACHE_FOLDER - value: $(Pipeline.Workspace)/.yarn-global - - steps: - - checkout: self - clean: true - path: $(repoFolder) - - - checkout: ComplianceRepo - - - powershell: | - Install-module Pester -Scope CurrentUser -Force -MaximumVersion 4.99 - displayName: Install Pester - - - bash: | - curl -o- --progress-bar -L https://yarnpkg.com/install.sh | bash - displayName: Bootstrap Yarn - - - bash: | - yarn config set global-folder "$(YARN_GLOBAL_CACHE_FOLDER)" - displayName: Set Yarn global cache folder - - - ${{ if not(contains(variables['SYSTEM.COLLECTIONURI'],'mscodehub')) }}: - - pwsh: | - Import-module ./build.psm1 - $path = Join-Path -Path $pwd -ChildPath './commonTestResults.xml' - $results = invoke-pester -Script ./test/common/markdown-link -OutputFile $path -OutputFormat NUnitXml -PassThru - Write-Host "##vso[results.publish type=NUnit;mergeResults=true;runTitle=Markdown Link;publishRunAttachments=true;resultFiles=$path;]" - if($results.TotalCount -eq 0 -or $results.FailedCount -gt 0) - { - throw "Markdown tests failed" - } - displayName: Run Markdown Link Tests - condition: succeededOrFailed() - workingDirectory: '$(repoPath)' From 27e5399b4d3fff9ad828c005434aff522da3429f Mon Sep 17 00:00:00 2001 From: Travis Plunk Date: Mon, 17 Jul 2023 09:57:58 -0700 Subject: [PATCH 04/10] Update CONTRIBUTING.md --- .github/CONTRIBUTING.md | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index ce87c469d22..453524251a2 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -76,19 +76,18 @@ made. #### Spellchecking documentation Documentation is spellchecked. We use the -[markdown-spellcheck](https://github.com/lukeapage/node-markdown-spellcheck) command line tool, -which can be run in interactive mode to correct typos or add words to the ignore list -(`.spelling` at the repository root). +[textlint](https://github.com/textlint/textlint/wiki/Collection-of-textlint-rule) command line tool, +which can be run in interactive mode to correct typos. To run the spellchecker, follow these steps: * install [Node.js](https://nodejs.org/en/) (v10 or up) -* install [markdown-spellcheck](https://github.com/lukeapage/node-markdown-spellcheck) by - `npm install -g markdown-spellcheck` (v0.11.0 or up) -* run `mdspell "**/*.md" "!**/dotnet-tools/**/*.md" --ignore-numbers --ignore-acronyms --en-us`. - - The folder `dotnet-tools` is excluded because files in that folder are copied from the `dotnet/performance` repository - and will need to be synchronized from time to time. -* if the `.spelling` file is updated, commit and push it +* install [textlint](https://github.com/textlint/textlint/wiki/Collection-of-textlint-rule) by + `npm install -g textlint textlint-rule-terminology` +* run `textlint --rule terminology `, + adding `--fix` will accept all the recommendations. + +If you need to add a term or disable checking part of a file see the [configuration sections of the rule](https://github.com/sapegin/textlint-rule-terminology). #### Checking links in documentation From 7cf57d97fe880637965067d1b2234f7acba07fbc Mon Sep 17 00:00:00 2001 From: Travis Plunk Date: Mon, 17 Jul 2023 10:21:30 -0700 Subject: [PATCH 05/10] repo issues --- .github/CONTRIBUTING.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 453524251a2..b3cbf8ee014 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -52,7 +52,7 @@ if you don't have it - `Install-Module PlatyPS`. 1. Clone the [`MicrosoftDocs/PowerShell-Docs`](https://github.com/MicrosoftDocs/PowerShell-Docs) -repo if you don't already have it. +repository if you don't already have it. 1. Start your local build of PowerShell (with the change to the cmdlet you made). 1. Find the cmdlet's markdown file in PowerShell Docs - usually under @@ -62,7 +62,7 @@ repo if you don't already have it. `Update-MarkdownHelp -Path ` which will update the documentation for you. 1. Make any additional changes needed for the cmdlet to be properly documented. -1. Send a Pull Request to the PowerShell Docs repo with the changes that +1. Send a Pull Request to the PowerShell Docs repository with the changes that `PlatyPS` made. 1. Link your Docs PR to your original change PR. @@ -71,7 +71,7 @@ made. * When writing Markdown documentation, use [semantic linefeeds][]. In most cases, it means "one clause/idea per line". -* Otherwise, these issues should be treated like any other issue in this repo. +* Otherwise, these issues should be treated like any other issue in this repository. #### Spellchecking documentation From dec8ca7373527c07ec61cdc6dca8107065fd7483 Mon Sep 17 00:00:00 2001 From: Travis Plunk Date: Mon, 17 Jul 2023 10:22:56 -0700 Subject: [PATCH 06/10] markdown term fixes --- .github/CONTRIBUTING.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index b3cbf8ee014..73bc1d7110e 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -55,11 +55,11 @@ if you don't have it - repository if you don't already have it. 1. Start your local build of PowerShell (with the change to the cmdlet you made). -1. Find the cmdlet's markdown file in PowerShell Docs - usually under +1. Find the cmdlet's Markdown file in PowerShell Docs - usually under `PowerShell-Docs/reference///.md` (Ex. `PowerShell-Docs/reference/7/Microsoft.PowerShell.Utility/Select-String.md`) 1. Run -`Update-MarkdownHelp -Path ` +`Update-MarkdownHelp -Path ` which will update the documentation for you. 1. Make any additional changes needed for the cmdlet to be properly documented. 1. Send a Pull Request to the PowerShell Docs repository with the changes that @@ -92,13 +92,13 @@ If you need to add a term or disable checking part of a file see the [configurat #### Checking links in documentation Documentation is link-checked. We make use of the -markdown-link-check command line tool, +`markdown-link-check` command line tool, which can be run to see if any links are dead. To run the link-checker, follow these steps: * install [Node.js](https://nodejs.org/en/) (v10 or up) -* install markdown-link-check by +* install `markdown-link-check` by `npm install -g markdown-link-check@3.8.5` * run `find . \*.md -exec markdown-link-check {} \;` @@ -234,7 +234,7 @@ Additional references: * After submitting your pull request, our [CI system (Azure DevOps Pipelines)][ci-system] will run a suite of tests and automatically update the status of the pull request. -* Our CI contains automated spellchecking and link checking for markdown files. If there is any false-positive, +* Our CI contains automated spellchecking and link checking for Markdown files. If there is any false-positive, [run the spellchecker command line tool in interactive mode](#spellchecking-documentation) to add words to the `.spelling` file. * Our packaging test may not pass and ask you to update `files.wxs` file if you add/remove/update nuget package references or add/remove assert files. From 2ebb8b8a13544078db95c97b1092b2bada0e57d9 Mon Sep 17 00:00:00 2001 From: Travis Plunk Date: Mon, 17 Jul 2023 10:23:48 -0700 Subject: [PATCH 07/10] command-line term --- .github/CONTRIBUTING.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 73bc1d7110e..ed7637a4e67 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -76,7 +76,7 @@ made. #### Spellchecking documentation Documentation is spellchecked. We use the -[textlint](https://github.com/textlint/textlint/wiki/Collection-of-textlint-rule) command line tool, +[textlint](https://github.com/textlint/textlint/wiki/Collection-of-textlint-rule) command-line tool, which can be run in interactive mode to correct typos. To run the spellchecker, follow these steps: @@ -92,7 +92,7 @@ If you need to add a term or disable checking part of a file see the [configurat #### Checking links in documentation Documentation is link-checked. We make use of the -`markdown-link-check` command line tool, +`markdown-link-check` command-line tool, which can be run to see if any links are dead. To run the link-checker, follow these steps: @@ -235,7 +235,7 @@ Additional references: our [CI system (Azure DevOps Pipelines)][ci-system] will run a suite of tests and automatically update the status of the pull request. * Our CI contains automated spellchecking and link checking for Markdown files. If there is any false-positive, - [run the spellchecker command line tool in interactive mode](#spellchecking-documentation) + [run the spellchecker command-line tool in interactive mode](#spellchecking-documentation) to add words to the `.spelling` file. * Our packaging test may not pass and ask you to update `files.wxs` file if you add/remove/update nuget package references or add/remove assert files. From 1a05b5257e7e2a2c3df3e1f20e35a98fdb53a7ff Mon Sep 17 00:00:00 2001 From: Travis Plunk Date: Mon, 17 Jul 2023 10:26:17 -0700 Subject: [PATCH 08/10] fix syntax issues --- .github/CONTRIBUTING.md | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index ed7637a4e67..59fad36647b 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -12,8 +12,8 @@ Please read the rest of this document to ensure a smooth contribution process. * Make sure you have a [GitHub account](https://github.com/signup/free). * Learning Git: - * GitHub Help: [Good Resources for Learning Git and GitHub][good-git-resources] - * [Git Basics](../docs/git/basics.md): install and getting started + * GitHub Help: [Good Resources for Learning Git and GitHub][good-git-resources] + * [Git Basics](../docs/git/basics.md): install and getting started * [GitHub Flow Guide](https://guides.github.com/introduction/flow/): step-by-step instructions of GitHub Flow @@ -176,14 +176,14 @@ Additional references: See [this][closing-via-message] for more details. * Please use the present tense and imperative mood when describing your changes: - * Instead of "Adding support for Windows Server 2012 R2", write "Add support for Windows Server 2012 R2". - * Instead of "Fixed for server connection issue", write "Fix server connection issue". + * Instead of "Adding support for Windows Server 2012 R2", write "Add support for Windows Server 2012 R2". + * Instead of "Fixed for server connection issue", write "Fix server connection issue". This form is akin to giving commands to the code base and is recommended by the Git SCM developers. It is also used in the [Git commit messages](#common-engineering-practices). * If the change is related to a specific resource, please prefix the description with the resource name: - * Instead of "New parameter 'ConnectionCredential' in New-SqlConnection", + * Instead of "New parameter 'ConnectionCredential' in New-SqlConnection", write "New-SqlConnection: add parameter 'ConnectionCredential'". * If your change warrants an update to user-facing documentation, a Maintainer will add the `Documentation Needed` label to your PR and add an issue to the [PowerShell-Docs repository][PowerShell-Docs], @@ -194,7 +194,7 @@ Additional references: (See [Contributing to documentation related to PowerShell](#contributing-to-documentation-related-to-powershell) for more info.) * If your change adds a new source file, ensure the appropriate copyright and license headers is on top. It is standard practice to have both a copyright and license notice for each source file. - * For `.h`, `.cpp`, and `.cs` files use the copyright header with empty line after it: + * For `.h`, `.cpp`, and `.cs` files use the copyright header with empty line after it: ```c# // Copyright (c) Microsoft Corporation. @@ -202,7 +202,7 @@ Additional references: ``` - * For `.ps1` and `.psm1` files use the copyright header with empty line after it: + * For `.ps1` and `.psm1` files use the copyright header with empty line after it: ```powershell # Copyright (c) Microsoft Corporation. @@ -279,7 +279,7 @@ Additional references: - `Approve` if you believe your feedback has been addressed or the code is fine as-is, it is customary (although not required) to leave a simple "Looks good to me" (or "LGTM") as the comment for approval. - `Comment` if you are making suggestions that the *author* does not have to accept. Early in the review, it is acceptable to provide feedback on coding formatting based on the published [Coding Guidelines][coding-guidelines], however, - after the PR has been approved, it is generally _not_ recommended to focus on formatting issues unless they go against the [Coding Guidelines][coding-guidelines]. + after the PR has been approved, it is generally *not* recommended to focus on formatting issues unless they go against the [Coding Guidelines][coding-guidelines]. Non-critical late feedback (after PR has been approved) can be submitted as a new issue or new pull request from the *reviewer*. 1. *Assignees* who are always *Maintainers* ensure that proper review has occurred and if they believe one approval is not sufficient, the *maintainer* is responsible to add more reviewers. An *assignee* may also be a reviewer, but the roles are distinct. @@ -388,11 +388,9 @@ The duration of the temporary ban will depend on the impact and/or severity of t This can vary from 1 day, a few days, a week, and up to 30 days. Repeat offenses may result in a permanent ban from the PowerShell org. -[testing-guidelines]: ../docs/testing-guidelines/testing-guidelines.md [running-tests-outside-of-ci]: ../docs/testing-guidelines/testing-guidelines.md#running-tests-outside-of-ci [issue-management]: ../docs/maintainers/issue-management.md [vuln-reporting]: ./SECURITY.md -[governance]: ../docs/community/governance.md [using-prs]: https://help.github.com/articles/using-pull-requests/ [fork-a-repo]: https://help.github.com/articles/fork-a-repo/ [closing-via-message]: https://help.github.com/articles/closing-issues-via-commit-messages/ From 7c9cddbd12037147c554e93d3a966717ba45e238 Mon Sep 17 00:00:00 2001 From: Travis Plunk Date: Mon, 17 Jul 2023 10:29:09 -0700 Subject: [PATCH 09/10] fix codebase term --- .github/CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 59fad36647b..2e43a299d24 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -179,7 +179,7 @@ Additional references: * Instead of "Adding support for Windows Server 2012 R2", write "Add support for Windows Server 2012 R2". * Instead of "Fixed for server connection issue", write "Fix server connection issue". - This form is akin to giving commands to the code base + This form is akin to giving commands to the codebase and is recommended by the Git SCM developers. It is also used in the [Git commit messages](#common-engineering-practices). * If the change is related to a specific resource, please prefix the description with the resource name: @@ -298,7 +298,7 @@ In these cases: - If the *reviewer*'s comments are very minor, merge the change, fix the code immediately, and create a new PR with the fixes addressing the minor comments. - If the changes required to merge the pull request are significant but needed, *assignee* creates a new branch with the changes and open an issue to merge the code into the dev branch. Mention the original pull request ID in the description of the new issue and close the abandoned pull request. - - If the changes in an abandoned pull request are no longer needed (e.g. due to refactoring of the code base or a design change), *assignee* will simply close the pull request. + - If the changes in an abandoned pull request are no longer needed (e.g. due to refactoring of the codebase or a design change), *assignee* will simply close the pull request. ## Making Breaking Changes From a7b05a89a3fe63e0f829569faf24bdf63b9e71a9 Mon Sep 17 00:00:00 2001 From: Travis Plunk Date: Mon, 17 Jul 2023 10:32:02 -0700 Subject: [PATCH 10/10] Disable VALIDATE_EDITORCONFIG --- .github/workflows/markdownLink.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/markdownLink.yml b/.github/workflows/markdownLink.yml index ac1be6eba8d..b7df90232f6 100644 --- a/.github/workflows/markdownLink.yml +++ b/.github/workflows/markdownLink.yml @@ -38,4 +38,4 @@ jobs: DEFAULT_BRANCH: master FILTER_REGEX_INCLUDE: .*\.md GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - + VALIDATE_EDITORCONFIG: false