Contribution Standards

Overview

To maintain the integrity of the Supervised AI platform's testing infrastructure, all contributions must adhere to specific architectural and stylistic standards. We prioritize a clean, predictable Public Interface that ensures a seamless experience for developers consuming the testing-api.

API Design Principles

When adding or modifying endpoints, follow these core principles to ensure consistency across the platform:

• RESTful Conventions: Use standard HTTP methods (GET, POST, PUT, DELETE) that accurately reflect the action being performed.
• Predictable Pathing: Endpoints should follow a hierarchical structure (e.g., /v1/tests/{test_id}/results).
• Version Control: All breaking changes to the public interface must be introduced via a new version prefix (e.g., incrementing from /v1/ to /v2/).

Defining Public Interfaces

Every new feature must include clear Type definitions or Schemas. This allows users of the API to understand the expected input and output without diving into the source code.

Request/Response Example

When contributing a new endpoint, ensure the interface is documented as follows:

// Define the interface for the public request body
interface TestExecutionRequest {
  test_id: string;      // Unique identifier for the test suite
  environment: string;  // Target environment (e.g., 'staging', 'production')
  params?: Record<string, any>; // Optional execution parameters
}

// Define the expected public response
interface TestExecutionResponse {
  job_id: string;       // ID used to track the asynchronous execution
  status: 'queued' | 'running';
  started_at: string;   // ISO 8601 timestamp
}

Coding Standards

To maintain code quality and readability, please follow these requirements:

Naming Conventions

• Variables/Functions: Use camelCase for internal logic.
• Constants: Use SNAKE_UPPER_CASE.
• Public API Parameters: Use snake_case for JSON keys in requests and responses to maintain platform-wide consistency.

Documentation Requirements

Any change to the public interface must be reflected in the documentation.

• Inline Comments: Use JSDoc (or equivalent for the language used) to describe the purpose of public functions, parameters, and return types.
• README Updates: If a new module or high-level capability is added, update the main README.md with a usage example.

Testing Requirements

Contributions will not be merged without corresponding tests. We emphasize testing the observable behavior of the API rather than internal state.

• Integration Tests: Every new public endpoint must have an integration test demonstrating a successful 200 OK cycle and appropriate error handling (e.g., 400 Bad Request).
• Contract Testing: Ensure that changes do not break existing downstream consumers by verifying response structures against defined schemas.

# Example command to run the test suite before submission
npm run test:api

Pull Request Process

1. Branch Naming: Use a descriptive prefix: feat/, fix/, or docs/ (e.g., feat/add-batch-testing).
2. Description: Clearly state what changed in the public interface and provide a brief example of the new usage.
3. Review: At least one maintainer must approve the PR. They will focus on whether the new code aligns with the existing public-facing API structure.