Contribution, Review, and Generative AI Policy

JCSDA repositories are segregated into different quality tiers based on their use case, code quality standards, and review practices. In short, the quality tiers are:

  • Quality Tier 1: software intended for production use; highest quality and performance requirements, all changes human reviewed, tested, and owned by a responsible human contributor.

  • Quality Tier 2: nonproduction software; data analysis and visualization, convenience scripts, and CLI helpers. All changes reviewed, unit tested, some quality checks.

  • Quality Tier 3: Internal-only code, helpers, one-offs, reporting, and issue management. Not intended for sharing.

Review requirements and generative AI policy for each quality tier are detailed below. These policies should be included in each repository to maintain and communicate developer expectations.

Take note: quality tiers are sticky. Do not do "experimental work" under Tier 3 for software that is intended to ship as Tier 1. Software maintains its original quality tier until all code has been submitted under the review and contribution guidelines of a tier. Sufficiently large and complex software may be infeasible to migrate to a higher tier, necessitating a full rewrite.

Quality Tier 1

Review Policy

  • Pull requests may be submitted after review and approval by two humans, one of whom must be a maintainer of the repository.

  • AI reviews may be used to suppliment human reviews but may not replace the required human reviews.

Generative AI Policy

Contributors are welcome to use Generative AI provided they respect the following rules on its use.

  • Every contribution must have at least the accountable human author who opens the pull request.

    • Read and review every line of AI-generated code before submitting it.

    • Don't submit code you can't explain during the review.

  • Pull requests may not be opened by AI agents.

  • Pull requests using Generative AI must disclose the use of AI tooling in the description.

  • Do not credit the tool as the author of git commits.

  • Follow your employer's policy. The IP status of AI-generated code is unsettled in many jurisdictions.

Large Changes

  • A large change is any change with a diff over 500 lines, or any change that is unusually large or complex as determined by the maintainers.

  • Open an issue and settle the approach before submitting a large change. Large pull requests that arrive without that discussion will not be reviewed.

  • Large changes from new contributors may be closed without review.

  • Maintainers may require a large change to be split across several smaller pull requests. This requirement will generally apply to new contributors and may be applied to established contributors.

Quality Tier 2

Review Policy

  • Pull requests may be submitted after review and approval by at least one human who must be a maintainer of the repository.

  • AI reviews may be used to suppliment human reviews but may not replace the required human review.

Generative AI Policy

Contributors are welcome to use Generative AI provided they respect the following rules on its use.

  • Every contribution must have at least the accountable human author who opens the pull request.

    • Understand the input requirements for all data structures, methods, and functions.

    • Understand the testing strategy and be able to explain how the tests validate the software.

  • Pull requests may not be opened by AI agents.

  • Pull requests using Generative AI must disclose the use of AI tooling in the description.

  • Do not credit the tool as the author of git commits.

  • Follow your employer's policy. The IP status of AI-generated code is unsettled in many jurisdictions.

Large Changes

  • A large change is any change with a diff over 1000 lines, or any change that is unusually large or complex as determined by the maintainers.

  • Large changes from new contributors may be closed without review.

  • Maintainers may require a large change to be split across several smaller pull requests.

Quality Tier 3

Review Policy

  • Pull requests may be submitted after approval by at least one human who must be a maintainer of the repository.

  • The code must be reviewed by the maintainer or by an AI agent directed by the maintainer.

Generative AI Policy

Contributors are welcome to use Generative AI provided they respect the following rules on its use.

  • Every contribution must have at least one accountable human author who understands and can explain the requirement being satisfied by the change.

  • Pull requests using Generative AI must disclose the use of AI tooling in the description.

  • Do not credit the tool as an author git commits.

  • Follow your employer's policy. The IP status of AI-generated code is unsettled in many jurisdictions.

Large Changes

  • Large changes have no distinct review requirements or treatment.