Agent Instructions for Azure Service Operator

You are an expert Go developer and an AI assistant helping to maintain the Azure Service Operator (ASO) project.

Your Workflow

Please follow these steps to ensure your contributions are effective and align with our project standards:

1. Understand the Goal: Carefully read the title and description of any request or assigned GitHub issue to fully grasp the problem or feature request.
2. Explore the Code: Use the available tools to search the codebase, identify the relevant files to modify, and understand the existing implementation.
3. Implement Changes: Write clean, maintainable Go code that addresses the issue. Please mimic the style of the existing code in the repository.
4. Verify Your Work: Follow the Verification Steps outlined below to ensure your changes are correct and pass all checks.

Project Context

• Purpose: ASO is a Go-based operator for creating and managing Azure resources from a Kubernetes cluster.
• Key Files:
  • v2/azure-arm.yaml: Contains configuraiton for the custom code generator that generates the code for the Azure resources.
• Key Directories:
  • v2/api/: Contains the API definitions for the Azure resources (the CRDs).
  • v2/internal/controllers/: Contains the reconciliation logic for the operator.
  • docs/hugo/content/: Holds the reference documentation.
  • v2/tools/generator: Contains the code generator that generates the code for the Azure resources.

Development Environment

Your environment is automatically configured by invoking dev.sh. First run installs all required dependencies; later runs are fast. If dev.sh fails to run or install dependencies, stop and report the failure output; do not proceed with changes in an unconfigured environment.

• Custom tools are installed in the hack/tools directory and are on your PATH when running dev.sh.
• If you find a required tool is missing, please stop and report it as a problem.
• Do not modify generated files by hand (e.g. *.gen.go and *.gen_test.go files) as those changes will be overwritten during the build.

To run commands within the development shell, with all tools available on the path, run ./dev.sh -c <your command>.

Verification Steps

Before completing your task, run the following checks in the specified order, one at a time.

• Choose validation steps according to the changes made.
• Restart validation when a fix invalidates an earlier result.
• Skip irrelevant or unexpectedly expensive validation rather than needlessly expanding the task.

When the following sequence applies, run the checks in the specified order, one at a time:

1. Format Code:

   task format-code

2. Run Generator Checks: This builds the code generator, runs its unit tests, generates any new code, and checks for issues.

   task generator:quick-checks

3. Run Controller Checks: This builds the main controller, and runs its unit tests.

   task controller:quick-checks

If an issue seems too complex to fix, please stop and ask for clarification.

Key Guidelines

1. Follow Go best practices and idiomatic patterns
2. Maintain existing code structure and organization
3. Write unit tests for new functionality. Use table-driven unit tests when possible.
4. Document public APIs and complex logic. Suggest changes to the docs/hugo/content folder when appropriate

Detailed instructions

Please reference the following additional files for detailed instructions in specific scenarios.

• Use Conventional Commits for pull request titles and commit messages. Follow the prefix guidance in CONTRIBUTING.md.
• If you are adding a new resource, or a new version of an existing resource, use the /create-new-resource skill.
• If you are reviewing a change, consult code-review.instructions.md.
• If you are investigating or filing a security issue, consult SECURITY.md in the repository root.

Reference Documentation

We have extensive reference documentation available under the docs/hugo/content directory, including a detailed contributors guide in the docs/hugo/content/contributing directory and CONTRIBUTING.md. Please consult this as required.