From bcc9e432c595cbb17279b31a98269da3c118be6e Mon Sep 17 00:00:00 2001 From: Daniel Gonzalez Nothnagel Date: Thu, 25 Jun 2026 16:24:42 +0200 Subject: [PATCH 1/2] Remove all community content and link community page instead All community content was moved to the community repo and its corresponding github page. Therefore we must remove teh content from this central page. Signed-off-by: Daniel Gonzalez Nothnagel --- docs/.vitepress/config.mts | 4 +- docs/community/contributing.md | 144 ----------------- docs/community/index.md | 35 ---- docs/community/meetings.md | 19 --- docs/community/style-guide/coding.md | 171 -------------------- docs/community/style-guide/documentation.md | 102 ------------ 6 files changed, 2 insertions(+), 473 deletions(-) delete mode 100644 docs/community/contributing.md delete mode 100644 docs/community/index.md delete mode 100644 docs/community/meetings.md delete mode 100644 docs/community/style-guide/coding.md delete mode 100644 docs/community/style-guide/documentation.md diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index 006aed3..5068df5 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -13,7 +13,7 @@ export default withMermaid({ ['meta', {property: 'og:description', content: 'IronCore is an Open-Source platform designed to empower users by providing a robust Infrastructure as a Service layer, Bare Metal Management and Network Automation'}], ['meta', {property: 'og:site_name', content: 'IronCore Project'}], ['meta', {property: 'og:image', content: 'https://raw.githubusercontent.com/ironcore-dev/ironcore-dev.github.io/refs/heads/main/docs/public/og-ironcore.png'}], - ['meta', {property: 'og:url', content: 'https://ironcore.dev/'}], + ['meta', {property: 'og:url', content: 'https://ironcore.dev/', target: '_self'}], ], vite: { resolve: { @@ -38,7 +38,7 @@ export default withMermaid({ {text: 'Bare Metal Management', link: '/baremetal/'}, {text: 'Network Automation', link: '/network-automation/'}, ]}, - {text: 'Community', link: '/community/'}, + {text: 'Community', link: 'https://ironcore.dev/community/'}, ], editLink: { diff --git a/docs/community/contributing.md b/docs/community/contributing.md deleted file mode 100644 index a857d9c..0000000 --- a/docs/community/contributing.md +++ /dev/null @@ -1,144 +0,0 @@ -# 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. - -## Before You Contribute - -Before writing code, make sure your contribution has a home in an issue. This keeps the discussion visible to -maintainers and other contributors and avoids duplicate or misaligned work. - -- **Look for an existing issue** in the repository you want to contribute to. Someone may already be tracking the - bug or feature you have in mind. -- **If nothing matches, open a new issue** in the corresponding project to describe the problem or idea. Use it to - clarify open points and agree on an approach with the maintainers before starting implementation. -- **For larger or cross-cutting changes**, IronCore uses a central - [enhancements repository](https://github.com/ironcore-dev/enhancements) where contributors submit - **IronCore Enhancement Proposals (IEPs)**. An IEP is the place to describe the motivation, design, and trade-offs - of a substantial idea or solution that affects one or more IronCore projects. -- **Even for an IEP, start with an issue.** Especially for new contributors, please open an issue in the - enhancements repository first to outline the idea and gather early feedback. This makes it much easier for - maintainers to engage and for the proposal to land successfully. - -## Making a Contribution - -### Fork and Clone - -Fork the repository you want to contribute to and clone it locally: - -```shell -git clone git@github.com:/.git -cd -``` - -### 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 -``` - -### 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" -``` - -### 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. - -### 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 deleted file mode 100644 index f900ba6..0000000 --- a/docs/community/index.md +++ /dev/null @@ -1,35 +0,0 @@ -# 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 - -### Community Meetings - -The IronCore community holds regular meetings to discuss ongoing development, feature proposals, and other community topics. -Visit our [Meetings Overview](/community/meetings) if you're interested in attending. - -## 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/meetings.md b/docs/community/meetings.md deleted file mode 100644 index 6c01a5f..0000000 --- a/docs/community/meetings.md +++ /dev/null @@ -1,19 +0,0 @@ -# Community Meetings - -The IronCore community holds regular meetings to discuss ongoing development, feature proposals, and other community topics. -These meetings are open to everyone interested in IronCore, whether you're a developer, user, or just curious about the project. - -If you'd like to bring your own topic, feel free to add it to the [agenda](#meeting-agenda). - -## Meeting Schedule - -Visit the [community calendar](https://zoom-lfx.platform.linuxfoundation.org/meetings/ironcore?view=week) for upcoming meetings. - -## Meeting Agenda - -The agenda for the next meetings is maintained in our [Slack workspace](https://join.slack.com/t/ironcore-dev/shared_invite/zt-3o0qo3j90-pbqV0io1B~Z~LqeAp4n2Vg). -Join the workspace to be able to see the agenda and add your own topics. - -These are the existing meeting series and their agendas: - -- [IronCore IaaS Community Call / Office Hour](https://ironcore-dev.slack.com/docs/T01V4AK8HQ8/F0AM7CXFKQV) diff --git a/docs/community/style-guide/coding.md b/docs/community/style-guide/coding.md deleted file mode 100644 index 2fcd3ed..0000000 --- a/docs/community/style-guide/coding.md +++ /dev/null @@ -1,171 +0,0 @@ -# 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 deleted file mode 100644 index b3bf3af..0000000 --- a/docs/community/style-guide/documentation.md +++ /dev/null @@ -1,102 +0,0 @@ -# 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/` | From f24e80695b0029b216ffdaa27ad583f897eadd7b Mon Sep 17 00:00:00 2001 From: Daniel Gonzalez Nothnagel Date: Thu, 25 Jun 2026 16:27:37 +0200 Subject: [PATCH 2/2] Hide external link arrow for ironcore.dev nav links Signed-off-by: Daniel Gonzalez Nothnagel --- docs/.vitepress/theme/custom.css | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/.vitepress/theme/custom.css b/docs/.vitepress/theme/custom.css index 3da7829..4d1f645 100644 --- a/docs/.vitepress/theme/custom.css +++ b/docs/.vitepress/theme/custom.css @@ -30,6 +30,11 @@ padding: 18px; } +/* hide external link arrow for same-family ironcore.dev nav links */ +.VPNavBar a.vp-external-link-icon[href^="https://ironcore.dev"]::after { + display: none; +} + /* used in reference/default-theme-search */ img[src='/search.png'] { width: 100%;