From 1c721fa05acb79b36de3c03123d73ea02693a1c8 Mon Sep 17 00:00:00 2001 From: Tess Ferrandez Date: Mon, 12 Jun 2023 14:37:31 +0200 Subject: [PATCH] Remove broken link per #955 (#972) * remove link from excluded * add markdownlint json to ignore 400 lines * fix markdown lint issues * fix spelling errors * fix spelling and markdown linting * ignore plantuml links * ignore plantuml links * ignore github links --------- Co-authored-by: Tess Ferrandez Co-authored-by: Shiran Rubin --- .cspell.json | 1 + .markdown-link-check.json | 5 +-- .markdownlint.json | 14 ++++++++ .markdownlint.yaml | 29 ----------------- .../fault-injection-testing/README.md | 2 +- .../terraform-structure-guidelines.md | 14 ++++---- docs/developer-experience/copilots.md | 32 +++++++++---------- linkcheck.json | 1 - 8 files changed, 42 insertions(+), 56 deletions(-) create mode 100644 .markdownlint.json delete mode 100644 .markdownlint.yaml diff --git a/.cspell.json b/.cspell.json index 79be67ff79..a3f26df1f8 100644 --- a/.cspell.json +++ b/.cspell.json @@ -255,6 +255,7 @@ "Mitigations", "mkdir", "mkdocs", + "mlops", "msrc", "MSRC", "MTTR", diff --git a/.markdown-link-check.json b/.markdown-link-check.json index 98068b22e2..cdcc8089f6 100644 --- a/.markdown-link-check.json +++ b/.markdown-link-check.json @@ -14,7 +14,7 @@ {"pattern": "^https://gitlab.com/palisade/palisade-release"}, {"pattern": "(.*\\.)?.opentelemetry.io"}, {"pattern": "(.*\\.)?.pluralsight.com"}, - {"pattern": "(.*\\.)?.github.com"}, + {"pattern": "^https://www.github.com"}, {"pattern": "^https://marketplace.visualstudio.com"}, {"pattern": "^https://opensource.org/licenses/MIT"}, {"pattern": "^https://www.researchgate.net/publication/301839557_The_landscape_of_software_failure_cause_models"}, @@ -24,7 +24,8 @@ {"pattern": "^https://www.ranorex.com/free-trial/"}, {"pattern": "^https://argo-cd.readthedocs.io/"}, {"pattern": "^http://pytest.org/"}, - {"pattern": "^http://code.visualstudio.com/"} + {"pattern": "^http://code.visualstudio.com/"}, + {"pattern": "^https://plantuml.com/"} ], "httpHeaders": [ { diff --git a/.markdownlint.json b/.markdownlint.json new file mode 100644 index 0000000000..d441748970 --- /dev/null +++ b/.markdownlint.json @@ -0,0 +1,14 @@ +{ + "MD004": false, + "MD007": { + "indent": 2 + }, + "MD013": false, + "MD026": { + "punctuation": ".,;:!。，；:" + }, + "MD029": false, + "MD033": false, + "MD036": false, + "blank_lines": false +} \ No newline at end of file diff --git a/.markdownlint.yaml b/.markdownlint.yaml deleted file mode 100644 index 3333a6b1a5..0000000000 --- a/.markdownlint.yaml +++ /dev/null @@ -1,29 +0,0 @@ -# MD004 - Unordered list style -ul-style: false - -# MD007 - Unordered list indentation -ul-indent: - indent: 2 - -# MD013 - Line length -line-length: false - -# MD026 - Trailing punctuation in header -no-trailing-punctuation: - punctuation: ".,;:!。，；:" - -# MD029 - Ordered list item prefix -ol-prefix: false - -# MD033 - Inline HTML -no-inline-html: false - -# MD036 - Emphasis used instead of a header -no-emphasis-as-header: false - -# MD012 - Multiple consecutive blank lines -# MD022 - Headers should be surrounded by blank lines -# MD031 - Fenced code blocks should be surrounded by blank lines -# MD032 - Lists should be surrounded by blank lines -# MD047 - File should end with a single newline character -blank_lines: false diff --git a/docs/automated-testing/fault-injection-testing/README.md b/docs/automated-testing/fault-injection-testing/README.md index 853971d4dd..3edf15e2fd 100644 --- a/docs/automated-testing/fault-injection-testing/README.md +++ b/docs/automated-testing/fault-injection-testing/README.md @@ -66,7 +66,7 @@ Fault injection tests rely on metrics observability and are usually statistical; * Document the process and the observations. * Identify and act on the result. -#### Fault injection testing in kubernetes +#### Fault injection testing in kubernetes With the advancement of kubernetes (k8s) as the infrastructure platform, fault injection testing in kubernetes has become inevitable to ensure that system behaves in a reliable manner in the event of a fault or failure. There could be different type of workloads running within a k8s cluster which are written in different languages. For eg. within a K8s cluster, you can run a micro service, a web app and/or a scheduled job. Hence you need to have mechanism to inject fault into any kind of workloads running within the cluster. In addition, kubernetes clusters are managed differently from traditional infrastructure. The tools used for fault injection testing within kubernetes should have compatibility with k8s infrastructure. These are the main characteristics which are required: diff --git a/docs/continuous-delivery/recipes/terraform/terraform-structure-guidelines.md b/docs/continuous-delivery/recipes/terraform/terraform-structure-guidelines.md index 42283596b8..8120c64de9 100644 --- a/docs/continuous-delivery/recipes/terraform/terraform-structure-guidelines.md +++ b/docs/continuous-delivery/recipes/terraform/terraform-structure-guidelines.md @@ -14,13 +14,13 @@ The recommended structure is as follows: - **provider.tf**: defines the list of providers according to the plugins used - **data.tf**: defines information read from different data sources - **main.tf**: defines the infrastructure objects needed for your configuration (e.g. resource group, role assignment, container registry) - - **backend.tf**: backend configuration file + - **backend.tf**: backend configuration file - **outputs.tf**: defines structured data that is exported - **variables.tf**: defines static, reusable values -4. Include in each module subfolders for documentation, examples and tests. -The documentation includes basic information about the module: what is it installing, what are the options, an example use case and so on. You can also add here any other relevant details you might have. -The example folder can include one or more examples of how to use the module, each example having the same set of configuration files decided on the previous step. It's recommended to also include a README providing a clear understanding of how it can be used in practice. -The tests folder includes one or more files to test the example module together with a documentation file with instructions on how these tests can be [executed](https://www.hashicorp.com/blog/testing-hashicorp-terraform). +4. Include in each module sub folders for documentation, examples and tests. +The documentation includes basic information about the module: what is it installing, what are the options, an example use case and so on. You can also add here any other relevant details you might have. +The example folder can include one or more examples of how to use the module, each example having the same set of configuration files decided on the previous step. It's recommended to also include a README providing a clear understanding of how it can be used in practice. +The tests folder includes one or more files to test the example module together with a documentation file with instructions on how these tests can be [executed](https://www.hashicorp.com/blog/testing-hashicorp-terraform). 5. Place the root module in a separate folder called `main`: this is the primary entry point for the configuration. Like for the other modules, it will contain its corresponding configuration files. An example configuration structure obtained using the guidelines above is: @@ -45,8 +45,8 @@ modules ## Naming convention -When naming Terraform variables, it's essential to use clear and consistent naming conventions that are easy to understand and follow. The general convention is to use lowercase letters and numbers, with underscores instead of dashes, for example: "azurerm_resource_group". -When naming resources, start with the provider's name, followed by the target resource, separated by underscores. For instance, "azurerm_postgresql_server" is an appropriate name for an Azure provider resource. When it comes to data sources, use a similar naming convention, but make sure to use plural names for lists of items. For example, "azurerm_resource_groups" is a good name for a data source that represents a list of resource groups. +When naming Terraform variables, it's essential to use clear and consistent naming conventions that are easy to understand and follow. The general convention is to use lowercase letters and numbers, with underscores instead of dashes, for example: "azurerm_resource_group". +When naming resources, start with the provider's name, followed by the target resource, separated by underscores. For instance, "azurerm_postgresql_server" is an appropriate name for an Azure provider resource. When it comes to data sources, use a similar naming convention, but make sure to use plural names for lists of items. For example, "azurerm_resource_groups" is a good name for a data source that represents a list of resource groups. Variable and output names should be descriptive and reflect the purpose or use of the variable. It's also helpful to group related items together using a common prefix. For example, all variables related to storage accounts could start with "storage_". Keep in mind that outputs should be understandable outside of their scope. A useful naming pattern to follow is "{name}_{attribute}", where "name" represents a resource or data source name, and "attribute" is the attribute returned by the output. For example, "storage_primary_connection_string" could be a valid output name. Make sure you include a description for outputs and variables, as well as marking the values as 'default' or 'sensitive' when the case. This information will be captured in the generated documentation. diff --git a/docs/developer-experience/copilots.md b/docs/developer-experience/copilots.md index dd253e3e63..568d5b6a74 100644 --- a/docs/developer-experience/copilots.md +++ b/docs/developer-experience/copilots.md @@ -8,11 +8,11 @@ The current version of GitHub Copilot can provide code completion in many popula Some example use-cases for GitHub Copilot include: -- __Write Documentation__. For example, the above paragraph was written using Copilot. +- **Write Documentation**. For example, the above paragraph was written using Copilot. -- __Write Unit Tests__. Given that setup and assertions are often consistent across unit tests, Copilot tends to be very accurate. +- **Write Unit Tests**. Given that setup and assertions are often consistent across unit tests, Copilot tends to be very accurate. -- __Unblock__. It is often hard start writing when staring at a blank page, Copilot can fill the space with something that may or may not be what you ultimately want to do, but it can help get you in the right headspace. +- **Unblock**. It is often hard start writing when staring at a blank page, Copilot can fill the space with something that may or may not be what you ultimately want to do, but it can help get you in the right head space. If you want Copilot to write something useful for you, try writing a comment that describes what your code is going to do - it can often take it from there. @@ -20,31 +20,31 @@ If you want Copilot to write something useful for you, try writing a comment tha Copilot has a [GitHub Copilot Labs extension](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot-labs) that offers additional features that are not yet ready for prime-time. For VS Code, you can install it from the VS Code Marketplace. These features include: -- __Explain__. Copilot can explain what the code is doing in natural language. +- **Explain**. Copilot can explain what the code is doing in natural language. -- __Translate__. Copilot can translate code from one language to another. +- **Translate**. Copilot can translate code from one language to another. -- __Brushes__. You can select code that Copilot then modifies inline based on a "brush" you select, for example, to make the code more readable, fix bugs, improve debugging, document, etc. +- **Brushes**. You can select code that Copilot then modifies inline based on a "brush" you select, for example, to make the code more readable, fix bugs, improve debugging, document, etc. -- __Generate Tests__. Copilot can generate unit tests for your code. Though currently this is limited to JavaScript and TypeScript. +- **Generate Tests**. Copilot can generate unit tests for your code. Though currently this is limited to JavaScript and TypeScript. ## GitHub Copilot X The next version of Copilot offers a number of new use-cases beyond code completion. These include: -- __Chat__. Rather than just providing code completion, Copilot will be able to have a conversation with you about what you want to do. It has context about the code you are working on and can provide suggestions based on that context. Beyond just writing code, consider using chat to: +- **Chat**. Rather than just providing code completion, Copilot will be able to have a conversation with you about what you want to do. It has context about the code you are working on and can provide suggestions based on that context. Beyond just writing code, consider using chat to: - - __Build SQL Indexes__. Given a query, ChatGPT can generate a SQL index that will improve the performance of the query. + - **Build SQL Indexes**. Given a query, ChatGPT can generate a SQL index that will improve the performance of the query. - - __Write Regular Expressions__. These are notoriously difficult to write, but ChatGPT can generate them for you if you give some sample input and describe what you want to extract. + - **Write Regular Expressions**. These are notoriously difficult to write, but ChatGPT can generate them for you if you give some sample input and describe what you want to extract. - - __Improve and Validate__. If you are unsure of the implications of writing code a particular way, you can ask questions about it. For instance, you might ask if there is a way to write the code that is more performant or uses less memory. Once it gives you an opinion, you can ask it to provide documentation validating that assertion. + - **Improve and Validate**. If you are unsure of the implications of writing code a particular way, you can ask questions about it. For instance, you might ask if there is a way to write the code that is more performant or uses less memory. Once it gives you an opinion, you can ask it to provide documentation validating that assertion. -- __Explain__. Copilot can explain what the code is doing in natural language. +- **Explain**. Copilot can explain what the code is doing in natural language. -- __Write Code__. Given prompting by the developer it can write code that you can one-click deploy into existing or new files. +- **Write Code**. Given prompting by the developer it can write code that you can one-click deploy into existing or new files. -- __Debug__. Copilot can analyze your code and propose solutions to fix bugs. +- **Debug**. Copilot can analyze your code and propose solutions to fix bugs. It can do most of what Labs can do with "brushes" as "topics", but whereas Labs changes the code in your file, the chat functionality just shows what it would change in the window. However, there is also an "inline mode" for GitHub Copilot Chat that allows you to make changes to your code inline which does not have this same limitation. @@ -52,9 +52,9 @@ It can do most of what Labs can do with "brushes" as "topics", but whereas Labs For coding, generic AI chat tools such as ChatGPT and Bing Chat are less useful, but they still have their place. GitHub Copilot will only answer "questions about coding" and it's interpretation of that rule can be a little restrictive. Some cases for using ChatGPT or Bing Chat include: -- __Write Documentation__. Copilot can write documentation, but using ChatGPT or Bing Chat, you can expand your documentation to include business information, use-cases, additional context, etc. +- **Write Documentation**. Copilot can write documentation, but using ChatGPT or Bing Chat, you can expand your documentation to include business information, use-cases, additional context, etc. -- __Change Perspective__. ChatGPT can impersonate a persona or even a system and answer questions from that perspective. For example, you can ask it to explain what a particular piece of code does from the perspective of a user. You might have ChatGPT imagine it is a database adminstrator and ask it to explain how to improve a particular query. +- **Change Perspective**. ChatGPT can impersonate a persona or even a system and answer questions from that perspective. For example, you can ask it to explain what a particular piece of code does from the perspective of a user. You might have ChatGPT imagine it is a database administrator and ask it to explain how to improve a particular query. When using Bing Chat, experiment with modes, sometimes changing to Creative Mode can give the results you need. diff --git a/linkcheck.json b/linkcheck.json index b1ef9595b4..0703bdb63d 100644 --- a/linkcheck.json +++ b/linkcheck.json @@ -40,7 +40,6 @@ "https://www.inverse.com/innovation/how-companies-have-optimized-the-humble-office-water-cooler", "https://www.inverse.com/", "https://www.dynatrace.com/platform/synthetic-monitoring/", - "https://miro.com/guides/retrospectives/ideas-games", "https://interpret.ml/" ], "only_errors": true