Add Mesa-Examples policy document

[EwoutH]

Hey @mesa/maintainers, here's an important one:

I drafted a policy for how we handle mesa-examples during the Mesa 4 transition. It covers who's responsible for updating broken examples, branching strategy, CI expectations, and community involvement.

Key decisions in the draft:

• Branch-based: we snapshot mesa-3.x before the first breaking change, main tracks latest Mesa
• PR authors fix simple breakages directly, open tracked issues for complex ones
• Smoke tests only (no viz or batch_run testing required)
• Defer removal decisions until after Mesa 4.0 release

Please give it a critical read. Specifically looking for feedback on:

1. Is the simple vs complex boundary realistic? Will PR authors actually follow through?
2. Is the testing bar too low or about right?
3. Anything missing that will bite us later?

Would like to finalize this before we start landing breaking changes.

[jackiekazil]

I am confused by this a little... questions I have...

• We never did this before, why now?
• If we do this updating, then what happens with the GSoC proposal for updating examples?
• What problem are we trying to explicitly solve with this?

[EwoutH]

@jackiekazil thanks for your perspective.

Why now?

Mesa 4 has significantly more breaking changes than any previous release: we’re removing DataCollector, batch_run, overhauling spaces, changing time progression, etc. That’s qualitatively different from 3.x minor releases. The seed removal PR (#3318) already prompted exactly this discussion (“what do we do about mesa-examples?”), and I don’t want to have this debate on every PR. This is an attempt to avoid that.

We need to agree on this before we start landing breaking changes, not after half the examples are broken with no tracking.

What problem?

Two things:

1. making sure we don’t silently break all user examples and lose track of what needs fixing. The policy creates the structure (tracked issues, clear tasks per example).
2. not having to debate the process from scratch on every breaking PR.

GSoC?

This policy and a GSoC project are complementary, I think. Or maybe this is a start at that that can be further refined. A well-organized backlog of mesa-4-migration issues is exactly what makes a GSoC project feasible.

[EwoutH]

Any further comments?

[jackiekazil]

Any further comments?

I am good with this - other than my last pending comment - not sure if this is the time to do it OR if it should be separated.

[EwoutH]

Thanks.

I would prefer at least one green checkmark.