Журнал изменений

Журнал изменений (также пишется как журнал изменений ^[1]) — это журнал или запись всех заметных изменений, внесенных в проект. Проект часто представляет собой веб-сайт или проект программного обеспечения, и журнал изменений обычно включает записи об изменениях, таких как исправления ошибок, новые функции и т. д. Некоторые проекты с открытым исходным кодом включают журнал изменений в качестве одного из файлов верхнего уровня в своем дистрибутиве.

Журнал изменений исторически включал все изменения, внесенные в проект. Вместо этого сайт «Сохраняйте журнал изменений» выступает за то, чтобы журнал изменений не включал все изменения, а вместо этого содержал «кураторский, хронологически упорядоченный список заметных изменений для каждой версии проекта» и не должен быть «свалкой» git log, «потому что это никому не поможет». ^[2]

Хотя GNU ( Automake каноническое соглашение об именовании файла ) — ChangeLog , ^[3] иногда его альтернативно называют ИЗМЕНЕНИЯ или ИСТОРИЯ ( НОВОСТИ обычно представляют собой другой файл, отражающий изменения между выпусками, а не между коммитами). Другое соглашение — называть его CHANGELOG . ^[2] Некоторые сопровождающие проекта добавляют суффикс .txt к имени файла, если журнал изменений представляет собой обычный текст , суффикс .md, если он находится в Markdown , или суффикс .rst, если он находится в reStructuredText .

Некоторые системы контроля версий способны генерировать соответствующую информацию для журнала изменений, если цель состоит в том, чтобы включить все изменения. ^[4]

Формат

Файлы журнала изменений организованы по абзацам, которые определяют уникальные изменения внутри функции или файла. Стандарты кодирования GNU рекомендуют следующий формат: ^[5]

YYYY-MM-DD␣␣John Doe␣␣<[email protected]>

    * myfile.ext (myfunction): my changes made
    additional changes.

    * myfile.ext (unrelated_change): my changes made
    to myfile.ext but completely unrelated to the above.

    * anotherfile.ext (somefunction): more changes made by me.

Между датой и именем, а также между именем и адресом электронной почты есть по два пробела. Обычно адрес электронной почты заключают в < и >. Редактор Emacs создает такие записи при создании дополнительных записей журнала изменений.

Формат журнала изменений для упаковки

Когда программное обеспечение поддерживается под контролем версий, например, git или более старым svn или даже гораздо более старым cvs , и распространяется через такой пакет, как RPM Package Manager , формат файла журнала изменений отличается, например:

* Mon Aug 05 2024 johndoe <[email protected]> (583f243)
- myfile.ext (myfunction): my changes made additional changes.

* Fri Jul 19 2024 johndoe <[email protected]> (a18761f)
- myfile.ext (unrelated_change): my changes made
    to myfile.ext but completely unrelated to the above.

* Fri Jul 19 2024 johndoe <[email protected]>  (a739b6f)
- anotherfile.ext (somefunction): more changes made by me.

Такой файл обычно можно создать из внутренней базы данных используемого контроля версий. Например, в git формат даты должен опускать время и часовой пояс. В приведенной ниже команде сокращенный хеш коммита в скобках добавляется :

git log --date=format:"%a %b %d %Y" --pretty="tformat:* %ad %an <%ae> (%h)%n- %s%b%n" >Changelog

Пакет RPM сам создается из файла с расширением . расширение спецификации , а история изменений, содержащаяся в файле журнала изменений, вставляется в самом конце, после тега %changelog. Чтобы получить доступ к истории установленного пакета, такого как foo.rpm, опция запроса --changelog:

$ rpm -q --changelog foo
* Mon Aug 05 2024 johndoe <[email protected]> (583f243)
- myfile.ext (myfunction): my changes made additional changes.
...

Журналы изменений в вики

Большинство вики- программ включают журналы изменений в качестве фундаментальной функции (в этом контексте часто называемой историей ). Например, ссылка «Просмотреть историю» вверху. ^[6] записи в Википедии ссылается на журнал изменений этой страницы. Эта функция жизненно важна для соблюдения требований об атрибуции некоторых лицензий на авторские права. ^{[ нужна ссылка ]}

Журналы изменений продукта

Журнал изменений продукта может держать клиентов в курсе того, что нового. Это помогает анонсировать новые функции, последние выпуски и актуальные новости прямо в приложении. ^{[ нужна ссылка ]}

См. также

Примечания

^ «Определение журнала изменений» . Юридический инсайдер . Проверено 7 ноября 2023 г.
^ Перейти обратно: ^а ^б «Ведите журнал изменений» . Keepachangelog.com .
^ Руководство GNU automake .
^ Атласиан. «Что такое контроль версий | Учебное пособие по Atlassian Git» . Атласиан . Проверено 17 февраля 2022 г.
^ «Стандарты кодирования GNU: стиль журналов изменений» . Gnu.org . Проверено 03 сентября 2019 г.
^ Справка: История_страницы .

Внешние ссылки

[1] «Определение журнала изменений» . Юридический инсайдер . Проверено 7 ноября 2023 г.

[keepachangelog-2] Перейти обратно: ^а ^б «Ведите журнал изменений» . Keepachangelog.com .

[3] Руководство GNU automake .

[4] Атласиан. «Что такое контроль версий | Учебное пособие по Atlassian Git» . Атласиан . Проверено 17 февраля 2022 г.

[5] «Стандарты кодирования GNU: стиль журналов изменений» . Gnu.org . Проверено 03 сентября 2019 г.

[6] Справка: История_страницы .

[1]

[2]

[3]

[4]

[5]

[6]