Skip to content

Commit b0feca6

Browse files
afritzlerafritzler
committed
Add community section
1 parent 4ed9d14 commit b0feca6

7 files changed

Lines changed: 449 additions & 591 deletions

File tree

‎docs/.vitepress/config.mts‎

Lines changed: 19 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,13 +31,14 @@ export default withMermaid({
3131
// https://vitepress.dev/reference/default-theme-config
3232
nav: [
3333
{text: 'Home', link: '/'},
34-
{text: 'Overview', link: '/overview'},
34+
{text: 'Overview', link: '/overview/'},
3535
{text: 'Documentation',
3636
items: [
3737
{text: 'Infrastructure as a Service', link: '/iaas/getting-started'},
3838
{text: 'Bare Metal Management', link: '/baremetal/'},
3939
{text: 'Network Automation', link: '/network-automation/'},
4040
]},
41+
{text: 'Community', link: '/community/'},
4142
],
4243

4344
editLink: {
@@ -169,6 +170,23 @@ export default withMermaid({
169170
text: 'Overview', link: '/network-automation/',
170171
},
171172
],
173+
'/community/': [
174+
{
175+
text: 'Community',
176+
items: [
177+
{ text: 'Welcome', link: '/community/' },
178+
{ text: 'Contributing Guide', link: '/community/contributing' },
179+
],
180+
},
181+
{
182+
text: 'Style Guide',
183+
collapsed: false,
184+
items: [
185+
{ text: 'Coding', link: '/community/style-guide/coding' },
186+
{ text: 'Documentation', link: '/community/style-guide/documentation' },
187+
],
188+
},
189+
],
172190
},
173191
socialLinks: [
174192
{

‎docs/community/contributing.md‎

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
# Contributing to IronCore
2+
3+
Welcome to the IronCore contributor guide! Whether you're fixing a typo, reporting a bug, or building a new feature,
4+
your contributions are welcome at any time. This guide applies to all repositories under the
5+
[ironcore-dev](https://github.com/ironcore-dev) GitHub organization.
6+
7+
## Prerequisites
8+
9+
Before your first contribution, please complete the following:
10+
11+
1. **Create a [GitHub account](https://github.com/signup)** if you don't already have one.
12+
2. **Sign the [Developer Certificate of Origin (DCO)](https://developercertificate.org/)** — all commits must be
13+
signed off (`git commit -s`) to certify that you wrote the code or have the right to submit it. This is checked
14+
automatically on every pull request.
15+
3. **Read our [Code of Conduct](https://events.linuxfoundation.org/about/code-of-conduct/)** — we follow the
16+
Linux Foundation Code of Conduct and are committed to providing a welcoming and respectful community for everyone.
17+
18+
## Find Something to Work On
19+
20+
Not sure where to start? Here are a few ways to find your first contribution:
21+
22+
- **Browse [`good first issue`](https://github.com/search?q=org%3Aironcore-dev+label%3A%22good+first+issue%22+state%3Aopen&type=issues)
23+
labels** — these are issues where maintainers have committed to providing extra guidance.
24+
- **Look for [`help wanted`](https://github.com/search?q=org%3Aironcore-dev+label%3A%22help+wanted%22+state%3Aopen&type=issues)
25+
labels** — these are issues open for community contribution.
26+
- **Improve documentation** — clarify existing docs, fix typos, or add missing content. See the
27+
[documentation conventions](/community/style-guide/documentation) in the style guide.
28+
- **Report a bug** — if you've found an issue, open a GitHub issue with steps to reproduce it.
29+
- **Propose a feature** — open an issue to discuss your idea before starting implementation.
30+
31+
**Tip:** Before working on a larger change, open an issue first to discuss your approach with the maintainers. This
32+
avoids unnecessary work and helps align your contribution with the project's direction.
33+
34+
## Making a Contribution
35+
36+
### 1. Fork and Clone
37+
38+
Fork the repository you want to contribute to and clone it locally:
39+
40+
```shell
41+
git clone git@github.com:<your-username>/<repository>.git
42+
cd <repository>
43+
```
44+
45+
### 2. Create a Branch
46+
47+
Create a feature branch from `main`:
48+
49+
```shell
50+
git checkout -b my-feature
51+
```
52+
53+
If needed, rebase to the current `main` before submitting your pull request:
54+
55+
```shell
56+
git fetch upstream main
57+
git rebase upstream/main
58+
```
59+
60+
### 3. Make Your Changes
61+
62+
- Follow the [coding](/community/style-guide/coding) and [documentation](/community/style-guide/documentation) style guides for code, testing, and documentation standards.
63+
- Keep commits small and focused — each commit should be correct independently.
64+
- Write clear [commit messages](/community/style-guide/coding#commit-messages) that explain *why*, not just *what*.
65+
- Include tests for any new functionality or bug fix.
66+
- Sign off every commit for DCO compliance:
67+
68+
```shell
69+
git commit -s -m "Add support for feature X"
70+
```
71+
72+
### 4. Submit a Pull Request
73+
74+
Push your branch and open a pull request against `main`:
75+
76+
```shell
77+
git push origin my-feature
78+
```
79+
80+
In your pull request description:
81+
- Explain what the change does and why it's needed.
82+
- Reference any related issues (e.g., `Fixes #123`).
83+
- Tag a relevant maintainer if you need a specific reviewer — check the `CODEOWNERS` file in the repository.
84+
85+
### 5. Run Checks
86+
87+
Before submitting, run the project's checks locally to catch issues early. See
88+
[Running tests](/community/style-guide/coding#running-tests) in the coding style guide for details:
89+
90+
```shell
91+
make test # Unit and integration tests
92+
make lint # Linter checks
93+
make verify # Code generation and manifests are up to date
94+
```
95+
96+
## Code Review
97+
98+
All contributions go through code review before merging. Here's what to expect:
99+
100+
- **A maintainer will review your PR** and may request changes. This is normal — reviews improve code quality for
101+
everyone.
102+
- **Address feedback** by pushing additional commits or amending existing ones.
103+
- **Mark resolved comments** as resolved in GitHub and leave a comment when your changes are ready for another look.
104+
105+
Reviews are a collaborative process. Don't hesitate to ask questions or push back if you disagree with feedback —
106+
respectful discussion leads to better outcomes.
107+
108+
## Reporting Issues
109+
110+
We use GitHub issues to track bugs and feature requests. When opening an issue:
111+
112+
- Check if a similar issue already exists.
113+
- Provide enough context to understand and reproduce the problem.
114+
- Use the issue templates provided in each repository when available.
115+
116+
## Licensing
117+
118+
All contributions to IronCore projects are licensed under the
119+
[Apache 2.0 License](http://www.apache.org/licenses/LICENSE-2.0).
120+
121+
## Need Help?
122+
123+
- Ask questions on any issue or pull request — maintainers are happy to help.
124+
- Join our [Slack workspace](https://join.slack.com/t/ironcore-dev/shared_invite/zt-3o0qo3j90-pbqV0io1B~Z~LqeAp4n2Vg)
125+
to chat with the community.
126+
127+
Thank you for contributing to IronCore!

‎docs/community/index.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# Welcome to the IronCore Community!
2+
3+
IronCore is an open-source project built by and for the community. Whether you're a developer, system administrator,
4+
or infrastructure enthusiast, there are many ways to get involved, ask questions, and contribute to the project.
5+
6+
## Get Connected
7+
8+
### Slack
9+
10+
Join our [Slack workspace](https://join.slack.com/t/ironcore-dev/shared_invite/zt-3o0qo3j90-pbqV0io1B~Z~LqeAp4n2Vg) to chat
11+
with maintainers and other community members. It's the best place to ask questions, share ideas, and get help with IronCore.
12+
13+
### GitHub
14+
15+
All IronCore development happens in the open on [GitHub](https://github.com/ironcore-dev). You can:
16+
17+
- Browse the source code and documentation
18+
- Report bugs or request features by opening an [issue](https://github.com/ironcore-dev/ironcore/issues)
19+
- Follow the project's development and roadmap
20+
21+
## Contribute
22+
23+
We welcome contributions of all kinds — from code and documentation to bug reports and feature ideas. If you'd like to
24+
get started, check out our [Contributing Guide](/community/contributing), [Coding Style Guide](/community/style-guide/coding),
25+
and [Documentation Style Guide](/community/style-guide/documentation).
26+
27+
## Code of Conduct
28+
29+
The IronCore community is committed to providing a welcoming and inclusive environment for everyone. We expect all
30+
participants to treat each other with respect and professionalism.

‎docs/community/style-guide/coding.md‎

Lines changed: 171 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,171 @@
1+
# Coding Style Guide
2+
3+
This style guide defines the conventions for contributing code and tests across all IronCore projects.
4+
Following these standards ensures consistency and helps maintainers review contributions efficiently.
5+
6+
## Code Style
7+
8+
### Go Conventions
9+
10+
All IronCore projects are written in Go. We follow the standard Go style guides as our baseline:
11+
12+
- [Effective Go](https://go.dev/doc/effective_go) — the foundational language guide.
13+
- [Go Code Review Comments](https://go.dev/wiki/CodeReviewComments) — the de facto standard for code reviews.
14+
15+
The rules below supplement these upstream guides with IronCore-specific conventions. Do not duplicate what is already
16+
covered upstream — read those guides first.
17+
18+
### Formatting
19+
20+
- Run `gofmt` (or `goimports`) on all code before committing. This is non-negotiable.
21+
- Use your editor or a pre-commit hook to automate formatting.
22+
23+
### Naming
24+
25+
- Follow Go naming conventions: `MixedCaps` for exported identifiers, `mixedCaps` for unexported ones. Never use
26+
underscores in Go names.
27+
- Keep initialisms consistent: `URL` not `Url`, `ID` not `Id`, `HTTP` not `Http`.
28+
- Use descriptive package names. Avoid generic names like `util`, `common`, `helpers`, or `misc`.
29+
- Controller and reconciler types should clearly indicate the resource they manage
30+
(e.g., `MachineReconciler`, `VolumeController`).
31+
32+
### Imports
33+
34+
Organize imports into three groups separated by blank lines:
35+
36+
```go
37+
import (
38+
// Standard library
39+
"context"
40+
"fmt"
41+
42+
// Third-party packages
43+
"sigs.k8s.io/controller-runtime/pkg/client"
44+
45+
// IronCore packages
46+
"github.com/ironcore-dev/ironcore/api/compute/v1alpha1"
47+
)
48+
```
49+
50+
Avoid renaming imports unless there is a name collision.
51+
52+
### Error Handling
53+
54+
- Never discard errors with `_`. Handle every error or explicitly document why it is safe to ignore.
55+
- Return errors as the last return value. Handle errors early and return — keep the happy path at minimal indentation.
56+
- Use lowercase error strings without trailing punctuation: `fmt.Errorf("failed to create machine")`.
57+
- Wrap errors with context: `fmt.Errorf("reconciling machine %s: %w", name, err)`.
58+
59+
### Comments
60+
61+
- Write comments that explain *why*, not *what*. The code itself shows what it does.
62+
- Comments on exported identifiers become godoc — start with the identifier name and write complete sentences.
63+
- If reviewers ask questions about why code is written a certain way, that is a sign that a comment would help.
64+
65+
### Logging
66+
67+
- Use structured logging consistently. Prefer key-value pairs over formatted strings.
68+
- Use appropriate log levels:
69+
- **Error** — the reconciler cannot proceed; requires attention.
70+
- **Info** — significant events (resource created, deleted, reconciled).
71+
- **Debug/V(1)** — detailed information useful for troubleshooting.
72+
73+
### Linting
74+
75+
All projects should use [golangci-lint](https://golangci-lint.run/) with the project's `.golangci.yml` configuration.
76+
Run linters locally before pushing:
77+
78+
```shell
79+
make lint
80+
```
81+
82+
## Testing
83+
84+
Good tests are as important as good code. Tests protect against regressions, document expected behavior, and give
85+
reviewers confidence that changes work correctly.
86+
87+
### Testing Pyramid
88+
89+
IronCore projects use three levels of testing:
90+
91+
| Level | Purpose | Tools |
92+
| --- | --- | --- |
93+
| **Unit tests** | Test individual functions and methods in isolation. | Go standard `testing` package |
94+
| **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) |
95+
| **End-to-end tests** | Test the full system with real components deployed. | [Ginkgo](https://onsi.github.io/ginkgo/) + [Gomega](https://onsi.github.io/gomega/) |
96+
97+
### Writing Tests
98+
99+
- **Table-driven tests** are the preferred pattern for unit tests with multiple input/output cases:
100+
101+
```go
102+
func TestValidateMachineName(t *testing.T) {
103+
tests := []struct {
104+
name string
105+
input string
106+
wantErr bool
107+
}{
108+
{name: "valid name", input: "my-machine", wantErr: false},
109+
{name: "empty name", input: "", wantErr: true},
110+
{name: "name with spaces", input: "my machine", wantErr: true},
111+
}
112+
for _, tt := range tests {
113+
t.Run(tt.name, func(t *testing.T) {
114+
err := ValidateMachineName(tt.input)
115+
if (err != nil) != tt.wantErr {
116+
t.Errorf("ValidateMachineName(%q) error = %v, wantErr %v", tt.input, err, tt.wantErr)
117+
}
118+
})
119+
}
120+
}
121+
```
122+
123+
- **Test names** should be descriptive and specific. Use the pattern `Test<Function>_<scenario>` for unit tests.
124+
- **Assertions** in Ginkgo/Gomega tests should use matchers, not boolean checks:
125+
126+
| Do | Don't |
127+
| --- | --- |
128+
| `Expect(pod.Status.Phase).To(Equal(corev1.PodRunning))` | `Expect(pod.Status.Phase == corev1.PodRunning).To(BeTrue())` |
129+
130+
- **Failure messages** must be actionable. Include what was expected, what was received, and enough context to debug
131+
without re-running:
132+
133+
| Do | Don't |
134+
| --- | --- |
135+
| `"expected Machine %s to be in Running phase, got %s"` | `"wrong phase"` |
136+
137+
### Test Reliability
138+
139+
- Tests must be deterministic. A test that passes 99% of the time is unreliable in CI.
140+
- Use `gomega.Eventually` for polling conditions instead of `time.Sleep`.
141+
- Clean up resources after tests. Use `DeferCleanup` in Ginkgo or `t.Cleanup` in standard tests.
142+
- Keep tests fast. Unit tests should complete in seconds; integration tests in under two minutes.
143+
144+
### Running Tests
145+
146+
Before submitting a pull request, run the full test suite locally:
147+
148+
```shell
149+
make test # Unit and integration tests
150+
make lint # Linter checks
151+
make verify # Code generation and manifests are up to date
152+
```
153+
154+
## Commit Messages
155+
156+
- **Subject line**: imperative mood, max 72 characters, capitalize the first word, no trailing period.
157+
- **Body**: wrap at 72 characters, explain *what* and *why*, separate from the subject with a blank line.
158+
- Reference related issues: `Fixes #123` or `Relates to #456`.
159+
160+
| Do | Don't |
161+
| --- | --- |
162+
| `Add volume snapshot support` | `Added volume snapshot support` |
163+
| `Fix nil pointer in machine reconciler` | `fixed stuff` |
164+
165+
## Pull Requests
166+
167+
- Keep pull requests small and focused — one logical change per PR.
168+
- Separate bug fixes from refactoring from new features.
169+
- Include tests for any new functionality or bug fix.
170+
- Ensure all CI checks pass before requesting review.
171+
- Write a clear PR description explaining what changed and why.

0 commit comments

Comments
 (0)