From 3d46181efa5956ff2eb1665ed59c71447dc432d2 Mon Sep 17 00:00:00 2001 From: Eike Waldt Date: Thu, 19 Mar 2026 15:10:22 +0100 Subject: [PATCH 1/2] feat: new structure Signed-off-by: Eike Waldt On-behalf-of: SAP --- docs/.vitepress/config.mts | 218 ++++++++--- docs/.vitepress/config.mts.backup | 337 ------------------ docs/contributing/building-image.md | 297 ++++++++++++++- docs/contributing/workflow.md | 302 +++++++++++++++- docs/explanation/architecture.md | 24 ++ docs/explanation/design-decisions.md | 24 ++ docs/explanation/flavors-and-features.md | 24 ++ docs/explanation/image-types.md | 24 ++ docs/explanation/index.md | 49 +++ docs/explanation/release-cadence.md | 24 ++ docs/explanation/security-posture.md | 24 ++ docs/explanation/use-cases.md | 24 ++ docs/how-to/choosing-flavors.md | 24 ++ .../how-to/customization/building-features.md | 24 ++ docs/how-to/customization/building-flavors.md | 24 ++ docs/how-to/customization/index.md | 39 ++ docs/how-to/customization/testing-builds.md | 24 ++ docs/how-to/getting-images.md | 24 ++ docs/how-to/index.md | 70 ++++ docs/how-to/initial-configuration.md | 24 ++ docs/how-to/platform-specific/aws.md | 24 ++ docs/how-to/platform-specific/azure.md | 24 ++ docs/how-to/platform-specific/bare-metal.md | 24 ++ docs/how-to/platform-specific/gardener.md | 24 ++ docs/how-to/platform-specific/gcp.md | 24 ++ docs/how-to/platform-specific/index.md | 59 +++ docs/how-to/platform-specific/kvm.md | 24 ++ docs/how-to/platform-specific/lima.md | 24 ++ docs/how-to/platform-specific/oci.md | 24 ++ docs/how-to/platform-specific/openstack.md | 24 ++ docs/how-to/platform-specific/vmware.md | 24 ++ docs/how-to/security/index.md | 40 +++ docs/how-to/security/secure-boot.md | 24 ++ docs/how-to/security/ssh-hardening.md | 24 ++ docs/how-to/security/time-configuration.md | 24 ++ docs/how-to/system-management.md | 24 ++ docs/index.md | 28 +- docs/reference/api/cli.md | 24 ++ docs/reference/api/index.md | 44 +++ docs/reference/api/python-lib.md | 24 ++ docs/reference/feature-glossary.md | 24 ++ docs/reference/flavor-matrix.md | 24 ++ docs/reference/image-formats.md | 24 ++ docs/reference/index.md | 57 +++ docs/reference/kernels-and-modules.md | 24 ++ docs/reference/platform-compatibility.md | 24 ++ docs/reference/releases/index.md | 46 +++ .../reference/releases/maintained-releases.md | 24 ++ docs/reference/releases/release-notes.md | 24 ++ docs/tutorials/first-boot-aws.md | 67 ++++ docs/tutorials/first-boot-azure.md | 24 ++ docs/tutorials/first-boot-bare-metal.md | 24 ++ docs/tutorials/first-boot-gcp.md | 24 ++ docs/tutorials/first-boot-kvm.md | 24 ++ docs/tutorials/first-boot-lima.md | 24 ++ docs/tutorials/first-boot-oci.md | 24 ++ docs/tutorials/first-boot-openstack.md | 24 ++ docs/tutorials/index.md | 40 +++ scripts/migration_tracker.py | 248 +++++++++++++ scripts/repos-config.json | 25 +- scripts/repos-config.local.json | 14 +- scripts/transform_content.py | 24 +- 62 files changed, 2607 insertions(+), 429 deletions(-) delete mode 100644 docs/.vitepress/config.mts.backup create mode 100644 docs/explanation/architecture.md create mode 100644 docs/explanation/design-decisions.md create mode 100644 docs/explanation/flavors-and-features.md create mode 100644 docs/explanation/image-types.md create mode 100644 docs/explanation/index.md create mode 100644 docs/explanation/release-cadence.md create mode 100644 docs/explanation/security-posture.md create mode 100644 docs/explanation/use-cases.md create mode 100644 docs/how-to/choosing-flavors.md create mode 100644 docs/how-to/customization/building-features.md create mode 100644 docs/how-to/customization/building-flavors.md create mode 100644 docs/how-to/customization/index.md create mode 100644 docs/how-to/customization/testing-builds.md create mode 100644 docs/how-to/getting-images.md create mode 100644 docs/how-to/index.md create mode 100644 docs/how-to/initial-configuration.md create mode 100644 docs/how-to/platform-specific/aws.md create mode 100644 docs/how-to/platform-specific/azure.md create mode 100644 docs/how-to/platform-specific/bare-metal.md create mode 100644 docs/how-to/platform-specific/gardener.md create mode 100644 docs/how-to/platform-specific/gcp.md create mode 100644 docs/how-to/platform-specific/index.md create mode 100644 docs/how-to/platform-specific/kvm.md create mode 100644 docs/how-to/platform-specific/lima.md create mode 100644 docs/how-to/platform-specific/oci.md create mode 100644 docs/how-to/platform-specific/openstack.md create mode 100644 docs/how-to/platform-specific/vmware.md create mode 100644 docs/how-to/security/index.md create mode 100644 docs/how-to/security/secure-boot.md create mode 100644 docs/how-to/security/ssh-hardening.md create mode 100644 docs/how-to/security/time-configuration.md create mode 100644 docs/how-to/system-management.md create mode 100644 docs/reference/api/cli.md create mode 100644 docs/reference/api/index.md create mode 100644 docs/reference/api/python-lib.md create mode 100644 docs/reference/feature-glossary.md create mode 100644 docs/reference/flavor-matrix.md create mode 100644 docs/reference/image-formats.md create mode 100644 docs/reference/index.md create mode 100644 docs/reference/kernels-and-modules.md create mode 100644 docs/reference/platform-compatibility.md create mode 100644 docs/reference/releases/index.md create mode 100644 docs/reference/releases/maintained-releases.md create mode 100644 docs/reference/releases/release-notes.md create mode 100644 docs/tutorials/first-boot-aws.md create mode 100644 docs/tutorials/first-boot-azure.md create mode 100644 docs/tutorials/first-boot-bare-metal.md create mode 100644 docs/tutorials/first-boot-gcp.md create mode 100644 docs/tutorials/first-boot-kvm.md create mode 100644 docs/tutorials/first-boot-lima.md create mode 100644 docs/tutorials/first-boot-oci.md create mode 100644 docs/tutorials/first-boot-openstack.md create mode 100644 docs/tutorials/index.md create mode 100755 scripts/migration_tracker.py diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index 73fd56c..87c8916 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -1,9 +1,130 @@ import { defineConfig } from "vitepress"; +// Get base URL from environment variable (for GitHub Pages deployment) +const base = process.env.BASE_URL || '/'; + +// Shared sidebar for all documentation categories +const documentationSidebar = [ + { + text: "Tutorials", + collapsed: true, + items: [ + { text: "Overview", link: "/tutorials/" }, + { text: "First Boot - AWS", link: "/tutorials/first-boot-aws" }, + { text: "First Boot - Azure", link: "/tutorials/first-boot-azure" }, + { text: "First Boot - Bare Metal", link: "/tutorials/first-boot-bare-metal" }, + { text: "First Boot - GCP", link: "/tutorials/first-boot-gcp" }, + { text: "First Boot - KVM", link: "/tutorials/first-boot-kvm" }, + { text: "First Boot - Lima", link: "/tutorials/first-boot-lima" }, + { text: "First Boot - OCI", link: "/tutorials/first-boot-oci" }, + { text: "First Boot - OpenStack", link: "/tutorials/first-boot-openstack" }, + ], + }, + { + text: "How-to Guides", + collapsed: true, + items: [ + { text: "Overview", link: "/how-to/" }, + { text: "Choosing Flavors", link: "/how-to/choosing-flavors" }, + { text: "Getting Images", link: "/how-to/getting-images" }, + { text: "Initial Configuration", link: "/how-to/initial-configuration" }, + { text: "System Management", link: "/how-to/system-management" }, + { + text: "Customization", + collapsed: true, + items: [ + { text: "Overview", link: "/how-to/customization/" }, + { text: "Building Features", link: "/how-to/customization/building-features" }, + { text: "Building Flavors", link: "/how-to/customization/building-flavors" }, + { text: "Testing Builds", link: "/how-to/customization/testing-builds" }, + ], + }, + { + text: "Platform-Specific", + collapsed: true, + items: [ + { text: "Overview", link: "/how-to/platform-specific/" }, + { text: "AWS", link: "/how-to/platform-specific/aws" }, + { text: "Azure", link: "/how-to/platform-specific/azure" }, + { text: "Bare Metal", link: "/how-to/platform-specific/bare-metal" }, + { text: "Gardener", link: "/how-to/platform-specific/gardener" }, + { text: "GCP", link: "/how-to/platform-specific/gcp" }, + { text: "KVM", link: "/how-to/platform-specific/kvm" }, + { text: "Lima", link: "/how-to/platform-specific/lima" }, + { text: "OCI/Containers", link: "/how-to/platform-specific/oci" }, + { text: "OpenStack", link: "/how-to/platform-specific/openstack" }, + { text: "VMware", link: "/how-to/platform-specific/vmware" }, + ], + }, + { + text: "Security", + collapsed: true, + items: [ + { text: "Overview", link: "/how-to/security/" }, + { text: "Secure Boot", link: "/how-to/security/secure-boot" }, + { text: "SSH Hardening", link: "/how-to/security/ssh-hardening" }, + { text: "Time Configuration", link: "/how-to/security/time-configuration" }, + ], + }, + ], + }, + { + text: "Explanation", + collapsed: true, + items: [ + { text: "Overview", link: "/explanation/" }, + { text: "Architecture", link: "/explanation/architecture" }, + { text: "Design Decisions", link: "/explanation/design-decisions" }, + { text: "Flavors and Features", link: "/explanation/flavors-and-features" }, + { text: "Image Types", link: "/explanation/image-types" }, + { text: "Release Cadence", link: "/explanation/release-cadence" }, + { text: "Security Posture", link: "/explanation/security-posture" }, + { text: "Use Cases", link: "/explanation/use-cases" }, + ], + }, + { + text: "Reference", + collapsed: true, + items: [ + { text: "Overview", link: "/reference/" }, + { text: "Feature Glossary", link: "/reference/feature-glossary" }, + { text: "Flavor Matrix", link: "/reference/flavor-matrix" }, + { text: "Image Formats", link: "/reference/image-formats" }, + { text: "Kernels & Modules", link: "/reference/kernels-and-modules" }, + { text: "Platform Compatibility", link: "/reference/platform-compatibility" }, + { + text: "API", + collapsed: true, + items: [ + { text: "Overview", link: "/reference/api/" }, + { text: "CLI", link: "/reference/api/cli" }, + { text: "Python Library", link: "/reference/api/python-lib" }, + ], + }, + { + text: "Releases", + collapsed: true, + items: [ + { text: "Overview", link: "/reference/releases/" }, + { text: "Maintained Releases", link: "/reference/releases/maintained-releases" }, + { text: "Release Notes", link: "/reference/releases/release-notes" }, + ], + }, + ], + }, +]; + // https://vitepress.dev/reference/site-config export default defineConfig({ + base, title: "Garden Linux", // description: "Operating system built for cloud native workloads.", + ignoreDeadLinks: [ + // Ignore dead links in legacy documentation + /\/how-to\/troubleshooting\//, + /localhost/, + /\/projects\/gardenlinux\/02_operators\/deployment/, + ], head: [ [ "link", @@ -33,39 +154,43 @@ export default defineConfig({ dark: ".vitepress/theme/assets/gardenlinux-logo.svg", }, nav: [ - { text: "Home", link: "/" }, - { text: "Quick Start", link: "/users/quickstart" }, + { text: "Start Here", link: "/" }, { - text: "Docs", + text: "Documentation", items: [ { - text: "User Docs", - items: [ - { text: "Quickstart", link: "/users/quickstart" }, - { text: "Installation Guide", link: "/users/installation" }, - { text: "Build an Image", link: "/users/build-image" }, - ], + text: "Tutorials", + link: "/tutorials/", }, { - text: "Technical Documentation", - items: [ - { - text: "Garden Linux", - link: "/projects/gardenlinux/introduction/index", - }, - { text: "Builder", link: "/projects/builder/getting_started" }, - { - text: "Python Library", - link: "/projects/python-gardenlinux-lib/index", - }, - ], + text: "How-to Guides", + link: "/how-to/", }, { - text: "Contributing", - link: "/contributing/", + text: "Explanation", + link: "/explanation/", + }, + { + text: "Reference", + link: "/reference/", + }, + ], + }, + { + text: "Legacy Docs", + items: [ + { + text: "Garden Linux", + link: "/projects/gardenlinux/introduction/index", + }, + { text: "Builder", link: "/projects/builder/getting_started" }, + { + text: "Python Library", + link: "/projects/python-gardenlinux-lib/index", }, ], }, + { text: "Contributing", link: "/contributing/" }, ], // footer: { @@ -74,40 +199,21 @@ export default defineConfig({ // }, sidebar: { - // Default sidebar for root pages - "/": [ - { - text: "Getting Started", - items: [{ text: "Quick Start", link: "/users/quickstart" }], - }, - { - text: "Usage Docs", - items: [ - { text: "Installation Guide", link: "/users/installation" }, - { text: "Build an Image", link: "/users/build-image" }, - ], - }, - { - text: "Technical Documentation", - items: [ - { - text: "Garden Linux", - link: "/projects/gardenlinux/introduction/index", - }, - { text: "Builder", link: "/projects/builder/getting_started" }, - { - text: "Python Library", - link: "/projects/python-gardenlinux-lib/index", - }, - ], - }, + // Shared sidebar for all documentation categories + "/tutorials/": documentationSidebar, + "/how-to/": documentationSidebar, + "/explanation/": documentationSidebar, + "/reference/": documentationSidebar, + + // Contributing section + "/contributing/": [ { text: "Contributing", - collapsed: true, items: [ + { text: "Overview", link: "/contributing/" }, { - text: "Development Environment", - link: "/contributing/dev-environment", + text: "Documentation Guide", + link: "/contributing/documentation-guide", }, { text: "Building an Image", link: "/contributing/building-image" }, { text: "Testing an Image", link: "/contributing/testing-image" }, @@ -117,15 +223,11 @@ export default defineConfig({ text: "Dependency Policy", link: "/contributing/dependency-policy", }, - { - text: "Documentation Guide", - link: "/contributing/documentation-guide", - }, ], }, ], - // Garden Linux project docs + // Legacy documentation (temporary, for backward compatibility) "/projects/gardenlinux/": [ { text: "Introduction", diff --git a/docs/.vitepress/config.mts.backup b/docs/.vitepress/config.mts.backup deleted file mode 100644 index b03c61d..0000000 --- a/docs/.vitepress/config.mts.backup +++ /dev/null @@ -1,337 +0,0 @@ -import { defineConfig } from 'vitepress' -import { fileURLToPath, URL } from 'node:url' - -// https://vitepress.dev/reference/site-config -export default defineConfig({ - title: "Gardenlinux Documentation", - description: "All your documentation need - in one place", - base: process.env.VITE_PUBLIC_BASE_PATH || '', - srcDir: 'docs', - cleanUrls: true, - head: [ - ['link', { rel: 'icon', type: 'image/png', href: '/favicon-96x96.png', sizes: '96x96' }], - ['link', { rel: 'icon', type: 'image/svg+xml', href: '/favicon.svg' }], - ['link', { rel: 'shortcut icon', href: '/favicon.ico' }], - ['link', { rel: 'apple-touch-icon', sizes: '180x180', href: '/apple-touch-icon.png' }], - ['link', { rel: 'manifest', href: '/site.webmanifest' }], - ['meta', {name: 'theme-color', content: '#009f76'}], - ['meta', {property: 'og:type', content: 'website'}], - ['meta', {property: 'og:site_name', content: 'Garden Linux'}], - [ - 'meta', - { - property: 'og:image', - content: 'https://raw.githubusercontent.com/gardenlinux/gardenlinux/main/logo/gardenlinux-logo-black-text.svg' - } - ], - ['meta', {property: 'og:url', content: 'https://gardenlinux.io/'}], - ], - themeConfig: { - // https://vitepress.dev/reference/default-theme-config - logo: { - light: '/gardenlinux-logo.svg', - dark: '/gardenlinux-logo.svg', - }, - nav: [ - { text: 'Home', link: '/' }, - { text: 'Quick Start', link: '/users/quickstart' }, - { - text: 'Docs', - items: [ - { - text: 'User Docs', - items: [ - { text: 'Quickstart', link: '/users/quickstart' }, - { text: 'Installation Guide', link: '/users/installation' }, - { text: 'Build an Image', link: '/users/build-image' } - ] - }, - { - text: 'Technical Documentation', - items: [ - { text: 'Gardenlinux', link: '/projects/gardenlinux/' }, - { text: 'Builder', link: '/projects/builder/features' }, - { text: 'Python Gardenlinux Lib', link: '/projects/python-gardenlinux-lib/' }, - ] - }, - { - text: 'Contributing', link: '/contributing/', - } - ] - }, - ], - socialLinks: [ - { - icon: { - svg: '' - }, - link: 'https://x.com/GardenLinux' - }, - { - icon: { - svg: ' +Learn how to build Garden Linux images and packages for development and contribution purposes. + +## Building Images for Development + +For detailed instructions on building Garden Linux images, see the [Building Custom Flavors](/how-to/customization/building-flavors) guide, which covers: + +- Build requirements and prerequisites +- Basic and advanced build commands +- Cross-architecture builds +- Parallel build options +- Secure boot image generation + +## Building Packages + +Garden Linux packages are built using [the package-build scripts](https://github.com/gardenlinux/package-build). Understanding the package build system is essential for contributing package changes. + +### Package Repository Structure + +Each package has its own GitHub repository following the naming convention `package-{package_name}`. These packages are automatically picked up by [the workflows in the 'repo'](https://github.com/gardenlinux/repo). + +**Examples**: +- **Trivial example**: [`gardenlinux/package-containerd`](https://github.com/gardenlinux/package-containerd) +- **Non-trivial example**: [`gardenlinux/package-openssh`](https://github.com/gardenlinux/package-openssh) + +### Package Build Strategy + +Garden Linux follows a pragmatic approach to package management: + +**Default approach**: Use binary packages as provided by Debian +- Leverages Debian's extensive testing and security processes +- Reduces maintenance burden +- Ensures compatibility with Debian ecosystem + +**Rebuild only when necessary**: Create a `package-{package_name}` repository when: +- Garden Linux-specific patches are required +- Custom build environment is needed +- Package is temporarily unavailable in Debian testing + +### Types of Package Rebuilds + +#### 1. Source from Debian + +Rebuild Debian packages with Garden Linux modifications. + +**Use cases**: +- **Apply patches**: Add Garden Linux-specific patches on top of Debian source +- **Custom build environment**: Rebuild with specific compiler/runtime versions (e.g., newer golang, glibc, gcc) +- **Debian testing gaps**: Package temporarily removed from Debian testing (happens periodically) + +**Example workflow**: +```bash +# Clone package repository +git clone https://github.com/gardenlinux/package-openssh +cd package-openssh + +# Review Garden Linux patches +ls debian/patches/ + +# Build package +./build.sh +``` + +#### 2. Source from Upstream Project + +Package software directly from upstream when Debian doesn't provide suitable packages. + +**Use cases**: +- **Not in Debian**: Software not maintained by Debian +- **Version mismatch**: Debian maintains old version, newer upstream version required +- **Specialized needs**: Garden Linux requires features not in Debian package + +**Example**: +```bash +# Clone package repository +git clone https://github.com/gardenlinux/package-{upstream-software} +cd package-{upstream-software} + +# Check upstream source +cat debian/watch # Upstream version tracking + +# Build from upstream +./build.sh +``` + +#### 3. Native Source + +Package software developed and maintained by Garden Linux team. + +**Use cases**: +- **Garden Linux-specific tools**: Software developed by Garden Linux team +- **Integration components**: Tools for Garden Linux system integration +- **Custom utilities**: Garden Linux-specific system utilities + +**Example**: +```bash +# Clone native package +git clone https://github.com/gardenlinux/package-{native-tool} +cd package-{native-tool} + +# Source is maintained in repository +ls src/ + +# Build native package +./build.sh +``` + +## Package Development Workflow + +### Set Up Package Development Environment + +1. **Install build dependencies**: + ```bash + sudo apt install build-essential devscripts debhelper + ``` + +2. **Clone package repository**: + ```bash + git clone https://github.com/gardenlinux/package-{package_name} + cd package-{package_name} + ``` + +3. **Review package structure**: + ```bash + # Debian packaging files + ls debian/ + + # Build scripts + ls *.sh + + # Package-specific patches + ls debian/patches/ + ``` + +### Make Package Changes + +1. **Create feature branch**: + ```bash + git checkout -b feature/my-package-change + ``` + +2. **Modify source or patches**: + ```bash + # Add new patch + vim debian/patches/my-fix.patch + + # Update patch series + echo "my-fix.patch" >> debian/patches/series + ``` + +3. **Update changelog**: + ```bash + dch -i "Description of changes" + ``` + +4. **Test build locally**: + ```bash + ./build.sh + ``` + +### Submit Package Contributions + +1. **Commit changes**: + ```bash + git add debian/ + git commit -m "package: Add fix for issue XYZ" + ``` + +2. **Push and create PR**: + ```bash + git push origin feature/my-package-change + # Create pull request on GitHub + ``` + +3. **CI/CD validation**: + - Automated builds run on PR + - Package builds must succeed + - Tests must pass + +## Testing Package Changes + +### Local Testing + +Test your package changes before submitting: + +```bash +# Build package +./build.sh + +# Install locally in test environment +sudo dpkg -i ../package-name_version_arch.deb + +# Verify functionality +# ... test your changes ... + +# Remove test package +sudo apt remove package-name +``` + +### Integration Testing + +Test packages within Garden Linux image: + +```bash +# Build image with modified package +# (assuming package in local repo) +./build kvm-gardener_dev-amd64 + +# Test in QEMU +# ... verify package changes in running system ... +``` + +## Package Repository Automation + +The [`gardenlinux/repo`](https://github.com/gardenlinux/repo) repository contains workflows that: + +- Monitor package repositories for changes +- Trigger automated builds +- Publish packages to Garden Linux repository +- Maintain package metadata and dependencies + +**Package updates are automated**: +1. Changes merged to package repository +2. Workflow detects change +3. Package builds automatically +4. Published to Garden Linux APT repository +5. Available in next image builds + +## Best Practices + +### Package Maintenance + +- **Minimal changes**: Only rebuild when necessary +- **Document patches**: Clear commit messages and patch descriptions +- **Test thoroughly**: Build and test before submitting +- **Follow Debian policy**: Adhere to [Debian Policy](https://www.debian.org/doc/debian-policy/) +- **Version carefully**: Use appropriate version suffixes (e.g., `+gardenlinux1`) + +### Security Considerations + +- **Security patches**: Apply security fixes promptly +- **Upstream tracking**: Monitor upstream security advisories +- **Testing**: Verify security fixes don't introduce regressions +- **Documentation**: Document security-related changes clearly + +## Troubleshooting + +### Build Fails + +**Missing dependencies**: +```bash +# Install build dependencies +sudo apt build-dep package-name + +# Or install from debian/control +mk-build-deps -i debian/control +``` + +**Patch doesn't apply**: +```bash +# Refresh patches for new upstream version +quilt push -a +quilt refresh +``` + +### Package Won't Install + +**Dependency issues**: +```bash +# Check dependencies +dpkg-deb -I package-name.deb + +# Install with dependencies +sudo apt install -f ./package-name.deb +``` + +## Next Steps + +- **Test images**: [Testing an Image](/contributing/testing-image) +- **Contribution workflow**: [Contribution Workflow](/contributing/workflow) +- **Code style**: [Code Style Guide](/contributing/code-style) +- **Build flavors**: [Building Custom Flavors](/how-to/customization/building-flavors) + +## Related Documentation + +- **Explanation**: [Architecture](/explanation/architecture) - Build system design +- **Reference**: [Feature Glossary](/reference/feature-glossary) - Available features +- **How-to**: [Testing Custom Builds](/how-to/customization/testing-builds) - Testing procedures diff --git a/docs/contributing/workflow.md b/docs/contributing/workflow.md index b850381..3f0c7b8 100644 --- a/docs/contributing/workflow.md +++ b/docs/contributing/workflow.md @@ -1,5 +1,303 @@ +--- +title: "Contribution Workflow" +description: "Git workflow, GitHub workflows, and contribution process for Garden Linux" +category: "contributing" +tags: ["workflow", "git", "github", "ci-cd", "contribution"] +--- + # Contribution Workflow -Learn about the contribution workflow for Garden Linux. +Learn about the Git workflow, GitHub Actions pipelines, and contribution process for Garden Linux. + +## Git Workflow + +### Fork and Clone + +1. **Fork the repository**: + - Go to [github.com/gardenlinux/gardenlinux](https://github.com/gardenlinux/gardenlinux) + - Click "Fork" button + - Select your GitHub account + +2. **Clone your fork**: + ```bash + git clone https://github.com/YOUR-USERNAME/gardenlinux.git + cd gardenlinux + ``` + +3. **Add upstream remote**: + ```bash + git remote add upstream https://github.com/gardenlinux/gardenlinux.git + git fetch upstream + ``` + +### Create Feature Branch + +Create a branch for your changes: + +```bash +# Update main branch +git checkout main +git pull upstream main + +# Create feature branch +git checkout -b feature/my-improvement + +# Or for bug fixes +git checkout -b fix/issue-123 +``` + +**Branch naming conventions**: +- `feature/` - New features or enhancements +- `fix/` - Bug fixes +- `docs/` - Documentation changes +- `refactor/` - Code refactoring +- `test/` - Test additions or modifications + +### Make Changes + +1. **Make your changes**: + - Edit files + - Follow [Code Style](/contributing/code-style) guidelines + - Add tests if applicable + +2. **Test locally**: + ```bash + # Build image + ./build kvm-gardener_dev-amd64 + + # Run tests + make test + ``` + +3. **Commit changes**: + ```bash + git add . + git commit -m "feat: Add new feature XYZ" + ``` + +**Commit message format**: +``` +: + + + +