Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions src/app/_components/RichCard.jsx
Original file line number Diff line number Diff line change
Expand Up @@ -54,9 +54,9 @@ export const RichCardOption = ({ icon, title, description, badge, href }) => {
</div>
</div>

<p className="mt-3 text-sm text-gray-600 dark:text-gray-400">
<div className="mt-3 text-sm text-gray-600 dark:text-gray-400">
{description}
</p>
</div>
</Link>
)
}
7 changes: 3 additions & 4 deletions src/app/community/page.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -17,8 +17,8 @@ Join the SpaceDF community! Connect with other users, get help, share experience
}
title="Community Forum"
href="https://forum.df.technology/"
>
</Cards.Card>
/>


<Cards.Card
icon={
Expand All @@ -28,8 +28,7 @@ Join the SpaceDF community! Connect with other users, get help, share experience
}
title="Discord Server"
href="https://discord.gg/HxCTyMCzuK"
>
</Cards.Card>
/>
</Cards>

## Why Join Our Community?
Expand Down
56 changes: 56 additions & 0 deletions src/content/contributing/index.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
---
title: Contributing
asIndexPage: true
---

import { RichCardOptions, RichCardOption } from "@/app/_components/RichCard.jsx"

# Contributing to SpaceDF

First off, thank you for considering contributing to SpaceDF! It's people like you who make SpaceDF such a powerful open-source tool for everyone.

Whether you are fixing a bug, improving documentation, or proposing new features, your help is welcome. Use the guide below to find your way around our development process.

## 🛠 How can you help?

<RichCardOptions>
<RichCardOption
icon={
<div
className="w-2/3 text-center"
>
🚀
</div>
}
title="Release Workflow"
badge="Policy"
description={<p>Learn how we tag versions for <code>spacedf-core</code> and submodules. Understand the promotion flow from <b>latest</b> to <b>stable</b>.</p>}
href="/docs/contributing/release-versioning"
/>

<RichCardOption
icon={
<div
className="w-2/3 text-center"
>
💻
</div>
}
title="Technical Setup"
description={<p>How to clone <code>spacedf-core</code>, setup your Docker environment, and run services locally for development.</p>}
href="/docs/getting-started/self-hosting/docker"
/>
</RichCardOptions>

---
## 🚦 Quick Rules for Contributors

To keep the project healthy, please follow these simple rules:

1. **Atomic Commits:** Keep your Pull Requests focused. One feature/fix per PR is easier to review.
2. **Tagging:** If you are working on a service, ensure your tag follows our `X.Y.Z` SemVer policy.
3. **Tests:** Ensure that your changes do not break the integration tests in `spacedf-core`.

---

> **Tip:** If you're new to the project, look for the **"good first issue"** label in our repository!
148 changes: 148 additions & 0 deletions src/content/contributing/release-versioning.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,148 @@
---
title: Release & Versioning
---

import { CardInfo } from "@/app/_components/CardInfo.jsx"
import {
NumberOfContent,
NumberWithMdx
} from "@/app/_components/NumberOfContent.jsx"

# SpaceDF Release & Versioning Strategy

This document defines how we manage versions across the **SpaceDF ecosystem**, ensuring that both **core developers** and **self-hosting users** have a reliable, predictable experience.

<CardInfo classNames={{
container: "!mt-6 !p-3 shadow-none",
title: "!text-base",
description: "!text-base"
}}
>
<>
**🔁 Predictability:** Developers should know **exactly** which code is running in any environment.<br/>
**🛡️ Safety:** The `stable` alias is a **certified version** that has passed **all integration tests**.<br/>
**🧩 Independence:**<br/>
<span className="ml-6">- Submodules (services) are **versioned independently**</span><br/>
<span className="ml-6">- `spacedf-core` acts as the **orchestrator / umbrella**</span>
</>
</CardInfo>

## Versioning Formats

### 1. Submodules (e.g., `auth-svc`, `spacedf-dashboard`)
We follow [Semantic Versioning (SemVer)](https://semver.org/) for individual services.
- Format: `X.Y.Z` (e.g., `1.4.1`)
- Hotfixes: `X.Y.Z-rcX` (e.g., `1.4.1-rc1`).

### 2. Spacedf-Core (The Umbrella)
We follow [Calendar Versioning (CalVer)](https://calver.org/) to represent a specific snapshot of the entire system.
- Format: `YYYY.MM.DD` (e.g., `2026.02.06`)
- Hotfixes: `YYYY.MM.DD-rcX` (e.g., `2026.02.06-rc1`).

## Promotion Workflow (`latest` → `stable`)
To avoid breaking local environments when using Docker images, we use a **Promotion** logic.

### 1. Service Development (`latest`)
When a developer pushes a change to a service (e.g., `auth-svc`):

<NumberWithMdx number={1} className="mt-3">
CI builds the image: `auth-svc:1.4.1`.
</NumberWithMdx>

<NumberWithMdx number={2}>
The **alias** `auth-svc:latest` is updated to point to `1.4.1`.
</NumberWithMdx>

<CardInfo classNames={{
container: "!mt-6 !p-3 shadow-none",
title: "!text-base",
description: "!text-sm"
}}
title="🔴 Risk: High"
>
This version is **Bleeding Edge** and might not have been integration-tested with other services.
</CardInfo>

### 2: Integration Testing
We update `spacedf-core` (the docker-compose or manifest) to use the new service version.
- **Action:** Run full suite integration tests.
- **Environment:** Staging/Test environment using `spacedf-core:2026.02.06-rc1`.

### 3: Certification (`stable`)
<NumberWithMdx number={1} className="mt-3">
Tag the core as stable: `spacedf-core:2026.02.06`.
</NumberWithMdx>
<NumberWithMdx number={2}>
Update the **alias** `auth-svc:stable` to point to `1.4.1`.
</NumberWithMdx>
<NumberWithMdx number={3}>
Self-hosting users on the `stable` track now receive the update safely.
</NumberWithMdx>

## Practical Case Studies

### Case 1: Deploying a New Feature
<NumberWithMdx number={1} className="mt-3">
Merge feature to `auth-svc`. CI tags it `1.5.0` and updates `latest`.
</NumberWithMdx>
<NumberWithMdx number={2}>
Update `spacedf-core` to point to `auth-svc:1.5.0`.
</NumberWithMdx>
<NumberWithMdx number={3}>
Integration tests pass. Tag `spacedf-core:2026.02.07`.
</NumberWithMdx>

<CardInfo classNames={{
container: "!mt-6 !p-3 shadow-none",
title: "!text-base",
description: "!text-base"
}}
>
<>
**🏁 Result:** `latest` users got it immediately; `stable` users got it only after the Core release.
</>
</CardInfo>

### Case 2: Emergency Hotfix

<CardInfo classNames={{
container: "!mt-6 !p-3 shadow-none",
title: "!text-base",
description: "!text-base"
}}
>
<>
**💥 Issue:** Bug found in `auth-svc:1.5.0`.
</>
</CardInfo>

<NumberWithMdx number={1} className="mt-3">
Developer fixes and tags `auth-svc:1.5.1-rc1`.
</NumberWithMdx>
<NumberWithMdx number={2}>
Test the RC image specifically.
</NumberWithMdx>
<NumberWithMdx number={3}>
If fixed, tag `auth-svc:1.5.1` and release `spacedf-core:2026.02.07-rc1`.
</NumberWithMdx>

## Docker Image Reference Table

| Tag Alias | Target Audience | Stability | Description |
|---------------|-----------------------------|-----------|-------------|
| `latest` | Core Contributors | 🔴 Low | Automated build from every merge to `main`. |
| `stable` | Self-hosters / Production | 🟢 High | Points to the last version that passed all Integration Tests. |
| `YYYY.MM.DD` | Enterprise / Fixed | 🟢 High | A specific, immutable point-in-time release. |

<CardInfo classNames={{
container: "!mt-6 !p-3 shadow-none",
title: "!text-base",
description: "!text-sm"
}}
title="❓ Why this works"
>

1. **No more broken "latest":** Core developers can still use `latest` to see changes immediately, but they are aware of the risk.<br/>
2. **Easy Rollbacks:** If a new stable alias fails, we simply point the alias back to the previous version number (e.g., 1.4.0) without needing to rebuild code.<br/>
3. **Clarity:** The distinction between `spacedf-core` (the platform) and `submodules` (the `components`) is clear to anyone reading the docs.
</CardInfo>