Skip to content

OpenToonz - An open-source full-featured 2D animation creation software

C

Add developmental policy/guideline checklists

Rodney3fd1ab6da9e3
diff --git a/README.md b/README.md
index e62f88fc2..01c2eb596 100644
--- a/README.md
+++ b/README.md
@@ -30,6 +30,11 @@ Please download and install OpenToonz from the latest installer at <https://open
Older versions and unstable nightly builds are also available at <https://github.com/opentoonz/opentoonz/releases>.
+## Development
+
+- [Development checklist (draft)](./doc/development_checklist.md)
+- [AI-assisted development checklist (draft)](./doc/ai_assisted_development_checklist.md)
+
## How to Build Locally
- [Windows](./doc/how_to_build_win.md)
diff --git a/doc/ai_assisted_development_checklist.md b/doc/ai_assisted_development_checklist.md
new file mode 100644
index 000000000..b38f9c840
--- /dev/null
+++ b/doc/ai_assisted_development_checklist.md
@@ -0,0 +1,131 @@
+# AI-Assisted Development Checklist (Draft)
+
+> **OT-Dev permits broad AI-assisted exploration and development.**
+>
+> Acceptance in OT-Dev does **not** imply readiness for OpenToonz upstream. Upstream contributions must also pass the **Upstream Readiness Gate** below.
+>
+> Based on Shun Iwasawa's AI-assisted development policy in [OpenToonz Discussion #6937](https://github.com/opentoonz/opentoonz/discussions/6937).
+
+## 1. OT-Dev Development
+
+AI may assist investigation, prototyping, implementation, debugging, testing, documentation, and refactoring.
+
+- [ ] State the purpose.
+- [ ] Test or evaluate the change.
+- [ ] Take responsibility for the result.
+- [ ] Identify known uncertainties or untested assumptions.
+- [ ] Do not introduce licensing or provenance conflicts.
+- [ ] Preserve OpenToonz licensing, usage, and distribution requirements for work intended upstream.
+
+Large or experimental changes may remain combined during exploration.
+
+## 2. Human Reviewability
+
+- [ ] Be able to explain the change and its design.
+- [ ] Avoid unnecessary complexity.
+- [ ] Preserve design decisions needed for maintenance.
+- [ ] Use AI review to assist, not replace, human judgment.
+- [ ] Make upstream candidates small enough for humans to track and understand.
+
+## 3. Scope
+
+- [ ] Keep related exploratory work together when useful.
+- [ ] Separate unrelated work.
+- [ ] Identify topics requiring separation before upstream submission.
+- [ ] Split upstream candidates into one topic per PR.
+
+## 4. Documentation
+
+- [ ] Describe what changed.
+- [ ] Explain why.
+- [ ] Record important design decisions.
+- [ ] Identify AI assistance.
+
+When possible, include:
+
+- [ ] AI model and version.
+- [ ] Important prompts or design documents.
+- [ ] Attribution for prompts or designs derived from another contributor.
+
+## 5. Licensing and Provenance
+
+- [ ] Do not introduce code or assets with licensing incompatible with OpenToonz.
+- [ ] Check provenance when output resembles third-party material.
+- [ ] License shared prompts or design documents when required.
+- [ ] Preserve required attribution.
+- [ ] Resolve licensing concerns before upstream submission.
+
+---
+
+# Upstream Readiness Gate — OpenToonz
+
+**OT-Dev acceptance is not upstream approval.**
+
+## 6. Human-Reviewable Scope
+
+Before proposing AI-assisted work to `opentoonz/opentoonz`:
+
+- [ ] Limit each PR to **one topic of change or improvement**.
+- [ ] Split large or multifaceted work into separate PRs.
+- [ ] Keep each PR small enough for humans to track and understand.
+- [ ] Keep unrelated changes out.
+
+## 7. Required PR Explanation
+
+Each PR must include:
+
+- [ ] **Details of the changes.**
+- [ ] **Reason for the changes.**
+
+## 8. AI Information
+
+When possible, include or attach:
+
+- [ ] AI model name and version.
+- [ ] Prompt or design document given to the AI.
+- [ ] A **CC-BY license** for the prompt/design document if necessary.
+- [ ] `Co-authored-by` credit when a prompt is based on another contributor's posted prompt, as recommended by the upstream policy.
+
+## 9. Human Maintainability
+
+- [ ] A human can explain the change.
+- [ ] Humans can understand the important implementation choices.
+- [ ] Human review does not depend on AI review.
+- [ ] Humans can maintain the code after merge.
+
+## 10. General OpenToonz Requirements
+
+The PR must also pass the OpenToonz development checklist:
+
+- [ ] Do not interfere with existing usages.
+- [ ] Do not unnecessarily disrupt existing workflows.
+- [ ] Preserve existing scene rendering when modifying existing Fx or rendering behavior.
+- [ ] Make conflicting workflow behavior optional when appropriate.
+- [ ] Resolve licensing concerns or obtain required owner review.
+- [ ] Follow the current release-phase restrictions.
+
+## Final Upstream Check
+
+- [ ] One topic per PR.
+- [ ] Human-reviewable scope.
+- [ ] Changes and reasons documented.
+- [ ] AI information included when possible.
+- [ ] Licensing and attribution resolved.
+- [ ] Human-understandable and maintainable.
+- [ ] General OpenToonz requirements satisfied.
+
+---
+
+## Policy Distinction
+
+**OT-Dev:** Explore, test, learn, and develop responsibly with AI.
+
+**OpenToonz upstream:** Make the resulting contribution small, documented, human-reviewable, and human-maintainable.
+
+The upstream policy is a **promotion requirement**, not a restriction on OT-Dev exploration.
+
+## Source
+
+Shun Iwasawa, [OpenToonz Discussion #6937](https://github.com/opentoonz/opentoonz/discussions/6937).
+
+This checklist adapts the upstream policy to OT-Dev while preserving its requirements for upstream contributions.
diff --git a/doc/development_checklist.md b/doc/development_checklist.md
new file mode 100644
index 000000000..f35a73a76
--- /dev/null
+++ b/doc/development_checklist.md
@@ -0,0 +1,103 @@
+# Development Checklist (Draft)
+
+> Drafted from Shun Iwasawa's development policy posted in [OpenToonz Discussion #6332](https://github.com/opentoonz/opentoonz/discussions/6332).
+>
+> **Core principle:** A pull request can be merged if it will not interfere with existing usages.
+
+This checklist is intended as a practical aid for contributors, reviewers, and maintainers. It does not replace maintainer judgment or project-specific review.
+
+## 1. Core Merge Requirement
+
+Before merging a pull request:
+
+- [ ] Confirm that the change does **not interfere with existing usages** of OpenToonz.
+- [ ] Consider whether a change that benefits one workflow could disadvantage another workflow.
+- [ ] Where workflows may conflict, consider making the behavior **optional or user-selectable**, preferably through user profiles or appropriate settings.
+
+## Exceptions and Escalation
+
+A checklist conflict does not automatically reject a change. It identifies a decision that requires explicit approval.
+
+Changes that break existing usage, compatibility, licensing expectations, or other policy may require maintainer or owner approval before acceptance. Approval may take time; identify these conflicts early.
+
+Major changes may require a working demonstration in OT-Dev or a separate fork before approval. Use the demonstration to compare benefits, regressions, migration costs, and affected workflows.
+
+Do not treat an exception as implicit approval. Record the exception, its impact, and the decision that permits it.
+
+## 2. License Review
+
+- [ ] Check whether the PR introduces code, libraries, assets, algorithms, or other material that could conflict with OpenToonz's existing license.
+- [ ] If there is a possibility of a license conflict, **do not merge until the owner has reviewed it**.
+
+## 3. Stable Release Restrictions
+
+During the period beginning several months before an announced stable release:
+
+- [ ] Determine whether the PR is a **feature PR**.
+- [ ] Do **not merge feature PRs** during the pre-release stabilization period.
+- [ ] Continue to evaluate appropriate bug fixes and other non-feature changes according to the core principle.
+
+## 4. Changes Generally Suitable for Merge
+
+The following types of changes are generally acceptable, provided they satisfy the core merge requirement and normal review standards:
+
+- [ ] **Bug fixes**
+- [ ] **Refactoring**
+- [ ] **Enhancements / speed improvements**
+- [ ] **Translations**
+- [ ] **New Effects (Fx)**
+- [ ] **New commands**
+- [ ] **New panels**
+- [ ] **New presets**, including Fx presets, camera settings, shortcuts, and similar additions
+- [ ] **Changes to default user profiles**, including preferences, panel layouts, and shortcuts
+
+## 5. User Interface Changes
+
+For UI changes that **cannot be controlled through user profiles**, such as adding buttons to panels or commands to context menus:
+
+- [ ] Confirm that the addition will not disturb conventional/existing usage.
+- [ ] Check whether the new UI element unnecessarily obstructs, displaces, or complicates an established workflow.
+- [ ] Consider whether the behavior or interface can reasonably be made optional when it could affect different workflows differently.
+
+These changes are basically acceptable to merge when they preserve conventional usage.
+
+## 6. Existing Effects and Rendering Behavior
+
+For changes to an existing Fx or rendering behavior:
+
+- [ ] Test scenes/workflows created with the previous OpenToonz version.
+- [ ] Ensure the change does **not alter the rendering result of an existing scene** created with the previous version.
+- [ ] Treat backward-compatible rendering as a merge requirement unless there is an explicitly reviewed reason to break compatibility.
+- [ ] Where new behavior is desirable but would change existing results, consider providing it as an optional/new mode rather than silently changing established behavior.
+
+## 7. Workflow Compatibility Check
+
+Because OpenToonz supports many different animation-production workflows:
+
+- [ ] Consider workflows beyond the one targeted by the PR.
+- [ ] Ask whether improving one workflow creates a disadvantage or behavioral change for another.
+- [ ] Preserve existing workflows whenever practical.
+- [ ] Prefer selectable/optional behavior when multiple valid workflows have conflicting requirements.
+
+## Final Merge Check
+
+Before merging, verify:
+
+- [ ] Existing usages remain functional.
+- [ ] Existing workflows are not unnecessarily disrupted.
+- [ ] Existing scene rendering remains compatible when existing Fx/rendering behavior is modified.
+- [ ] Potentially conflicting workflow changes are optional where appropriate.
+- [ ] No unresolved licensing concern requires owner review.
+- [ ] The PR is permitted under the current stable-release development phase.
+
+---
+
+## Source
+
+Shun Iwasawa, [OpenToonz Discussion #6332](https://github.com/opentoonz/opentoonz/discussions/6332).
+
+This checklist is a practical restatement of the development policy described in the post. The source policy's central rule is:
+
+> **PR can be merged if it will not interfere existing usages.**
+
+A separate checklist covers project policy for **AI-assisted contributions**.