Забыл совсем написать про настройку EnablePackageValidation в csproj, который использует под капотом тот же ApiCompat.
Он создан для разработчиков библиотек чтобы отловить breaking changes до их выпуска в продакшн.
Если задать EnablePackageValidation и PackageValidationBaselineVersion, то при вызове dotnet pack он будет проверять совместимость public API между текущей и базовой версией. Это очень удобно!
Допустим, у библиотеки была версия 1.1.1 (major.minor.patch соответственно).
В качестве базовой (PackageValidationBaselineVersion) задана 1.0.0.
Разработчик реализовал фичу. Для фичи по semver принято поднимать minor версию, поэтому версия поднимается до 1.2.0
Поднятие только minor или patch составляющих подразумевает сохранение обратной совместимости.
Валидатор возьмет API из базовой версии 1.0.0 и сравнит с текущей.
Если мы случайно внесли breaking change, то будет ошибка с описанием где именно проблема, с каким методом и т.п.
И здесь 2 варианта:
- (Лучше всего) поправить breaking change и зарелизить 1.2.0
- Если совсем никак, то поднять major версию до 2.0.0, написать в changelog информацию о breaking change и migration guide. И не забыть поднять PackageValidationBaselineVersion, иначе опубликовать пакет не удастся.
Ниже пример настройки валидатора:
net9.0
1.1.0
true
1.0.0
Так как валидация происходит при вызове dotnet pack, то в CI/CD нужно еще в Merge Request pipeline сделать dotnet pack, чтобы запустился валидатор и проверил на совместимость версий. Сразу поднимать текущую версию необязательно - валидатор все равно покажет ошибки.
Такой подход гораздо удобней применять при разработке своих NuGet пакетов
А для чужих библиотек - ApiCompat как из поста выше.
В тоже время анализатор позволяет ускорить inner loop, так как очевидные breaking changes подсвечивает прямо во время разработки в IDE. Но анализатор это не замена валидатора в CI/CD. Они скорее друг друга дополняют, потому что в CI проверки более глубокие, а анализатор не сложно отключить локально :)
Он создан для разработчиков библиотек чтобы отловить breaking changes до их выпуска в продакшн.
Если задать EnablePackageValidation и PackageValidationBaselineVersion, то при вызове dotnet pack он будет проверять совместимость public API между текущей и базовой версией. Это очень удобно!
Допустим, у библиотеки была версия 1.1.1 (major.minor.patch соответственно).
В качестве базовой (PackageValidationBaselineVersion) задана 1.0.0.
Разработчик реализовал фичу. Для фичи по semver принято поднимать minor версию, поэтому версия поднимается до 1.2.0
Поднятие только minor или patch составляющих подразумевает сохранение обратной совместимости.
Валидатор возьмет API из базовой версии 1.0.0 и сравнит с текущей.
Если мы случайно внесли breaking change, то будет ошибка с описанием где именно проблема, с каким методом и т.п.
И здесь 2 варианта:
- (Лучше всего) поправить breaking change и зарелизить 1.2.0
- Если совсем никак, то поднять major версию до 2.0.0, написать в changelog информацию о breaking change и migration guide. И не забыть поднять PackageValidationBaselineVersion, иначе опубликовать пакет не удастся.
Ниже пример настройки валидатора:
net9.0
1.1.0
true
1.0.0
Так как валидация происходит при вызове dotnet pack, то в CI/CD нужно еще в Merge Request pipeline сделать dotnet pack, чтобы запустился валидатор и проверил на совместимость версий. Сразу поднимать текущую версию необязательно - валидатор все равно покажет ошибки.
Такой подход гораздо удобней применять при разработке своих NuGet пакетов
А для чужих библиотек - ApiCompat как из поста выше.
В тоже время анализатор позволяет ускорить inner loop, так как очевидные breaking changes подсвечивает прямо во время разработки в IDE. Но анализатор это не замена валидатора в CI/CD. Они скорее друг друга дополняют, потому что в CI проверки более глубокие, а анализатор не сложно отключить локально :)