Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
134 lines (89 loc) · 4.16 KB

CONTRIBUTING.md

File metadata and controls

134 lines (89 loc) · 4.16 KB
Raw

How to Contribute

We welcome contributions to AX!

Before You Begin

Sign our Contributor License Agreement

All submissions to this project need to follow Google’s Contributor License Agreement (CLA), which covers any original work of authorship included in the submission. This doesn't prohibit the use of coding assistance tools, including tool-, AI-, or machine-generated code, as long as these submissions abide by the CLA's requirements.

You (or your employer) retain the copyright to your contribution; this simply gives us permission to use and redistribute your contributions as part of the project.

If you or your current employer have already signed the Google CLA (even if it was for a different project), you probably don't need to do it again. Visit https://cla.developers.google.com/ to see your current agreements or sign a new one.

Community Guidelines

This project follows Google's Open Source Community Guidelines.

Code Reviews

All submissions, including submissions by project members, require review. We use GitHub pull requests for this purpose. Consult GitHub Help for more information on using pull requests.

Every pull request to main needs one approving review and a passing build-and-test check before it can be merged. A push after an approval needs a fresh approval.

When you start on an issue or pull request, assign yourself to it, so others know it is being worked on.

Merging

  • Pull requests from project members: The author merges once the pull request is approved and CI is green. The author knows when a change is ready, and is the one who rebases when pull requests have to land in order.
  • Pull requests from external contributors: The reviewer who approves also merges, since external contributors cannot merge.

Development Workflow

Prerequisites

  • Go 1.27+
  • ko (for building and deploying control plane images)
  • Docker or Podman (for building the Linux task-runner container image)
  • A Kubernetes cluster with Agent Substrate installed

Building Binaries

Build all local binaries (bin/ax, bin/ax-server):

make build

Or install the ax CLI directly into $(go env GOPATH)/bin:

make install

Make sure that $(go env GOPATH)/bin is on your $PATH:

export PATH="$PATH:$(go env GOPATH)/bin"

Running Tests

Run all unit and integration tests (including the mock Substrate gRPC server and API server tests):

make test

Or run via go test:

go test -v ./...

Building the Task Runner Image

Cross-compile the task runner for linux/amd64 and package the container image:

make build-task-runner

To build and push to a remote container registry:

make push-task-runner TASK_RUNNER_REPO=gcr.io/<your-project>/ax-task-runner

Deploying to Kubernetes

Deploy Redis and server components to your cluster in the ax-system namespace:

make deploy AX_IMAGE_REPO=gcr.io/<your-project>/ax-images

Creating a Pull Request

  1. Fork and Clone the Repository: Fork google/ax on GitHub, then clone your fork. Replace YOUR_USERNAME with your GitHub username:

    git clone git@github.com:YOUR_USERNAME/ax.git
cd ax
git remote add upstream git@github.com:google/ax.git

  2. Ensure main is up to date:

    git fetch upstream
git checkout main
git merge --ff-only upstream/main

  3. Create a feature branch:

    git checkout -b my-feature

  4. Make changes and verify:

    • Run tests: make test
    • Ensure clean modules: go mod tidy and verify with git diff --exit-code go.mod go.sum
    • Build binaries: make build

  5. Commit and open a PR:

    git add .
git commit -m "feat: describe your changes"
git push -u origin my-feature

    Open a pull request from your fork's my-feature branch to google/ax's main branch, describing the motivation and changes.