Correctness over compatibility. Evolution over preservation. Explicit over silent.
Bengal promises progress, not stability. When we discover a better approach, we implement it—even if that means breaking changes.
The Core Bargain
Not ready to upgrade? Stay on your current version. Ready? Read the release notes and migrate.
Why This Approach
Wrong output is worse than a failed build
A site that renders incorrectly is harder to catch than a site that fails to build. Clear error messages pointing to what changed are a feature.
Compatibility layers become the problem
Hidden shims cause subtle bugs, slow development, and become their own maintenance burden. Bengal deletes known mistakes instead of preserving them.
Example: Config key migration
When Bengal renamedsite.base_pathtosite.baseurl, we:
- Removed the old key entirely
- Added a clear error:
"site.base_path" is no longer supported. Use "site.baseurl" instead. - Documented the change in release notes
We did not silently map the old key to the new one. That approach would have hidden the problem until some future version removed the shim, breaking sites with no warning.
Honest expectations
Projects that claim backwards compatibility often break things silently or stagnate under legacy code. Bengal's stance: we control what changes, you control when you upgrade.
What This Means
For Users
| If you expect... | Expect instead... |
|---|---|
| Seamless upgrades | Read release notes before upgrading |
| Old config always works | Migrate config when prompted |
| Graceful deprecation | Clear errors pointing to fixes |
| Consistent cross-version behavior | Each version defines its behavior |
For Contributors
| If you expect... | Expect instead... |
|---|---|
| Avoid breaking changes | Make the right change, document it |
| Maintain compatibility shims | Delete deprecated code when ready |
| Support all past behavior | Support current behavior well |
Versioning
Bengal uses semantic versioning with one caveat: pre-1.0 releases may include breaking changes in any minor version.
| Version | Meaning |
|---|---|
| 0.x.y (current) | Any release may break things—read release notes |
| 1.0+ | Major = breaking, Minor = features, Patch = fixes |
Every release includes release notes. Breaking changes include migration guides.
Tip
Pin your version inpyproject.tomlorrequirements.txt(e.g.,bengal==0.1.7) to prevent unexpected upgrades. Upgrade deliberately by reviewing the changelog first.
Who Bengal Is For
Bengal prioritizes architectural integrity over broad enterprise adoption.
Summary
| Principle | Meaning |
|---|---|
| Correctness first | We fix mistakes even when it breaks things |
| Fail loudly | Errors are explicit, not silent degradation |
| User control | You choose when to upgrade |
| No hidden layers | What you see is what you get |
| Evolution over preservation | The project moves forward |
Bengal is not for everyone—and that's intentional. By being explicit about trade-offs, we can build the tool we believe in rather than the tool that satisfies everyone poorly.
Seealso
- FAQ — Common questions about compatibility and upgrades
- Changelog — Version history with migration guides
- Limitations — Known constraints and workarounds