Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
163 lines (106 loc) · 5.47 KB

CONTRIBUTING.md

File metadata and controls

163 lines (106 loc) · 5.47 KB
Raw

Contributing Guide

Thank you for your interest in contributing to Halo. As a contributor, you should agree that:

a. The producer can adjust the open-source agreement to be more strict or relaxed as deemed necessary. b. Your contributed code may be used for commercial purposes, including but not limited to its cloud business operations.

Pull requests to this repository are restricted to project maintainers. We are not accepting pull requests from external contributors at this time. Bug reports, feature proposals, and discussions are still welcome.

This document explains how to share feedback and the development workflow for maintainers, including code, tests, and documentation updates.

Before You Start

  • For bugs, new features, or major behavior changes, please open an issue with reproduction steps or a clear description of the proposal.
  • Opening an issue does not grant permission to submit a pull request; PR creation remains restricted to maintainers.
  • If your report is not about the core project itself (for example, deployment questions), please use Discussions instead of Issues.

Development Environment

This repository mainly contains:

  • Backend and platform modules built with Gradle.
  • Frontend code in ui, managed with pnpm workspaces.

Prerequisites

  • Git
  • JDK (version compatible with the project build)
  • Node.js and pnpm (see ui/package.json for the current package manager)

Maintainer Development Workflow

The following pull request workflow is for project maintainers.

1. Fork and Clone

Fork this repository, then clone your fork:

git clone https://github.com/{YOUR_USERNAME}/{REPOSITORY}.git
cd {REPOSITORY}

2. Add Upstream Remote

git remote add upstream https://github.com/halo-dev/halo.git
git fetch upstream

3. Create a Branch

Use a focused branch name that reflects your change:

git checkout -b feat/short-description

4. Implement and Validate

Run relevant checks before opening a PR.

Backend and general checks (including Spotless):

./gradlew spotlessApply
./gradlew spotlessCheck
./gradlew clean check

Install the pre-push hook once to run Spotless checks automatically before git push:

./gradlew spotlessInstallGitPrePushHook

If spotlessCheck fails, run ./gradlew spotlessApply, review the formatting changes, and re-run checks.

Frontend checks (in ui):

cd ui
pnpm install
pnpm build:packages
pnpm lint
pnpm typecheck
pnpm test:unit

5. Commit and Push

git push origin <your-branch>

6. Open a Pull Request

Open a PR from your branch to main and fill out the PR template carefully:

  • Describe what changed and why.
  • Link related issues (for example, Fixes #123).
  • Add release note content or NONE when no user-facing change is introduced.
  • Add proper /kind labels as requested in the template.

AI-Assisted Contribution Policy

We encourage the use of AI Agents to assist with code generation, refactoring, and design exploration. AI-assisted development is a powerful tool that can improve productivity and code quality when used responsibly.

However, you are personally responsible for every line of code you submit. AI-generated code must be treated as a draft that requires your thorough review and understanding.

If you used AI tools, please follow these rules:

  • Review all AI-generated content before submission.
  • Verify correctness, security, performance, and maintainability.
  • Ensure generated code follows project conventions and architecture.
  • Remove low-quality or redundant generated code.
  • Mention AI assistance in your PR description when AI materially contributed to the final changes.

In short: AI assistance is allowed, but unreviewed AI output is not acceptable.

OpenSpec Workflow for Feature and API Changes

For functional changes or API changes (new endpoints, breaking changes, or behavioral modifications), you must use OpenSpec to create a proposal before implementation.

OpenSpec is a spec-driven development workflow that helps align design intent between humans and AI before coding begins.

For detailed documentation, visit: https://github.com/Fission-AI/OpenSpec/tree/main/docs

Why OpenSpec?

  • Design alignment: Forces upfront design thinking before coding, reducing rework.
  • Clear scope: The proposal serves as a contract between the contributor, reviewers, and AI tools.
  • Traceability: Every change has a documented rationale and decision history.
  • Consistency: Ensures AI-generated implementations follow the project's agreed-upon design.
  • Review efficiency: Reviewers can focus on high-level design before line-by-line code review.

Testing Expectations

  • Add or update tests whenever you change behavior.

Coding Standards

  • Follow the project coding style guide: https://docs.halo.run/developer-guide/core/code-style
  • Keep changes focused and avoid unrelated refactors in the same PR.
  • Run ./gradlew spotlessApply before pushing changes outside ui.
  • Spotless does not format files under ui; continue to run frontend lint/typecheck/test commands there.

Keep Your Fork Updated

Before starting new work, sync your branch with upstream:

git fetch upstream
git checkout main
git merge upstream/main
git push origin main

Need Help?

  • Open an issue for confirmed bugs and feature proposals.
  • Use Discussions for general questions and usage/deployment topics.

Thanks again for helping improve Halo.