From b0feca69b5d67faa420e14e7915bfd0325e85d75 Mon Sep 17 00:00:00 2001 From: Andreas Fritzler Date: Tue, 10 Feb 2026 20:55:08 +0100 Subject: [PATCH] Add community section --- docs/.vitepress/config.mts | 20 +- docs/community/contributing.md | 127 ++++++ docs/community/index.md | 30 ++ docs/community/style-guide/coding.md | 171 +++++++ docs/community/style-guide/documentation.md | 102 +++++ docs/contribute/contributing.md | 114 ----- docs/contribute/style-guide.md | 476 -------------------- 7 files changed, 449 insertions(+), 591 deletions(-) create mode 100644 docs/community/contributing.md create mode 100644 docs/community/index.md create mode 100644 docs/community/style-guide/coding.md create mode 100644 docs/community/style-guide/documentation.md delete mode 100644 docs/contribute/contributing.md delete mode 100644 docs/contribute/style-guide.md diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index 368edae..d2f5910 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -31,13 +31,14 @@ export default withMermaid({ // https://vitepress.dev/reference/default-theme-config nav: [ {text: 'Home', link: '/'}, - {text: 'Overview', link: '/overview'}, + {text: 'Overview', link: '/overview/'}, {text: 'Documentation', items: [ {text: 'Infrastructure as a Service', link: '/iaas/getting-started'}, {text: 'Bare Metal Management', link: '/baremetal/'}, {text: 'Network Automation', link: '/network-automation/'}, ]}, + {text: 'Community', link: '/community/'}, ], editLink: { @@ -169,6 +170,23 @@ export default withMermaid({ text: 'Overview', link: '/network-automation/', }, ], + '/community/': [ + { + text: 'Community', + items: [ + { text: 'Welcome', link: '/community/' }, + { text: 'Contributing Guide', link: '/community/contributing' }, + ], + }, + { + text: 'Style Guide', + collapsed: false, + items: [ + { text: 'Coding', link: '/community/style-guide/coding' }, + { text: 'Documentation', link: '/community/style-guide/documentation' }, + ], + }, + ], }, socialLinks: [ { diff --git a/docs/community/contributing.md b/docs/community/contributing.md new file mode 100644 index 0000000..e51fda3 --- /dev/null +++ b/docs/community/contributing.md @@ -0,0 +1,127 @@ +# Contributing to IronCore + +Welcome to the IronCore contributor guide! Whether you're fixing a typo, reporting a bug, or building a new feature, +your contributions are welcome at any time. This guide applies to all repositories under the +[ironcore-dev](https://github.com/ironcore-dev) GitHub organization. + +## Prerequisites + +Before your first contribution, please complete the following: + +1. **Create a [GitHub account](https://github.com/signup)** if you don't already have one. +2. **Sign the [Developer Certificate of Origin (DCO)](https://developercertificate.org/)** — all commits must be + signed off (`git commit -s`) to certify that you wrote the code or have the right to submit it. This is checked + automatically on every pull request. +3. **Read our [Code of Conduct](https://events.linuxfoundation.org/about/code-of-conduct/)** — we follow the + Linux Foundation Code of Conduct and are committed to providing a welcoming and respectful community for everyone. + +## Find Something to Work On + +Not sure where to start? Here are a few ways to find your first contribution: + +- **Browse [`good first issue`](https://github.com/search?q=org%3Aironcore-dev+label%3A%22good+first+issue%22+state%3Aopen&type=issues) + labels** — these are issues where maintainers have committed to providing extra guidance. +- **Look for [`help wanted`](https://github.com/search?q=org%3Aironcore-dev+label%3A%22help+wanted%22+state%3Aopen&type=issues) + labels** — these are issues open for community contribution. +- **Improve documentation** — clarify existing docs, fix typos, or add missing content. See the + [documentation conventions](/community/style-guide/documentation) in the style guide. +- **Report a bug** — if you've found an issue, open a GitHub issue with steps to reproduce it. +- **Propose a feature** — open an issue to discuss your idea before starting implementation. + +**Tip:** Before working on a larger change, open an issue first to discuss your approach with the maintainers. This +avoids unnecessary work and helps align your contribution with the project's direction. + +## Making a Contribution + +### 1. Fork and Clone + +Fork the repository you want to contribute to and clone it locally: + +```shell +git clone git@github.com:/.git +cd +``` + +### 2. Create a Branch + +Create a feature branch from `main`: + +```shell +git checkout -b my-feature +``` + +If needed, rebase to the current `main` before submitting your pull request: + +```shell +git fetch upstream main +git rebase upstream/main +``` + +### 3. Make Your Changes + +- Follow the [coding](/community/style-guide/coding) and [documentation](/community/style-guide/documentation) style guides for code, testing, and documentation standards. +- Keep commits small and focused — each commit should be correct independently. +- Write clear [commit messages](/community/style-guide/coding#commit-messages) that explain *why*, not just *what*. +- Include tests for any new functionality or bug fix. +- Sign off every commit for DCO compliance: + +```shell +git commit -s -m "Add support for feature X" +``` + +### 4. Submit a Pull Request + +Push your branch and open a pull request against `main`: + +```shell +git push origin my-feature +``` + +In your pull request description: +- Explain what the change does and why it's needed. +- Reference any related issues (e.g., `Fixes #123`). +- Tag a relevant maintainer if you need a specific reviewer — check the `CODEOWNERS` file in the repository. + +### 5. Run Checks + +Before submitting, run the project's checks locally to catch issues early. See +[Running tests](/community/style-guide/coding#running-tests) in the coding style guide for details: + +```shell +make test # Unit and integration tests +make lint # Linter checks +make verify # Code generation and manifests are up to date +``` + +## Code Review + +All contributions go through code review before merging. Here's what to expect: + +- **A maintainer will review your PR** and may request changes. This is normal — reviews improve code quality for + everyone. +- **Address feedback** by pushing additional commits or amending existing ones. +- **Mark resolved comments** as resolved in GitHub and leave a comment when your changes are ready for another look. + +Reviews are a collaborative process. Don't hesitate to ask questions or push back if you disagree with feedback — +respectful discussion leads to better outcomes. + +## Reporting Issues + +We use GitHub issues to track bugs and feature requests. When opening an issue: + +- Check if a similar issue already exists. +- Provide enough context to understand and reproduce the problem. +- Use the issue templates provided in each repository when available. + +## Licensing + +All contributions to IronCore projects are licensed under the +[Apache 2.0 License](http://www.apache.org/licenses/LICENSE-2.0). + +## Need Help? + +- Ask questions on any issue or pull request — maintainers are happy to help. +- Join our [Slack workspace](https://join.slack.com/t/ironcore-dev/shared_invite/zt-3o0qo3j90-pbqV0io1B~Z~LqeAp4n2Vg) + to chat with the community. + +Thank you for contributing to IronCore! diff --git a/docs/community/index.md b/docs/community/index.md new file mode 100644 index 0000000..489b00e --- /dev/null +++ b/docs/community/index.md @@ -0,0 +1,30 @@ +# Welcome to the IronCore Community! + +IronCore is an open-source project built by and for the community. Whether you're a developer, system administrator, +or infrastructure enthusiast, there are many ways to get involved, ask questions, and contribute to the project. + +## Get Connected + +### Slack + +Join our [Slack workspace](https://join.slack.com/t/ironcore-dev/shared_invite/zt-3o0qo3j90-pbqV0io1B~Z~LqeAp4n2Vg) to chat +with maintainers and other community members. It's the best place to ask questions, share ideas, and get help with IronCore. + +### GitHub + +All IronCore development happens in the open on [GitHub](https://github.com/ironcore-dev). You can: + +- Browse the source code and documentation +- Report bugs or request features by opening an [issue](https://github.com/ironcore-dev/ironcore/issues) +- Follow the project's development and roadmap + +## Contribute + +We welcome contributions of all kinds — from code and documentation to bug reports and feature ideas. If you'd like to +get started, check out our [Contributing Guide](/community/contributing), [Coding Style Guide](/community/style-guide/coding), +and [Documentation Style Guide](/community/style-guide/documentation). + +## Code of Conduct + +The IronCore community is committed to providing a welcoming and inclusive environment for everyone. We expect all +participants to treat each other with respect and professionalism. diff --git a/docs/community/style-guide/coding.md b/docs/community/style-guide/coding.md new file mode 100644 index 0000000..2fcd3ed --- /dev/null +++ b/docs/community/style-guide/coding.md @@ -0,0 +1,171 @@ +# Coding Style Guide + +This style guide defines the conventions for contributing code and tests across all IronCore projects. +Following these standards ensures consistency and helps maintainers review contributions efficiently. + +## Code Style + +### Go Conventions + +All IronCore projects are written in Go. We follow the standard Go style guides as our baseline: + +- [Effective Go](https://go.dev/doc/effective_go) — the foundational language guide. +- [Go Code Review Comments](https://go.dev/wiki/CodeReviewComments) — the de facto standard for code reviews. + +The rules below supplement these upstream guides with IronCore-specific conventions. Do not duplicate what is already +covered upstream — read those guides first. + +### Formatting + +- Run `gofmt` (or `goimports`) on all code before committing. This is non-negotiable. +- Use your editor or a pre-commit hook to automate formatting. + +### Naming + +- Follow Go naming conventions: `MixedCaps` for exported identifiers, `mixedCaps` for unexported ones. Never use + underscores in Go names. +- Keep initialisms consistent: `URL` not `Url`, `ID` not `Id`, `HTTP` not `Http`. +- Use descriptive package names. Avoid generic names like `util`, `common`, `helpers`, or `misc`. +- Controller and reconciler types should clearly indicate the resource they manage + (e.g., `MachineReconciler`, `VolumeController`). + +### Imports + +Organize imports into three groups separated by blank lines: + +```go +import ( + // Standard library + "context" + "fmt" + + // Third-party packages + "sigs.k8s.io/controller-runtime/pkg/client" + + // IronCore packages + "github.com/ironcore-dev/ironcore/api/compute/v1alpha1" +) +``` + +Avoid renaming imports unless there is a name collision. + +### Error Handling + +- Never discard errors with `_`. Handle every error or explicitly document why it is safe to ignore. +- Return errors as the last return value. Handle errors early and return — keep the happy path at minimal indentation. +- Use lowercase error strings without trailing punctuation: `fmt.Errorf("failed to create machine")`. +- Wrap errors with context: `fmt.Errorf("reconciling machine %s: %w", name, err)`. + +### Comments + +- Write comments that explain *why*, not *what*. The code itself shows what it does. +- Comments on exported identifiers become godoc — start with the identifier name and write complete sentences. +- If reviewers ask questions about why code is written a certain way, that is a sign that a comment would help. + +### Logging + +- Use structured logging consistently. Prefer key-value pairs over formatted strings. +- Use appropriate log levels: + - **Error** — the reconciler cannot proceed; requires attention. + - **Info** — significant events (resource created, deleted, reconciled). + - **Debug/V(1)** — detailed information useful for troubleshooting. + +### Linting + +All projects should use [golangci-lint](https://golangci-lint.run/) with the project's `.golangci.yml` configuration. +Run linters locally before pushing: + +```shell +make lint +``` + +## Testing + +Good tests are as important as good code. Tests protect against regressions, document expected behavior, and give +reviewers confidence that changes work correctly. + +### Testing Pyramid + +IronCore projects use three levels of testing: + +| Level | Purpose | Tools | +| --- | --- | --- | +| **Unit tests** | Test individual functions and methods in isolation. | Go standard `testing` package | +| **Integration tests** | Test controllers against a real API server using envtest. | [controller-runtime envtest](https://pkg.go.dev/sigs.k8s.io/controller-runtime/pkg/envtest) | +| **End-to-end tests** | Test the full system with real components deployed. | [Ginkgo](https://onsi.github.io/ginkgo/) + [Gomega](https://onsi.github.io/gomega/) | + +### Writing Tests + +- **Table-driven tests** are the preferred pattern for unit tests with multiple input/output cases: + +```go +func TestValidateMachineName(t *testing.T) { + tests := []struct { + name string + input string + wantErr bool + }{ + {name: "valid name", input: "my-machine", wantErr: false}, + {name: "empty name", input: "", wantErr: true}, + {name: "name with spaces", input: "my machine", wantErr: true}, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + err := ValidateMachineName(tt.input) + if (err != nil) != tt.wantErr { + t.Errorf("ValidateMachineName(%q) error = %v, wantErr %v", tt.input, err, tt.wantErr) + } + }) + } +} +``` + +- **Test names** should be descriptive and specific. Use the pattern `Test_` for unit tests. +- **Assertions** in Ginkgo/Gomega tests should use matchers, not boolean checks: + +| Do | Don't | +| --- | --- | +| `Expect(pod.Status.Phase).To(Equal(corev1.PodRunning))` | `Expect(pod.Status.Phase == corev1.PodRunning).To(BeTrue())` | + +- **Failure messages** must be actionable. Include what was expected, what was received, and enough context to debug + without re-running: + +| Do | Don't | +| --- | --- | +| `"expected Machine %s to be in Running phase, got %s"` | `"wrong phase"` | + +### Test Reliability + +- Tests must be deterministic. A test that passes 99% of the time is unreliable in CI. +- Use `gomega.Eventually` for polling conditions instead of `time.Sleep`. +- Clean up resources after tests. Use `DeferCleanup` in Ginkgo or `t.Cleanup` in standard tests. +- Keep tests fast. Unit tests should complete in seconds; integration tests in under two minutes. + +### Running Tests + +Before submitting a pull request, run the full test suite locally: + +```shell +make test # Unit and integration tests +make lint # Linter checks +make verify # Code generation and manifests are up to date +``` + +## Commit Messages + +- **Subject line**: imperative mood, max 72 characters, capitalize the first word, no trailing period. +- **Body**: wrap at 72 characters, explain *what* and *why*, separate from the subject with a blank line. +- Reference related issues: `Fixes #123` or `Relates to #456`. + +| Do | Don't | +| --- | --- | +| `Add volume snapshot support` | `Added volume snapshot support` | +| `Fix nil pointer in machine reconciler` | `fixed stuff` | + +## Pull Requests + +- Keep pull requests small and focused — one logical change per PR. +- Separate bug fixes from refactoring from new features. +- Include tests for any new functionality or bug fix. +- Ensure all CI checks pass before requesting review. +- Write a clear PR description explaining what changed and why. diff --git a/docs/community/style-guide/documentation.md b/docs/community/style-guide/documentation.md new file mode 100644 index 0000000..b3bf3af --- /dev/null +++ b/docs/community/style-guide/documentation.md @@ -0,0 +1,102 @@ +# Documentation Style Guide + +This section covers conventions for contributing to the [IronCore documentation site](https://ironcore.dev), built +with [VitePress](https://vitepress.dev/). + +## Language and Tone + +- Write in **U.S. English**. +- Use **second person** ("you") to address the reader directly. +- Use **active voice** and **present tense**. +- Keep sentences short and direct. + +| Do | Don't | +| --- | --- | +| You can create a Machine by applying the manifest. | The Machine can be created by the user by applying the manifest. | +| Run `kubectl apply` to create the resource. | The resource should be created by running `kubectl apply`. | + +## Content Types + +Structure documentation pages according to these types: + +- **Concept** — Explains *what* something is and *why* it matters. Prose and headings, no step-by-step instructions. +- **Task** — Shows *how* to do a single thing. Numbered steps with minimal explanation. +- **Tutorial** — Walks through a larger goal involving multiple tasks. Includes objectives, prerequisites, and cleanup. +- **Reference** — API or CLI documentation. Covers synopsis, options, and examples. + +## API Object Names + +Use **UpperCamelCase** when referring to IronCore or Kubernetes API kinds. Do not wrap them in backticks — the casing +alone signals they are API objects. + +| Do | Don't | +| --- | --- | +| Create a Machine resource. | Create a `machine` resource. | +| The Volume object stores block data. | The volume object stores block data. | +| A NetworkInterface belongs to a Network. | A network interface belongs to a network. | + +## Inline Code + +Use backticks for commands, tools, field names, file paths, and namespaces. Do not use backticks for API kind names +or field values. + +| Do | Don't | +| --- | --- | +| Set `replicas` to 3. | Set `replicas` to `3`. | +| The `kubelet` reports node status. | `kubelet` reports node status. | + +Never start a sentence with a backticked word — prefix with an article (e.g., "The `kubeadm` tool..."). + +## Placeholders + +Use angle brackets and explain each placeholder: + +```shell +kubectl get machine -n +``` + +## Headings + +- One `#` (H1) per page as the document title. +- Use `##` and below for sections. Do not skip heading levels. +- Use **title case**: capitalize major words (nouns, verbs, adjectives, adverbs) and lowercase minor words (articles, prepositions, conjunctions) unless they are the first word. +- Keep headings unique within a document — they generate anchor links. +- Do not number headings. + +## Lists + +- Use `1.` for every numbered list item — the renderer handles numbering. +- Use `-` for bulleted lists. +- Use 4-space indentation for nested items. + +## Code Blocks + +Use fenced code blocks with a language identifier for syntax highlighting. Use meaningful names — avoid `foo` and +`bar`. For plain text output, use `text` as the language. + +## Links + +- Use site-relative paths for internal links: `[Getting started](/iaas/getting-started)`. +- Do not use full URLs for internal links or relative paths with `../`. +- Write links as natural parts of the sentence — avoid "click here" or "this link". + +## Diagrams + +- Prefer [Mermaid](https://mermaid.js.org) for inline diagrams rendered in VitePress. +- For complex visuals, use [draw.io](https://draw.io) or [Excalidraw](https://excalidraw.com) and export as PNG. +- Store source files alongside exported images. Use the suffix `.diagram.png`. + +## Images and Screenshots + +- Use sparingly — they become outdated quickly. +- Blur or remove sensitive information. +- Use light mode and crop to the relevant area. + +## File and Folder Naming + +Use lowercase with hyphens. No spaces or underscores: + +| Do | Don't | +| --- | --- | +| `getting-started.md` | `Getting Started.md` | +| `bare-metal-management/` | `bare_metal_management/` | diff --git a/docs/contribute/contributing.md b/docs/contribute/contributing.md deleted file mode 100644 index 1986e9a..0000000 --- a/docs/contribute/contributing.md +++ /dev/null @@ -1,114 +0,0 @@ -# Contributing to IronCore Documentation - -We welcome contributions from the community! Follow these guidelines to help us maintain high-quality, consistent documentation. - -## How to Contribute -1. Fork the repository and create a new branch. -2. Make your changes following the [Style Guide](style-guide.md). -3. Submit a pull request with a clear description of your changes. - -## Code Review -- All contributions will be reviewed for clarity, accuracy, and consistency. -- Feedback will be provided if any adjustments are necessary. - -Thank you for helping improve our documentation! -## Contributors Guide - -The IronCore Documentation project uses Github to manage reviews of pull requests. - -* If you are looking to make your first contribution, follow [Steps to Contribute](#steps-to-contribute) - -* If you have a trivial fix or improvement, go ahead and create a pull request and -address (with @...) a suitable maintainer of this repository -(see [CODEOWNERS](https://github.com/ironcore-dev/ironcore-dev.github.io/blob/main/CODEOWNERS) -of this repository) in the description of the pull request. - -* If you plan to do something more involved, first discuss your ideas by creating an -[issue](https://github.com/ironcore-dev/ironcore-dev.github.io/issues) for this repository. This will avoid unnecessary work and surely give you -and us a good deal of inspiration. - -!!! note - Please follow these style guidelines to have your contribution considered by the maintainers: - [Documentation style guidelines](https://github.com/ironcore-dev/ironcore-dev.github.io/blob/main/docs/contribute/style-guide.md) - -## Steps to Contribute - -Do you want to work on an issue? You are welcome to claim an existing one by commenting on it in GitHub. - -!!! note - Perform a cursory search to see if the issue has already been taken by someone else. - This will prevent misunderstanding and duplication of effort from contributors on the same issue. - -If you have questions about one of the issues please comment on them and one of the -maintainers will clarify it. - -We kindly ask you to follow the [Pull Request Checklist](#pull-request-checklist) to ensure reviews can happen accordingly. - -## Contributing - -You are welcome to contribute documentation to the IronCore Documentation project. - -The following rules govern documentation contributions: - -* Contributions must be licensed under the [Apache 2.0 License](http://www.apache.org/licenses/LICENSE-2.0) -* You need to sign the [Developer Certificate of Origin](#developer-certificate-of-origin). - - -## Developer Certificate of Origin - -Due to legal reasons, contributors will be asked to accept a Developer Certificate of Origin (DCO) before they submit -the first pull request to the IronCore project, this happens in an automated fashion during the submission -process. We use [the standard DCO text of the Linux Foundation](https://developercertificate.org/). - -## Pull Request Checklist - -* Fork and clone the repository to your local machine. - -```shell -git clone git@github.com:ironcore-dev/ironcore-dev.github.io.git -cd docs -``` - -* Create a branch from the `main` using 'git checkout' command. -!!! note - If needed, rebase to the current `main` branch before submitting your pull request. If it doesn't merge properly - with `main` you may be asked to rebase your changes. - -```shell -git checkout -b my_feature -# rebase if necessary -git fetch upstream main -git rebase upstream/main -``` - -* Commits should be as small as possible, while ensuring that each commit is correct independently - -* Commit your changes to your feature branch and push it to your fork. - -```shell -git add . -git commit -m "Something meaningful" -git push origin my_feature -``` - -!!! note - Alternatively you can amend your commit before pushing if you forgot something by using `git commit --amend` - -* Create _Work In Progress [WIP]_ pull requests only if you need a clarification or an explicit review before you can -continue your work item. - -* If your patch is not getting reviewed, or you need a specific person to review it, you can @-reply a reviewer asking -for a review in the pull request or a comment. - -* Post review: - * If a reviewer requires you to change your commit(s), please test the changes again. - * Amend the affected commit(s) and force push onto your branch. - * Set respective comments in your GitHub review as resolved. - * Create a general PR comment to notify the reviewers that your amendments are ready for another round of review. - -## Issues and Planning - -We use GitHub issues to track bugs and enhancement requests. Please provide as much context as possible when you open an issue. The information you provide must be comprehensive enough to understand, reproduce the behavior and find related reports of that issue for the assignee. -Therefore, contributors may use but aren't restricted to the issue template provided by the IronCore maintainers. - -Thank you for helping improve our documentation! diff --git a/docs/contribute/style-guide.md b/docs/contribute/style-guide.md deleted file mode 100644 index 0c07682..0000000 --- a/docs/contribute/style-guide.md +++ /dev/null @@ -1,476 +0,0 @@ -# Documentation Style Guide - -This style guide outlines the standards for writing and formatting documents for -the IronCore project. - -## Target audience - -Markdown is basically a structured language similar to source code, it will be -consumed in rendered form. There is no unified Markdown specification, so -different renderers will show it in different way. - -User-facing documentation will be rendered by `mkdocs` (with the Material theme) -to static HTML files. `mkdocs` provides several enhancements compared to other -solutions, such as warning boxes. - -You can install `mkdocs` with the Material theme to your workstation using `pip` -and render the page locally to see the result. Do not assume, that your document -will look OK via `mkdocs`, based on its appearance in GitHub, Gitlab, or in VS -Code's preview! - -## Document layout - -In general, Markdown source documents benefit from some variation of the -following layout: - -```markdown -# Document Title - -Short introduction. - -[TOC] - -## Topic - -Content. - -## See also - -- https://link.to/more-info -``` - -1. `# Document title`: The first heading should be a H1 heading, ideally the - same or nearly the same as the filename. The first H1 heading is used as the - page ``. -1. `Short introduction`. 1–3 sentences providing a high-level overview of the - topic. Imagine yourself as a complete newbie who landed on your “Extending - Foo” doc and doesn’t know the most basic information you take for granted. - “What is Foo? Why would I extend it?” -1. `[TOC]`: if you use hosting that supports table of contents, such as GitHub - or Gitlab put `[TOC]` after the short introduction. If renderers support - creating automatic TOCs, do not place a `TOC` directive. -1. `## Topic`: The rest of your headings should start from H2. -1. `## See also`: Put miscellaneous links at the bottom for the user who wants - to know more or didn’t find what they needed. - -## Table of contents - -`mkdocs` generates a static `TOC` from the sub-page based on the headers found -in the page during generation. Do not include any sort of `TOC` to the -user-facing documentation. - -## Line length - -Markdown can be considered source code, which is written, re-written, edited -continuously, and compiled into its final HTML form. - -To simplify the editing and review process the line length should be kept short. -Consider starting a sentence in a newline after a comma, after an "and", when -the sentence naturally breaks. - -Try to write short sentences. Keep in mind a ca. 80, max. 120 character line -length limit. If the sentence is too long, apply the rules from above. - -## Headers - -Use headers only for real headers, not for making the text more visible. For -that purpose use **bold** or _italics_. Use a single H1 heading in a Markdown -source document; subsequent headings should be H2 or deeper. - -Use header levels consecutively, don't skip them: - -```markdown -# level1 - -## level 2 - -### level 3 -``` - -Not: - -```markdown -# level1 - -### level 3 -``` - -Header text has to be unique in the whole Markdown source document. It is -important, because HTML IDs are created from the headers which are then used as -links to the specific section in the document (such as the `TOC`). Duplicated -headers will break this functionality, and a link to a specific section can be -rendered as a link to another section with the same header text. This includes -headers in different sub-sections. - -BAD example: - -```markdown -# My bad docs site - -## Foo - -### Summary - -### Examples - -## Bar - -### Summary - -### Examples -``` - -GOOD example: - -```markdown -# My good docs site - -## Foo - -### Foo Summary - -### Foo Examples - -## Bar - -### Bar Summary - -### Bar Examples -``` - -### Header case - -There are several approaches, our approach is `First word with uppercase`. You -can see this applied in this document. - -### Header numbering - -Do not number the headers. This will just introduce headaches during editing, as -adding or removing sections will necessitate manual renumbering. - -If documenting sequential tasks, consider numbered lists instead. - -### Header spacing - -Prefer an empty line break between a header and its content text. This increases -readability. For example: - -```markdown -Some text before heading. - -## Level 2 - -Text after the heading. -``` - -## Lists - -### Numbered lists - -Numbered lists can be tricky as the renderers usually ignore the manually added -numbers and number the list automatically. The automatic numbering is sensitive -and can restart the numbering. The exact rules of preventing this can be -different for different renderers. - -When adding numbered lists, let the renderer decide how to display them and just -stick to the definition for numbered lists, which is to use `1.` for any item in -the same numbered list. - -```markdown -1. first item -1. second item -1. third item -``` - -### Bulleted lists - -Bulleted (or unordered lists) should use a `-` as the identifier for an item in -a bulleted list. For example: - -```markdown -DO NOT DO THIS - -* not a good item -* this is also not a good item - -DO THIS - -- this is a good item -- this is another good item -``` - -### Indentation - -Use 4-space indentation for lists, this includes ordered and unordered lists as -well. For example: - -```markdown -1. this sentence has 1 space between the number and the content the next - sentence is wrapped and continues here -1. finally the third sentence is again 4-space indented - 1. a sub item uses again 4-space indentation - 1. and the iem below as well -1. and we are back to the original level -``` - -Consistently, the same indentation and spacing rules are applied to unordered -lists. For example: - -```markdown -- my bulleted item -- another item - - with a sub item consistently indented - - and another one -- and back to original level -``` - -### Nested lists - -When nesting lists, the same rules explained before are applied. Use a -consistent 4-space indent for both numbered and bulleted items: - -```markdown -1. Use 1 space after the item number, so the text itself is indented 3 spaces. - Use a 3-space indent for wrapped text. -2. Use 1 space again for the next item. - -- Use 1 space after a bullet, so the text itself is indented 2 spaces. Use a - 3-space indent for wrapped text. - - 1. Use 1 space with numbered lists, as before. Wrapped text in a nested list - needs an 7-space indent. - 2. Looks nice, doesn't it? - -- Back to the bulleted list, indented 1 space. -``` - -## Text highlighting - -There are two possibilities: - -- One asterisk for _italics, or slanted text_: `*italics*`. This is usually - recommended for emphasizing text. -- Two asterisks for **bold text**: `**bold**`. This is more visible. -- Do not use the backtick style for highlighting parts of the text. - -To write monospace texts: - -- Backticked (\`) `ConfigurationParameter`. Use only for words, phrases lifted - from a source code or configuration file. -- Fenced code (with \`\`\`) — only for code or configuration snippets. Syntax - should be hinted. - -!!! note - - Each code block has to have its language specified. For plaintexts or stdouts, - use text. For usage refer to official documentation. - -To write a block quote, prepend the line with `>`: - -> This is a block quote. You can use it to highlight a paragraph. - -`mkdocs` with the Material theme supports [admonitions][admonitions] for -structuring pages. - -[admonitions]: - https://squidfunk.github.io/mkdocs-material/reference/admonitions/#usage - -## Links - -Long links make source Markdown difficult to read and break the 80 character -wrapping. **Wherever possible, shorten your links.** - -### Use explicit paths for links within markdown - -Use the explicit path for a markdown link in the same documentation project. For -example: - -```markdown -[my example link](/path/to/markdown.md) -``` - -Avoid using the full qualifier URL: - -```markdown -[my bad example link](https://full-url.bad-example.com/path/to/markdown.md) -``` - -### Avoid relative paths unless in the same directory - -Relative paths are safe to use in the same directory. For example: - -```markdown -[my link](other-page-in-same-dir.md) - -[my other link](/path/to/another/dir/other-page.md) -``` - -Avoid relative links if you need to specify other directories with `../`: - -```markdown -[my bad relative link](../bad/path/to/another/dir/other-page.md) -``` - -### Use natural and informative link titles - -Markdown link syntax allows you to set a link title. Use it wisely. Users often -do not read documents word-by-word; they scan them. - -Links catch the eye. But titling your links “here,” “link,” or simply -duplicating the target URL tells the reader precisely nothing and is a waste of -space: - -```text -DO NOT DO THIS. - -See the Markdown guide for more info: [link](markdown.md), or check out the style guide [here](/styleguide/docguide/style.html). - -Check out a typical test result: [https://example.com/foo/bar](https://example.com/foo/bar). -``` - -Instead, write the sentence naturally, then go back and wrap the most -appropriate phrase with the link: - -```text -See the [Markdown guide](markdown.md) for more info, or check out the [style guide](/styleguide/docguide/style.html). - -Check out a [typical test result](https://example.com/foo/bar). -``` - -### References - -Use reference-style links sparingly. Use them where the length of the link would -detract from readability of the source Markdown file. For example: - -```markdown -See more in the [documentation][doku]. - -[doku]: - http://example.com/doku/this/is/a/really/long/link/who/would/have/thought/man/when/does/it/actually/stop.md -``` - -Use reference links more often in tables. It is particularly important to keep -table content short, since Markdown does not provide a facility to break text in -cell tables across multiple lines, and smaller tables are more readable. -Multiple lines, and smaller tables are more readable. - -For example, this table’s readability is worsened by inline links: - -```markdown -DO NOT DO THIS. - -| Site | Description | -| ---------------------------------------------------------------- | ----------------------- | -| [site 1](http://github.com/excessively/long/path/example_site_1) | This is example site 1. | -| [site 2](http://github.com/excessively/long/path/example_site_2) | This is example site 2. | -``` - -Instead, use reference-style links to shorten the content of the table cells: - -```markdown -| Site | Description | -| -------- | ----------------------- | -| [site 1] | This is example site 1. | -| [site 2] | This is example site 2. | - -[site 1]: http://github.com/excessively/long/path/example_site_1 -[site 2]: http://github.com/excessively/long/path/example_site_2 -``` - -Reference-style links can also help with deduplication, when links to the same -resources are used more than once in the same Markdown source document. - -The definition of a reference-style link should be at the bottom of the -sub-section where it is first used. For example: - -```markdown -# Header - -Some text with a [link][link_def]. - -Some more text with the same [link][link_def]. - -[link_def]: http://reallyreallyreallylonglink.com - -## Header 2 - -... lots of text ... - -## Header 3 - -Some more text using a [different_link][different_link_def]. - -[different_link_def]: http://differentreallyreallylonglink.com -``` - -## Diagrams - -Diagrams are a well-suited tool to transport complex behavior or relationships -in a digestible manner. To work with diagrams in an effective way the -style-guide defines some guidelines for diagrams. - -There are different tools which implement diagram drawing, the most popular ones -are: - -- [draw.io](https://draw.io) -- [excalidraw](https://excalidraw.com) -- [mermaid.js](https://mermaid.js.org) - -In general, the chosen tool is not as important. The source diagram should be -stored in the same repository. When the chosen tool supports tabs, such usage -should be limited to 1 tab per file. This is to make sure there are no hidden -diagrams that renderers cannot properly visualize. - -Most tools support storing a diagram in some image format. The diagram should be -stored in PNG format to support layers and transparency. The diagram image -requires the filename suffix `.diagram.png`. - -## Emoji - -How Emoji is displayed depends on the specific Markdown renderer software so to -make sure the document looks the same, you shouldn't use them. - -Instead of emojis you can use [UTF symbols][utfsymbols]. - -## Screenshots - -Screenshots should be inserted with care as they tend to be outdated quickly. - -Be careful to not leave sensitive information on the screenshots. Blur or black -them out if there's no possibility to leave them out. - -Try to use light mode when creating screenshots, they look better on the white -pages of the documentation. - -Try to shrink the window as much as possible, no point of including empty parts -of web interfaces. - -## Folder and File naming convention - -Files and folder names will be ideally simple without whitespace characters. -Complex names created from multiple words can use `-` instead of space. - -BAD complex name: - -```text -brokering and poollet behavior.md -``` - -GOOD complex name: - -```text -brokering-and-poollet-behavior.md -``` - -## Miscellaneous - -- Use a spell checker (example for [VS Code][codespell] and [VIM][vimspell]). -- Use a Markdown linter plugin for your editor. - -This style guide was inspired by experience and -[the official google documentation style guide](https://google.github.io/styleguide/docguide/style.html). - -[codespell]: - https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker -[vimspell]: https://www.linux.com/training-tutorials/using-spell-checking-vim/ -[utfsymbols]: https://www.w3schools.com/charsets/ref_utf_symbols.asp