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/.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%; 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/` |