OpenToonz - An open-source full-featured 2D animation creation software
C
Add developmental policy/guideline checklists
Rodney3fd1ab6da9e3
diff --git a/README.md b/README.mdindex e62f88fc2..01c2eb596 100644--- a/README.md+++ b/README.md@@ -30,6 +30,11 @@ Please download and install OpenToonz from the latest installer at <https://openOlder 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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**.