From 98ecce18af58ed1edbd02fd803603d0a98e9fe01 Mon Sep 17 00:00:00 2001 From: mmitoraj Date: Fri, 4 Oct 2024 22:04:20 +0200 Subject: [PATCH 1/2] Update repository guidelines and style and terminology --- .../content-guidelines/02-style-and-terminology.md | 1 + .../01-new-repository-settings.md | 11 +++++++++++ .../repository-guidelines/02-repository-template.md | 6 ++++-- 3 files changed, 16 insertions(+), 2 deletions(-) diff --git a/docs/guidelines/content-guidelines/02-style-and-terminology.md b/docs/guidelines/content-guidelines/02-style-and-terminology.md index 5eaedc34a..7d9e07d21 100644 --- a/docs/guidelines/content-guidelines/02-style-and-terminology.md +++ b/docs/guidelines/content-guidelines/02-style-and-terminology.md @@ -194,6 +194,7 @@ Here is the preferred terminology to use in the Kyma documentation: | **application** | **app** | Use "Application" to describe an external solution connected to Kyma through Application Connector, "application" to describe a microservice deployed on Kyma or other kind of software. | | **the following** | **below**, **this**, **the described**, ... | or "as shown in the example" | | **the previous**, **earlier** | **above**, **this**, **the described**, ... | or "as shown in the example" | +| **Infrastructure Provider** **IaaS Provider** | **hyperscaler**, **Cloud Provider** | | ### Command Line Arguments diff --git a/docs/guidelines/repository-guidelines/01-new-repository-settings.md b/docs/guidelines/repository-guidelines/01-new-repository-settings.md index 339593b5a..09823329b 100644 --- a/docs/guidelines/repository-guidelines/01-new-repository-settings.md +++ b/docs/guidelines/repository-guidelines/01-new-repository-settings.md @@ -55,6 +55,8 @@ The `/kyma-project` repositories in GitHub use [md-check-link](https://github.co ### Configuration +#### Repository Config + To configure the md-check-link in your repository, choose your CI/CD pipeline for the check and set up its workflow. For example, choose GitHub Action and add a configuration YAML file to the `/.github/workflows` directory. Paste the following content: ```yaml @@ -86,6 +88,15 @@ jobs: With that configuration, the md-check-link verifies all `.md` files in your repository on every PR. +#### Central Config + +All Kyma modules' repositories that store user-facing documentation are included in the central configuration of [md-check-link](https://github.com/kyma-project/md-check-link). It allows Technical Writers to use a nightly GitHub Actions workflow, called [Verify markdown links in Kyma project](https://github.com/kyma-project/md-check-link/actions/workflows/check-kyma-links.yml), that detects broken links in all `.md` files of the listed repositories. + +If you create a new module repository, you must add it to the following files: + +* [`md-check-link/.github/workflows/check-kyma-links.yml`](https://github.com/kyma-project/md-check-link/blob/main/.github/workflows/check-kyma-links.yml) +* [`md-check-link/.mlc.config.json`](https://github.com/kyma-project/md-check-link/blob/main/.mlc.config.json) + ## Custom Settings Track all repository changes that deviate from configuration standard described in the guidelines with an [issue](https://github.tools.sap/kyma/test-infra/issues/new?assignees=&labels=config-change&template=bug_report.md&title=). diff --git a/docs/guidelines/repository-guidelines/02-repository-template.md b/docs/guidelines/repository-guidelines/02-repository-template.md index 3dbd67291..e311d2b8e 100644 --- a/docs/guidelines/repository-guidelines/02-repository-template.md +++ b/docs/guidelines/repository-guidelines/02-repository-template.md @@ -15,14 +15,16 @@ The `template-repository` consists of: * [`.reuse`](https://github.com/kyma-project/template-repository/tree/main/.reuse) - This folder includes a file with the copyright and licensing disclaimer about SAP or third-party products or services developed outside the project. +* [`LICENSES`](https://github.com/kyma-project/template-repository/blob/main/LICENSE) - It is an obligatory element of every open-source repository. Copy the template into your repository. + * [`docs`](https://github.com/kyma-project/template-repository/tree/main/docs) - In this folder, put the repository-specific documentation only. Store any architectural decisions or documents applicable to all Kyma repositories in the `community` repository. * [`.mlc.config.json`](https://github.com/kyma-project/template-repository/blob/main/.mlc.config.json) - This file includes the Markdown link check configuration for the repository. The configuration is necessary to set up a CICD pipeline for the check. For example, use Markdown link check as a GitHub Action from the GitHub Marketplace. -* [`CODE_OF_CONDUCT.md`](https://github.com/kyma-project/template-repository/blob/main/CODE_OF_CONDUCT.md) - This document is a ready-to-use template which provides a link to the general `CODE_OF_CONDUCT.md` document from the `community` repository. - * [`CODEOWNERS`](https://github.com/kyma-project/template-repository/blob/main/CODEOWNERS) - In this document, specify the owners of particular parts of your repository. The owners are automatically added as reviewers when you open a pull request that modifies the code and content they own. +* [`CODE_OF_CONDUCT.md`](https://github.com/kyma-project/template-repository/blob/main/CODE_OF_CONDUCT.md) - This document is a ready-to-use template which provides a link to the general `CODE_OF_CONDUCT.md` document from the `community` repository. + * [`CONTRIBUTING.md`](https://github.com/kyma-project/template-repository/blob/main/CONTRIBUTING.md) - This template makes a reference to the [contributing rules](../../contributing/02-contributing.md) that contain the general guidance from the `community` repository and describes the rules for contributing to all Kyma repositories. If there is any additional, project-specific information that you want to add to your project's `CONTRIBUTING.md` document, add them under the same sections as in the general contributing guide. * [`LICENSE`](https://github.com/kyma-project/template-repository/blob/main/LICENSE) - It is an obligatory element of every open-source repository. Copy the template into your repository. From e2b14dd29d6b26756ce100e6e4c0a0608d70a4d7 Mon Sep 17 00:00:00 2001 From: mmitoraj Date: Fri, 4 Oct 2024 22:08:34 +0200 Subject: [PATCH 2/2] Fix --- .../repository-guidelines/01-new-repository-settings.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guidelines/repository-guidelines/01-new-repository-settings.md b/docs/guidelines/repository-guidelines/01-new-repository-settings.md index 09823329b..a1d833971 100644 --- a/docs/guidelines/repository-guidelines/01-new-repository-settings.md +++ b/docs/guidelines/repository-guidelines/01-new-repository-settings.md @@ -90,7 +90,7 @@ With that configuration, the md-check-link verifies all `.md` files in your repo #### Central Config -All Kyma modules' repositories that store user-facing documentation are included in the central configuration of [md-check-link](https://github.com/kyma-project/md-check-link). It allows Technical Writers to use a nightly GitHub Actions workflow, called [Verify markdown links in Kyma project](https://github.com/kyma-project/md-check-link/actions/workflows/check-kyma-links.yml), that detects broken links in all `.md` files of the listed repositories. +All Kyma modules' repositories that store user-facing documentation must be included in the central configuration of [md-check-link](https://github.com/kyma-project/md-check-link). It allows Technical Writers to use a nightly GitHub Actions workflow, called [Verify markdown links in Kyma project](https://github.com/kyma-project/md-check-link/actions/workflows/check-kyma-links.yml), that detects broken links in all `.md` files of the listed repositories. If you create a new module repository, you must add it to the following files: