bevyengine / bevyengine/bevy

Defining a stable core API for better maintainability

Open
#16,975 5 comments 6 reactions 0 assignees View on GitHub
A-Meta C-Feature S-Needs-Design X-Needs-SME
Dominant language
Rust
Stars
48.2k
Forks
4.8k
Avg merge
3d 16h
Merged PRs (30d)
171

Description

# Proposal: Defining a stable core API for better maintainability

## Description

As a developer using Bevy for project development, I've encountered challenges with maintaining my projects due to the rapid evolution of the Bevy API. While I understand and appreciate the reasons behind the frequent changes (rapid iteration, performance improvements, keeping up with the evolving Rust gamedev ecosystem), I believe that defining a stable core API could provide significant benefits for project maintainability and long-term adoption.

## Proposal

I suggest that we consider defining a stable core API that encapsulates the fundamental primitives and patterns that are unlikely to change frequently. This could include things like:

- Colors
- Transforms
- Basic ECS composition and usage
- Core math types and operations
- Key input event handling
- Basic rendering setup and configuration

The goal would be to provide a fixed, well-documented API for these core concepts that developers can rely on across Bevy versions, even as the wider framework continues to evolve and improve.

## Potential Benefits

- Improved maintainability for long-lived projects
- Reduced upgrade friction and breaking changes for fundamental use cases
- A stable foundation for learning Bevy and building reusable libraries
- Increased adoption and confidence in using Bevy for serious projects

## Potential Approaches

- Carefully designing core APIs with forwards/backwards compatibility in mind
- Providing a separate "core" library with a fixed API, distinct from the main library
- Maintaining thorough documentation and guides for the stable APIs
- Providing detailed changelogs and migration guides for any necessary breaking changes
- Offering a slower-moving, stability-focused release channel in addition to the current cutting-edge channel

## Open Questions

- What specific primitives and patterns should be included in the stable core?
- How do we balance stability with the need for ongoing improvement and evolution?
- How do we handle necessary breaking changes to the stable core over time?
- What's the best way to structure and distribute a stable core API alongside the main library?

I'm open to discussion and feedback on this proposal. I believe that with careful design and community input, we could define a stable core that would make Bevy even more powerful and appealing for long-term, serious project development.

Cheers,

Neshume

Contributor guide

Open the contributing guide

Research direction

No files, tests, or entry points are identified. Start by reviewing Bevy's existing public APIs and migration guidance, then narrow the proposal to a specific set of primitives and a concrete compatibility goal; done would require an agreed stable-core design rather than a single implementation change.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
api, game-dev
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.