Document an AI-assisted contribution policy

Open
  • Is something wrong?
#978 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
3/5
Estimated time
1-2 days
Newbie friendliness
42/100
Issue type
Documentation
Clarity
Mostly clear
Activity status
Active
Domain
documentation

Research direction

Start with docs/_toc.yml and docs/CONTRIBUTING.md, then look at the existing developer_guide pages to match their structure, and check the PR template for the "AI Usage" section. Add the new page and its toc entry, then link it from CONTRIBUTING.md. Done means the docs build passes with --warningiserror and the team has reviewed the wording. The issue depends on AGENTS.md from #976 and on the pending licensing questions, so confirm both before writing the licensing note.

Written by the indexing model from the issue text.

Description

infrastructure

Document an AI-assisted contribution policy

Team expectations about AI use are scattered, unclear, and historically haven't been discussed.
Contributors might not be sure what is expected of them.

Proposed solution

  1. Add a new developer-guide page, for example docs/developer_guide/ai_assisted_development.md, and add it to docs/_toc.yml next to the other developer guide pages.
  2. Add a short "AI-assisted contributions" section to docs/CONTRIBUTING.md that links to it and to the updated PR template.
  3. Point to the AGENTS.md file developed by #976 in this guide as well

Suggested page contents:

  • Principles: the human dev owns everything they submit; humans review; AI is optional and never required to contribute
  • Where AI helps (from the workshop): scaffolding and boilerplate, tests and coverage, docs and docstrings, plotting, debugging, learning an API, explaining unfamiliar code, planning before coding, pre-review checks for syntax and style, and drafting the changed-files list
  • Where AI hurts: excess or convoluted code, OpenMDAO misuse, lost intent, rogue test values, large unrequested changes, plausible but wrong facts, code that is harder to modify by hand
  • Author responsibilities: understand every line, review before opening a draft PR, no unrelated changes, run pre-commit and tests, cite sources for numbers
  • Disclosure: how to fill in the PR "AI Usage" section
  • Reviewer responsibilities and rights: humans always review; reviewers may ask for a PR to be split or simplified; AI-assisted review is allowed but the reviewer remains accountable
  • Safe use: no sensitive or unpublished data in prompts, no secrets, caution with AI web access
    and new dependencies, licensing note (pending the policy questions issue)
  • Link to AGENTS.md for tool-facing rules.

When are we done?

  • New page added and included in _toc.yml
  • CONTRIBUTING.md links to it
  • Docs build passes with --warningiserror
  • Wording reviewed by the team, avoiding judgment of anyone's tool choices
Dominant language
Python
Stars
30
Forks
44
Avg merge
3d 12h
Merged PRs (30d)
28

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from NatLabRockies/H2Integrate

All issues in NatLabRockies/H2Integrate

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.