Add article about BC breaks #730
Conversation
matks
force-pushed
the
article-bc-break
branch
2 times, most recently
from
712fc81
to
622b5a4
Compare
|
I should improve this article
|
|
I should mention "adding a new argument in __construct()" as a typical BC break |
|
I need to make sure SQL tables are displayed correctly. |
|
Article is complete from my point of view 😄 I await reviews. |
Co-authored-by: Antoine THOMAS <antoine.thomas@prestashop.com>
Co-authored-by: Antoine THOMAS <antoine.thomas@prestashop.com>
|
Applied @ttoine feedbacks. |
|
|
||
| ## A deeper look at Backward Compatibility Breaks | ||
|
|
||
| This article explains what exactly are [Backward Compatibility](https://en.wikipedia.org/wiki/Backward_compatibility) Breaks also known as Breaking Changes or BC breaks and how it influences how an open source project like PrestaShop is built. It explains the different types of BC breaks, why they are needed sometimes and how PrestaShop maintainers manage them. |
There was a problem hiding this comment.
also known as Breaking Changes or BC
Did you realize we often use the same acronym differently?
- BC = Breaking change
- BC Break = Backwards Compatibility Break
I think this should be explained
|
|
||
| All of these people will use code and logic that is written inside the software. For exammple, very often modules build URLs using function `Link::getModuleLink()`. | ||
|
|
||
| However, as time passes, new versions of the software are released and this code and logic are changed to be improved, upgraded, made faster or more secure. When, from one version to another, the code changes in a way that breaks the "external code" that has been built around it, this is a Breaking Change. |
There was a problem hiding this comment.
To me this is an inaccurate description of a breaking change. Formally, a breaking change relates to API changes, not code breaking. This is a subtle yet extremely important difference, as vendors can only be accountable for their contracts, not for the entirety of their public code. If your code breaks because you used an internal class from upstream, of because you relied on side effects that don't belong to the library's API, you can't blame the vendor.
There was a problem hiding this comment.
This means I need to introduce the concept "dependency as an API" then explain" SemVer & API contract" before being able to explain this. It's going to make this article longer although it's already quite big. Is it alright ?
|
|
||
| The concept of BC Break is not specific to PrestaShop. This is actually a very common issue for all code that is being used as a foundation for other software to use: operating systems like Linux, libraries like Guzzle, tools like cURL, frameworks like Symfony ... and CMS like Drupal or PrestaShop. | ||
|
|
||
| In order to make it easier for the people using these codebases as foundations to handle these changes, [Tom Preston Werner](http://tom.preston-werner.com/) has invented a convention: [SemVer](https://semver.org/). [SemVer](https://semver.org/) aims to help people understand immediately, when seeing a new version of software, what is contained inside it. |
There was a problem hiding this comment.
FYI this has already been explained before https://build.prestashop.com/news/a-more-semantic-versioning-scheme/
There was a problem hiding this comment.
I think it's better to re-explain it for the reader's ease (he does not need to go read something else) but I can refer to the blog post as an external reference.
Wdyt ?
- remove this and redirect to previous blog post
- only refer to previous blog post, keep this section content
Co-authored-by: Pablo Borowicz <pablo.borowicz@prestashop.com> Co-authored-by: Matthieu Rolland <matthieu.rolland@prestashop.com>
|
@matthieu-rolland @eternoendless Thank you for proof-reading ! I have applied all your feedbacks already. Here are the left blocking items:
|
|
Pfou 😅 I'm trying to introduce concepts such as "What is a dependency ?" "What is an API interface / a contract ?" "What does it mean for a package" and this article is becoming longer and longer. I might have to split it in 2. |
|
Following @eternoendless feedback I have rewritten this article. Part 1 will be coming soon #777 |
This article explains what exactly are Backward Compatibility Breaks also known as Breaking Changes or BC breaks and how it influences how an open source project like PrestaShop is built. It explains the different types of BC breaks, why they are needed sometimes and how PrestaShop maintainers manage them.
Fixes #704