# How to Contribute to CasaOS Development and Submit Patches: A Complete Guide > Learn how to contribute to CasaOS development and submit patches to the IceWhaleTech/CasaOS repository. Follow our guide to fork, set up your environment, and submit a pull request. - Repository: [IceWhale/CasaOS](https://github.com/IceWhaleTech/CasaOS) - Tags: how-to-guide - Published: 2026-06-27 --- **To contribute to CasaOS development, fork the IceWhaleTech/CasaOS repository, configure a Go 1.17+ and Node.js environment, develop your feature with accompanying unit tests, and submit a pull request following the project's CI and review workflow.** Contributing to CasaOS requires understanding its dual-stack architecture that combines Go-based backend services with a Node.js frontend. The official development guide in [`DEVELOPING.md`](https://github.com/IceWhaleTech/CasaOS/blob/main/DEVELOPING.md) and the contributing section of [`README.md`](https://github.com/IceWhaleTech/CasaOS/blob/main/README.md) outline specific workflows designed to maintain code quality across the IceWhaleTech/CasaOS repository. ## Prerequisites and Development Environment Setup Before writing code, you must configure your local environment to handle both the Go backend and the Yarn-based UI workspace. ### Forking and Cloning the Repository Start by creating a personal fork of the repository using GitHub's fork button. Then clone your fork with submodule support to ensure you capture all dependencies: ```bash git clone --recurse-submodules --remote-submodules \ https://github.com//CasaOS.git cd CasaOS ``` According to the development guidelines in [`DEVELOPING.md`](https://github.com/IceWhaleTech/CasaOS/blob/main/DEVELOPING.md), the project should reside under `$GOPATH/github.com//` to maintain compatible import paths. ### Installing Dependencies CasaOS requires **Go ≥ 1.17**, **Yarn**, and **Node.js**. Install these via your system package manager, then initialize the frontend workspace: ```bash cd UI yarn install yarn build cd .. go get ``` The `UI` directory operates as a separate Yarn workspace containing the frontend assets, while the root directory contains the Go modules that power the backend services. ## Writing Code and Tests for CasaOS CasaOS follows a service-oriented architecture where business logic resides in the `service/` directory and HTTP handlers are defined in `route/v2/`. ### Creating Services and Handlers New features typically involve adding service logic in `service/` and corresponding handlers. For example, to add a new greeting endpoint, create [`service/hello.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/service/hello.go): ```go package service import ( "github.com/labstack/echo/v4" ) // HelloHandler returns a friendly greeting. func HelloHandler(c echo.Context) error { return c.JSON(200, map[string]string{"msg": "Hello, CasaOS!"}) } ``` Reference existing implementations like [`service/file.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/service/file.go) to understand the project's patterns for error handling and context management. ### Adding Unit Tests Every service change requires corresponding tests. Follow the pattern established in [`service/file_test.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/service/file_test.go) using the `testify/assert` package: ```go package service import ( "net/http/httptest" "testing" "github.com/labstack/echo/v4" "github.com/stretchr/testify/assert" ) func TestHelloHandler(t *testing.T) { e := echo.New() req := httptest.NewRequest("GET", "/hello", nil) rec := httptest.NewRecorder() c := e.NewContext(req, rec) if assert.NoError(t, HelloHandler(c)) { assert.Equal(t, 200, rec.Code) assert.Contains(t, rec.Body.String(), `"msg":"Hello, CasaOS!"`) } } ``` Run the full test suite locally to verify your changes do not break existing functionality: ```bash go test ./... ``` ### Registering API Routes Connect your handler to the HTTP router by modifying [`route/v2/route.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/route/v2/route.go). The Echo framework instances defined here handle all API routing: ```go e.GET("/hello", service.HelloHandler) ``` This registration pattern mirrors existing endpoints in [`route/v2/file.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/route/v2/file.go), ensuring consistency across the API surface. ## Submitting Patches and Opening Pull Requests Once your code passes local testing, prepare your submission for review. ### Committing Changes and Pushing to Your Fork Create a descriptive feature branch rather than committing directly to `main`: ```bash git checkout -b feat/add-hello-endpoint ``` Write clear commit messages that describe the change scope. Then push to your fork: ```bash git add . git commit -m "feat: add hello endpoint for system status" git push origin feat/add-hello-endpoint ``` ### Opening a Pull Request Against Main Navigate to your fork on GitHub and open a pull request against `IceWhaleTech/CasaOS:main`. The repository includes a pull request template at [`.github/PULL_REQUEST_TEMPLATE.md`](https://github.com/IceWhaleTech/CasaOS/blob/main/.github/PULL_REQUEST_TEMPLATE.md) that prompts you to: - Describe the motivation and implementation details - Link related issues - Confirm that `go test ./...` passes locally ### Responding to CI and Reviewer Feedback The CI pipeline defined in `.github/workflows/*.yml` automatically executes `go vet`, `go test`, and lint checks on every pull request. If checks fail, amend your branch and push additional commits—the PR updates automatically. Maintainers may request architectural changes or additional test coverage before approving the merge. ## Summary - **Fork and clone** the CasaOS repository with `--recurse-submodules` to ensure complete dependency retrieval. - **Configure your environment** with Go 1.17+, Node.js, and Yarn, building the UI workspace before running the backend. - **Develop using the service pattern** in `service/`, following examples like [`service/file.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/service/file.go) and testing with `testify/assert` patterns. - **Register routes** in [`route/v2/route.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/route/v2/route.go) to expose new functionality through the Echo framework. - **Submit PRs** against the `main` branch after verifying `go test ./...` passes and adhering to the template in [`.github/PULL_REQUEST_TEMPLATE.md`](https://github.com/IceWhaleTech/CasaOS/blob/main/.github/PULL_REQUEST_TEMPLATE.md). ## Frequently Asked Questions ### What are the system requirements for CasaOS development? You need **Go version 1.17 or higher**, **Node.js**, and **Yarn** installed on your system. The repository must be cloned into your `$GOPATH` directory structure (specifically under `$GOPATH/github.com//`) to satisfy Go module requirements and ensure the UI workspace builds correctly alongside the backend. ### How do I run the test suite locally before submitting a patch? Execute `go test ./...` from the repository root to run all Go unit tests. If you modified UI components, run the appropriate Yarn test commands within the `UI/` directory. The CI pipeline also runs `go vet ./...` and linting checks, so verifying these locally prevents review delays. ### Where should I register new API endpoints in the CasaOS codebase? Register new HTTP handlers in [`route/v2/route.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/route/v2/route.go) using the Echo framework instance. For example, add `e.GET("/hello", service.HelloHandler)` alongside existing routes. This centralizes API versioning and middleware application, following the architectural pattern established in the v2 routing layer. ### Does CasaOS require specific commit message formats? While the repository follows conventional commit style (`feat:`, `fix:`, `docs:`), the primary requirement is clarity and specificity. Your commit message should explain what changed and why, referencing any related issues. The pull request template provides additional guidance on describing changes for the maintainers.