Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
139 lines (97 loc) · 6.13 KB

CONTRIBUTING.md

File metadata and controls

139 lines (97 loc) · 6.13 KB

Contributing to AgentCube

Thank you for your interest in improving AgentCube! This guide outlines how to get started, the workflow we follow, and the expectations for contributors. The structure closely follows the Volcano contributor guide, with adjustments for the AgentCube project.

👋 How to Get Involved

  • Join the conversation on GitHub:
    • Issues for bug reports and feature requests
    • Discussions for design questions and ideas
  • Review the code of conduct before participating

Contribution Workflow

1. Pick or Propose Work

  • Search open issues labeled good first issue or help wanted
  • If you have a new idea, open an issue describing the motivation, proposal, and alternatives
  • For large changes, propose an enhancement in Discussions first to get feedback

2. Set Up Your Environment

  • Install Go (version listed in go.mod)
  • Clone the repository and ensure scripts in Makefile run locally:
    • make lint
    • make test
    • make build

3. Create a Working Branch

# from the repo root
git checkout main
git pull origin main
git checkout -b feat/<short-description>

4. Develop with Tests

  • Follow Go best practices and respect existing module structure under pkg/ and cmd/
  • Maintain backwards compatibility for user-facing APIs (CRDs, CLI, HTTP schemas)
  • Add unit tests in the relevant *_test.go files or integration tests under test/
  • Run make lint and make test before submitting your changes

5. Commit Conventions

  • Use clear, descriptive commit messages: component: summary
  • Reference issues with Fixes #<issue-number> or Refs #<issue-number> when applicable
  • Sign off your commits if required by your employer/company policies

6. Keep Your Branch Up to Date

  • Rebase frequently on main to reduce merge conflicts:
git fetch origin
git rebase origin/main
  • Resolve conflicts locally and rerun tests after rebasing

7. Open a Pull Request

  • Push your branch and create a PR against main
  • Fill in the PR template, covering:
    • Problem statement
    • Summary of changes
    • Testing performed
    • Screenshots/logs if relevant
  • Link related issues or discussions for context
  • Request review from maintainers or area owners (see the OWNERS directories)

8. Code Review

To make it easier for your PR to receive reviews, consider the reviewers will need you to:

  • follow good coding guidelines.
  • write good commit messages.
  • break large changes into a logical series of smaller patches which individually make easily understandable changes, and in aggregate solve a broader issue.
  • label PRs with appropriate reviewers: to do this read the messages the bot sends you to guide you through the PR process.

9. Address Review Feedback

  • Be responsive to comments and iterate quickly
  • Reply to each comment once addressed
  • Squash commits if asked by reviewers to keep history clean

10. Celebrate the Merge

  • Once the PR is approved and checks are green, the maintainer will merge it
  • Your contribution becomes part of the AgentCube history!

Coding Standards

  • Follow Go gofmt formatting automatically (run make fmt)
  • Maintain consistent log semantics via the shared logging packages under pkg/
  • Keep public API changes backward compatible; update CRDs and generated clients when fields change (make generate)
  • Document new features under docs/ and update READMEs/examples when behavior changes

AI Guidance

Using AI tools to help write your PR is acceptable, but as the author, you are responsible for understanding every change. Do not leave the first review of AI generated changes to the reviewers, verify the changes (code review, testing, etc.) before submitting your PR. Reviewers may ask questions about your AI-assisted code, and if you cannot explain why a change was made, the PR will be closed. When responding to review comments, please do so without relying on AI tools. Reviewers want to engage directly with you, not with generated responses. If you used AI tools in preparing your PR, please disclose this in the "Special notes for your reviewer" section. All contributions must follow the contributions policies and use commit messages that align with the policy. Large AI generated PRs and AI generated commit messages are discouraged.

Testing Guidelines

  • Unit tests are mandatory for new functionality and bug fixes
  • Use table-driven tests where appropriate for clarity
  • For concurrency-sensitive code, add race detector checks (go test -race ./...)
  • Integration tests should target scenarios under test/ or example/

Documentation Expectations

  • Update relevant docs under docs/
  • Provide getting-started examples if introducing new CRDs or CLI commands
  • Refresh charts/examples under example/ when changing deployments
  • Include release notes summary for significant changes (tag release-note) in PRs

Governance and Ownership

  • Maintainers are listed in the top-level OWNERS file and OWNERS files in subdirectories
  • Subsystem owners review and approve changes in their areas
  • Major design decisions go through design docs in docs/design/

Tooling

  • make lint runs linters (golangci-lint)
  • make test runs unit tests
  • make e2e runs the full E2E test suite
  • make build-all produces all component binaries (workloadmanager, agentd, agentcube-router) under bin/
  • make generate regenerates codegen artifacts (CRDs, DeepCopy methods)
  • make gen-client regenerates client-go code
  • make gen-all regenerates all codegen artifacts

Security Reporting

  • For sensitive issues, email volcano-security@googlegroups.com instead of filing a public issue
  • Provide steps to reproduce, affected components, and impact assessment

License

By contributing, you agree that your contributions will be licensed under the Apache 2.0 License. See LICENSE for details.