Contributing and Issues

Contributing and Issues

Mochi is still in active development, so contributions should prioritize stability, clarity, and small reviewable changes.

Before contributing

Read:

• the repository README
• Project Philosophy
• Interaction Core
• Development and Testing
• REGRESSION_WATCHLIST.md

If your change affects input, animation state, dragging, context-menu behavior, or asset loading, assume it can create regressions outside the exact feature being edited.

Good contribution scope

Good pull requests are usually narrow:

• fix one reproducible bug
• replace one animation state
• improve one interaction path
• add one regression test
• improve one small piece of documentation
• improve packaging validation

Avoid combining unrelated work such as:

new drag system
+ repository cleanup
+ UI redesign
+ asset migration
+ state-machine rewrite

Even individually reasonable changes become difficult to validate when bundled together.

Issue categories

Useful issue labels/categories include:

• bug
• enhancement
• animation
• input
• state-machine
• rendering
• ui
• alpha-blocker
• polish
• docs

The exact label set may evolve, but issues should clearly distinguish release-blocking reliability problems from optional polish.

Priority guidance

Alpha blocker

Use for problems that prevent normal public-alpha use, including:

• crash
• input freeze
• context menu permanently intercepting input
• Mochi stuck in an invalid state
• pickup/drop fundamentally broken
• package fails to launch/install
• serious unexpected permission requirement

High

A major interaction is broken, but Mochi remains generally usable.

Medium

Noticeable regression or behavior inconsistency that should be fixed but does not block basic use.

Low / polish

Visual feel, timing, minor animation quality, or optional UX improvements.

Recommended bug format

## 🌱 Summary

Briefly describe the issue.

## 🧩 Area

- [ ] Animation
- [ ] Input / mouse interaction
- [ ] Drag / pickup / put-down
- [ ] State machine
- [ ] Context menu
- [ ] Sleep / wake
- [ ] Walking
- [ ] Emotes
- [ ] Rendering / transparency
- [ ] Audio
- [ ] UI / overlay
- [ ] Packaging / installation
- [ ] Performance
- [ ] Other

## 🚨 Priority

- [ ] Alpha blocker
- [ ] High
- [ ] Medium
- [ ] Low / polish

## 🔁 Steps to reproduce

1.
2.
3.

## ✅ Expected behavior

What should Mochi do?

## ❌ Actual behavior

What happens instead?

## 🧠 State / interaction sequence

```text
IDLE
→ ...
→ FAILURE

💻 Environment

OS / distro: Desktop environment: Wayland / X11 / XWayland: Mochi version / commit: Python version:

🎯 Acceptance criteria

• root cause understood
• expected behavior works consistently
• Mochi remains interactable
• regression test added/updated
• full test suite passes
• live test passes when applicable

## Why interaction sequences matter

Mochi bugs are often lifecycle bugs rather than isolated visual bugs.

This:

```text
IDLE → RIGHT CLICK → WALK → DRAG → INPUT FREEZE

is usually more diagnostic than:

Drag sometimes does not work.

Include the sequence whenever possible.

Screenshots and recordings

Attach visual evidence for:

• checkerboard backgrounds
• matte/halo artifacts
• eye inconsistencies
• loop restart pops
• window placement problems
• context menu stuck on screen

For freeze/state bugs, include debug logs if available.

Pull request expectations

A runtime PR should explain:

1. what was broken or missing
2. the confirmed cause or design need
3. the smallest implementation used
4. tests added/updated
5. manual/live scenarios tested
6. any remaining uncertainty

Do not describe a change as fully verified if compositor-level interaction was not actually tested.

Required regression thinking

For interaction-related changes, verify that the fix does not break:

• single-click squish
• double-click heart
• pickup → drag → put-down
• context menu
• Walk
• Sleep/Wake
• Emote
• Computer/typing
• idle recovery

For art changes, verify:

• transparency
• no gray matte
• canonical eyes
• bottom-center alignment
• nearest-neighbor rendering
• no legacy art

Asset contributions

Do not overwrite the entire Mochi asset tree to add one animation.

Preferred flow:

1. identify the exact state being replaced
2. preserve current working art for other states
3. add/replace only relevant files
4. update the manifest
5. run asset integrity tests
6. build/audit package
7. preview visually

AI-assisted contributions

AI-assisted code or art is acceptable as part of the development process, but generated output should be treated like any other contribution:

• inspect it
• understand the change
• test it
• document relevant limitations
• do not merge generated assets without production QA

AI output does not reduce the acceptance standard.

Project-management split

Mochi uses different tools for different layers of work:

• GitHub Issues — concrete bugs, regressions, and implementation tasks
• Trello — sprint planning and prioritization
• Git commits / PRs — actual implementation history
• Wiki/docs — durable knowledge and architecture guidance

Avoid duplicating entire issue descriptions in planning tools. Link between them instead.

Contribution philosophy

The best contribution is not necessarily the biggest one.

A small fix that keeps Mochi responsive across every interaction is more valuable than a large feature that destabilizes the creature core.