> For the complete documentation index, see [llms.txt](https://docs.sylius.com/public/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sylius.com/public/open-source/release-cycle/backwards-compatibility-promise.md).

# Backwards Compatibility Promise

Sylius follows a versioning strategy called [Semantic Versioning](https://semver.org/). It means that only major releases include BC breaks, whereas minor releases include new features without breaking backwards compatibility.

Since Sylius is based on Symfony, our BC promise extends [Symfony’s Backward Compatibility Promise](https://symfony.com/doc/current/contributing/code/bc.html) with a few new rules and exceptions stated in this document. We also follow [Symfony’s Experimental Features](https://symfony.com/doc/current/contributing/code/experimental.html) process to be able to innovate safely.

### Minor and patch releases

Patch releases (such as 1.0.x, 1.1.x, etc.) do not require any additional work apart from cleaning the Symfony cache.

Minor releases (such as 1.1.0, 1.2.0, etc.) require to run database migrations.

### Code covered

This BC promise applies to all of Sylius’ PHP code except for:

* code tagged with `@internal` or `@experimental` tags
* event listeners
* model and repository interfaces
* PHPUnit tests (located at `tests/`, `src/**/Tests/`)
* PHPSpec tests (located at `src/**/spec/`)
* Behat tests (located at `src/Sylius/Behat/`)
* final controllers (their service name is still covered with BC promise)

### Additional rules

#### Models & model interfaces

To fulfill the constant Sylius’ need to evolve, model interfaces are excluded from this BC promise. Methods may be added to the interface, but backward compatibility is promised as long as your custom model extends the one from Sylius, which is true for most cases.

#### Repositories & repository interfaces

Following the reasoning same as above and due to technological constraints, repository interfaces are also excluded from this BC promise.

#### Event listeners

They are excluded from this BC promise, but they should be as simple as possible and always call another service. Behaviour they’re providing (the end result) is still included in BC promise.

#### Final controllers

It is allowed to change their dependencies, but the behaviour they’re providing is still included in BC promise. The service name and class name will not change.

#### Routing

The currently present routes cannot have their name changed, but optional parameters might be added to them. All the new routes will start with `sylius_` prefix in order to avoid conflicts.

#### Services

Services names cannot change, but new services might be added with `sylius.` or `Sylius\\` prefix.

#### Templates

Neither template events, block or templates themselves cannot be deleted or renamed.

### Deprecations

Before we remove or replace code covered by this backwards compatibility promise, it is first deprecated in the next minor release before being removed in the next major release.

A code is marked as deprecated by adding a `@deprecated` PHPDoc to relevant classes, methods, properties:

```
/**
 * @deprecated Deprecated since version 1.X. Use XXX instead.
 */
```

The deprecation message should indicate the version in which the class/method was deprecated and how the feature was replaced (whenever possible).

A PHP deprecation must also be triggered to help people with the migration, for instance:

```
trigger_deprecation(
    'sylius/some-package', // package name
    '1.x', // package version
    'A is deprecated and will be removed in Sylius 2.0. Use B instead.', // message
);
```

You should not use the `@trigger_error()` function.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.sylius.com/public/open-source/release-cycle/backwards-compatibility-promise.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.