Есть ли автоматический способ создания списка изменений интерфейса?

Question

Я разрабатываю/поддерживаю библиотеку Java и хочу отслеживать назад-несовместимые изменения между релизами. Этот список может содержать изменения в объявлениях классов, сигнатурах методов и т. Д.

Например, если я (случайно) изменил конструктор, добавив параметр, то я хотел бы включить его в список и предупредить об изменении ,

// before 
public MyCar(String name) { ... } 

// after (some accidental change) 
public MyCar(String name, long mileage) { ... } 
// an application using my library depending on this constructor would be broken 
// when it updates to the new version 

Есть ли автоматический способ создания этого списка? Это похоже на то, что IntelliJ или Gradle должны делать.

Моя команда попыталась проверить запросы на тяну и вручную сохранить CHANGELOG (что, по-видимому, является общим подходом), но это связано с человеческими ошибками. Я ищу автоматический способ, который в идеале может быть частью системы сборки.

Answer 1

Я всегда поддерживал список совместимости вручную, но иногда забываю что-то.

Быстрый просмотр вокруг показывает несколько библиотек с открытым исходным кодом, но у них не было новых версий, выпущенных почти за 10 лет. Поэтому я не знаю, будут ли они работать с новыми функциями Java 7 или 8.

Примечание: Я никогда не использовал их!

CLIRR - проект apache, используемый некоторыми другими проектами apache, чтобы показать, что изменилось (например, вывод из apache commons-lang here.последний обновленный в 2005 году даже не построен с Maven 2 (или 3)

JDiff javadoc doclet компаратор. Может поддерживать Java 5. Последнее обновление в 2008 году

Japitools - по-видимому, был использован проектом GNU Classpath для сравнения их API для совместимости подписи с различными версиями библиотек классов Java Java. Не похоже, что он обновлен с 2006 года

Answer 2

Есть лучший способ сделать это.

Сохраните обратную совместимость на время, аннотируя свои методы с помощью @Deprecated и указывайте, когда они будут неподдерживаться. Затем добавьте @deprecated в свой Javadoc, и это будет automatically generate a list of deprecated features, о котором должен заботиться конечный пользователь.

Это имеет дополнительное преимущество, что позволяет вводить, когда функция была введена (@since), и когда функция будет удалена без необходимости суетиться слишком много с большим количеством других инструментов.

Поскольку вы добавили более конкретный пример кода, я добавлю еще один примечание: эти виды изменений ... являются результатом сознательного решения дизайна, и это выдвигает на первый план два вопроса:

• регрессионного тестирования (как, тест должен уловили это)
• Простота перехода в новую API (как, если мне нужно, чтобы внезапно дать новый параметр для этого, чтобы получить функциональность, не так ли новая вещь, а не привязанность к старой, старой вещи?)

Эти проблемы нельзя поддразнить любыми обычными инструментами; что требует серьезного разговора о количестве времени, которое требуется для перехода от одного API к другому. Если вы обнаружите, что вам нужно внедрить новую функциональность в ядро, тогда вам лучше задуматься, что не нарушило устаревший случай.

Это то, что означает иметь API - у вас есть, чтобы иметь более старую версию, скрывающуюся некоторое время.