Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update repository guidelines and style and terminology #944

Merged
merged 2 commits into from
Oct 9, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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 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:

* [`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=).
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down