Update documentation and maintenance docs (#30)

* Update Documentation and Add Markdown Lint Workflow - Added a GitHub Actions workflow for Markdown linting to ensure consistent formatting and style in markdown files. - Updated general documentation and maintenance docs for better clarity and completeness. - Fix spelling issues markdown files - Minor bug fixes and improvements Signed-off-by: Christine Murimi <[email protected]>
microsoft · Aug 13, 2024 · aeaf32e · aeaf32e
1 parent 68e6958
commit aeaf32e
Show file tree

Hide file tree

Showing 15 changed files with 638 additions and 132 deletions.
diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS
@@ -0,0 +1,14 @@
+# <https://help.github.com/articles/about-codeowners/>
+
+# Area: Documentation
+docs/   @tinamor
+
+# Area: Test
+*.Tests.ps1        @tinamor
+
+
+# Tools
+containers-toolkit//Public/BuildkitTools.psm1             @profnandaa @billywr @danielGithinji
+containers-toolkit/Public/ontainerdTools.psm1             @charitykathure
+containers-toolkit/Public/ContainerNetworkTools.psm1      @iankingori
+containers-toolkit/Public/NerdctlTools.psm1               @tinamor
diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -1,38 +1,57 @@
 ---
 name: Bug report
-about: Create a report to help us improve
-title: ''
+about: Create a report to help improve Containers Toolkit PowerShell module
+title: "[BUG] [CTK v1.0.0] Summary of the issue"
 labels: ''
 assignees: ''
 
 ---
 
 **Describe the bug**
-A clear and concise description of what the bug is.
+
+Please file a single issue per bug instead of enumerating multiple items.
 
 **To Reproduce**
-Steps to reproduce the behavior:
-1. Go to '...'
-2. Click on '....'
-3. Scroll down to '....'
-4. See error
+
+Detailed steps to reproduce the behavior:
+1.
+2.
+3. ...
+
+The more information you can provide, the more likely someone will be successful at triaging and reproducing the issue and finding a fix.
 
 **Expected behavior**
+
+A clear and concise description of what you expected to happen.
+
+**Actual behavior**
+
 A clear and concise description of what you expected to happen.
 
 **Screenshots**
+
 If applicable, add screenshots to help explain your problem.
 
-**Desktop (please complete the following information):**
- - OS: [e.g. iOS]
- - Browser [e.g. chrome, safari]
- - Version [e.g. 22]
+**System information**
+
+- Windows build and Version
+  - PowerShell
 
-**Smartphone (please complete the following information):**
- - Device: [e.g. iPhone6]
- - OS: [e.g. iOS8.1]
- - Browser [e.g. stock browser, safari]
- - Version [e.g. 22]
+    ```PowerShell
+    systeminfo | findstr /B /C:"OS Name" /C:"OS Version" /C:"System Type"
+    ```
+
+- PowerShell version
+- Package version for which the problem occurs
+- Container tool versions:
+  - Containerd
+  - Buildkit
+  - Nerdctl
+  - Win CNI plugin:
+    - Plugin: [Windows Container Networking CNI](https://github.com/microsoft/windows-container-networking) or [CNI network plugins](https://github.com/containernetworking/plugins)
+    - Version
+- For issues with extensions, the version of the IDE for which the problem occurs
 
 **Additional context**
+
 Add any other context about the problem here.
diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md
@@ -1,6 +1,6 @@
 ---
 name: Feature request
-about: Suggest an idea for this project
+about: Suggest an idea for Containers Toolkit PowerShell module
 title: ''
 labels: ''
 assignees: ''

diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
@@ -0,0 +1,39 @@
+## PR description
+
+### Github issue/ discussion ()
+
+_related Isuue/discussion(s)_
+
+### Background information
+
+_From the perspective of the reviewer, what context do they need to know to understand this PR?_
+
+### What does this PR do
+
+_What does this PR achieve/fix._
+
+### TODOs not included in this PR
+
+_What issues will/should be addressed in followup PRs. Link any of these issues if they exist_
+
+### Testing information
+
+_How to test the changes_
+
+### Relevant links ()
+
+_Any links from your research that will help explain the changes_
+
+## Checklist
+
+As part of our commitment to engineering excellence, **before** submitting this PR, please make sure:
+
+- [ ] You've tested this code in both Desktop & Server environments and AMD & ARM64 enviroments (**functional testing**).
+- [ ] You've added **unit tests** for new code.
+- [ ] You've added/updated documentation in the [cmdlet docs](../docs/About/), [command-reference.md](../docs/command-reference.md)  and the [modules help files](../containers-toolkit/en-US/containers-toolkit-help.xml).
+- [ ] You've reviewed the PR/code best practices defined in the [CONTRIBUTING.md](../CONTRIBUTING.md).
+
+In addition, **after** this PR has been reviewed, please agree to:
+
+- [ ] If changes have been made to your PR in the process of addressing comments, please make sure to test again the _final_ version in both AMD and ARM64 environments.
+- [ ] Validate your changes have not introduced any regressions.
diff --git a/.github/workflows/markdown-lint.yml b/.github/workflows/markdown-lint.yml
@@ -0,0 +1,81 @@
+###########################################################################
+#                                                                         #
+#   Copyright (c) Microsoft Corporation. All rights reserved.             #
+#                                                                         #
+#   This code is licensed under the MIT License (MIT).                    #
+#                                                                         #
+###########################################################################
+
+name: Markdown Lint
+
+on:
+  pull_request:
+    branches:
+      - main
+      - "releases/**"
+    paths:
+      - "docs/**"
+      - "README.md"
+      - en-US/**"
+
+permissions:
+  contents: read
+
+jobs:
+  markdown-check:
+    runs-on: windows-latest
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install npm dependencies
+        run: npm install -g markdown-link-check textlint textlint-rule-spelling dictionary-en textlint-filter-rule-comments
+
+      - name: Markdown link check
+        shell: pwsh
+        run: |
+          # Check all markdown files in the repository
+          $mlc_error_file = "link-errors.txt"
+          Remove-Item -Path $mlc_error_file -Recurse -Force -ErrorAction SilentlyContinue
+          Get-ChildItem -Path "README.md", ".\docs\" -Filter "*.md" -Recurse | `
+              ForEach-Object { & markdown-link-check $_.FullName -q 2>>$mlc_error_file }
+
+          # Check if the error file exists
+          if (-not (Test-Path "$mlc_error_file")) {
+              return
+          }
+
+          # Check if the error file file contains errors
+          if (Select-String -Path "$mlc_error_file" -Pattern "ERROR: ") {
+              $errormsg = "Broken links found. Please check the output for more information."
+              $Link_Check_Summary = ":x: [Markdown Link Check] $errormsg"
+              echo $Link_Check_Summary >> $env:GITHUB_STEP_SUMMARY
+              throw $errormsg
+          }
+          else {
+              $Link_Check_Summary = ":white_check_mark: [Markdown Link Check] All links are valid."
+              echo $Link_Check_Summary >> $env:GITHUB_STEP_SUMMARY
+          }
+
+      - name: Markdown spell check
+        shell: pwsh
+        run: |
+          # Run spell check on all markdown files in the repository
+          $sc_error_file = "sc-errors.txt"
+          Remove-Item -Path $sc_error_file -Recurse -Force -ErrorAction SilentlyContinue
+          npx textlint README.md docs/**/*.md >>$sc_error_file
+
+          # Check if the error file exists
+          if (-not (Test-Path "$sc_error_file")) {
+              return
+          }
+
+          # Check if the error file file contains errors. If the file is empty, it means no errors were found.
+          if ([string]::IsNullOrWhiteSpace((Get-Content -Path $sc_error_file))) {
+              $Spell_Check_Summary = ":white_check_mark: [Markdown Spell Check] No spelling errors found."
+          }
+          else {
+              $Spell_Check_Summary = ":x: [Markdown Spell Check] Spelling errors found. Please check the output for more information."
+              cat $sc_error_file
+          }
+          echo $Spell_Check_Summary >> $env:GITHUB_STEP_SUMMARY
diff --git a/.textlintrc.json b/.textlintrc.json
@@ -1,35 +1,54 @@
 {
-    "rules": {
-        "spelling": {
-            "language": "en",
-            "skipPatterns": [
-                "/[0-9]+/g", // numbers
-                "/\\bhttp(s)?:\\/\\/[^\\s)>]+/", // URL
-                // "/\\b[a-z\\d]{7,40}\\b/", // commit hash
-                "/\\([^)]+?\\)/", // inside parentheses
-                // // '/"[^"]+?"/', // inside quotation marks
-                // // "/`[^`]+?`/", // inside backticks
-                "/\\b(?:[A-Z]){2,}\\b/g", // acronyms
-                "/\\b(?:[a-zA-Z]+-[a-zA-Z]+)\\b/g", // hyphenated words/ function names
-                // "/\b\\S*\\.\\S{2,4}/g", // filenames
-                "/\\$[\\w]+(:\\w)?/g", // PowerShell variables
-                "/-\\w+\\b/g", // FIXME: PowerShell Cmdlets/function parameter names
-                "/\\b\\w+[./]\\w+\\b/g", // paths // FIXME: Does not work for \ in paths
-                "containers-toolkit",
-                "PowerShell",
-                "/Cmdlets/i",
-                "Containerd",
-                "BuildKit",
-                "buildkitd",
-                "nerdctl",
-                "WinCNIPlugin",
-                "NatNetwork",
-                "/nat/i",
-                "cni",
-                "HNS",
-                "CIDR",
-                "subnet"
-            ]
-        }
+  "plugins": {},
+  "filters": {
+    "comments": true
+  },
+  "rules": {
+    "spelling": {
+      "language": "en",
+      "skipPatterns": [
+        "/[0-9]+/g", // numbers
+        "/\\bhttp(s)?:\\/\\/[^\\s)>]+/", // URL
+        // "/\\b[a-z\\d]{7,40}\\b/",     // commit hash
+        "/\\([^)]+?\\)/", // inside parentheses
+        // "/\"[^\"]+?\"/",              // inside quotation marks
+        // "/`[^`]+?`/",                 // inside backticks
+        "/\\b(?:[A-Z]){2,}\\b/g", // acronyms
+        "/\\b(?:[a-zA-Z]+-[a-zA-Z]+)\\b/g", // hyphenated words/ function names
+        // "/\\b\\S*\\.\\S{2,4}/g",      // filenames
+        "/\\$[\\w]+(:\\w)?/g", // PowerShell variables
+        "/-\\w+\\b/g", // FIXME: PowerShell Cmdlets/function parameter names
+        "/\\b\\w+[./]\\w+\\b/g", // paths //  FIXME: (Note: Does not work for \ in paths)
+        "about_Preference_Variables",
+        "CIDR",
+        "Containers[\\s\\.\\-]ToolKit/gi",
+        "/Cmdlet/gi",
+        "cni",
+        "/Containerd/gi",
+        "/BuildKit/gi",
+        "/buildkitd/gi",
+        "/H(ost)?N(etworking)?S(ervice)?/g",
+        "/Hyper[\\s-]?V/g",
+        "/moby/gi",
+        "/nat/gi",
+        "NatNetwork",
+        "nerdctl",
+        "PowerShell",
+        "/PSCustomObject/gi",
+        "subnet",
+        "ThreadJob",
+        "/unregisters/gi",
+        "WinCNIPlugin",
+        // Parameter names
+        "DownloadPath",
+        "InstallPath",
+        "LatestVersion",
+        "NetworkName",
+        "RegisterServices",
+        "WhatIf",
+        "WinCNIPath",
+        "WinCNIVersion"
+      ]
     }
+  }
 }
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,3 @@
+## 1.0.0
+
+* Initial release