CHANGELOG.md ガイド#

はじめに#

CHANGELOG.md ドキュメントは、開発者にとってもユーザーにとっても、プロジェクトの進化を追跡するための貴重なリソースとなります。変更履歴の構造と目的を理解することで、ユーザーや貢献者は各リリースで導入された新機能やバグ修正、その他の変更について常に情報を得ることができます。

CHANGELOG.mdとは？#

CHANGELOG.md の主な目的は、新しいリリースごとにプロジェクトに加えられた注目すべき変更の記録を提供することです。このドキュメントは、ソフトウェアの各バージョンで何が追加、修正、変更、削除されたかをユーザーが理解するのに役立ちます。

Keep a CHAGELOG.mdは、変更ログとは何か、どのように良い変更ログを作成するかを理解するための、シンプルで素晴らしいリソースです。また、避けるべきことの例も含まれています。

Pythonパッケージのバージョン管理とセマンティックバージョニング

変更履歴ファイルのバックボーンとなるパッケージの重要なコンポーネントは、優れたバージョン管理スキームです。セマンティック・バージョニングは Python パッケージ全体で広く使われています。

なぜそれが重要なのか？#

ユーザーや開発者との透明性のあるコミュニケーションには、よく管理された変更履歴が不可欠です。変更ログは、変更点を文書化し、各リリースでの進捗をハイライトするための一元的なハブとして機能します。変更履歴を常に最新の状態に保つことで、プロジェクトメンテナはユーザーベースとの信頼を築き、ソフトウェアを改善するというコミットメントを示すことができます。

その内容は？#

changelog.md ファイルの内容は一般的に構造化されたフォーマットに従い、各リリースで導入された変更の詳細を記述します。正確なフォーマットはプロジェクトの規約によって異なるかもしれませんが、 Python パッケージの changelog でよく見られる要素には以下のようなものがあります：

Versioning：セマンティックバージョニング、またはプロジェクトが採用するその他のバージョニングスキームを使って、各リリースのバージョンを明確に識別すること。
Release Date: 各バージョンが公開された日付で、変更のタイムラインのコンテキストを提供します。
変更カテゴリー: 変更を "Added," "Changed," "Fixed," "Removed" などのカテゴリーに整理し、ナビゲーションと理解を容易にします。
変更の内容: 新機能、機能強化、バグフィックス、非推奨機能を含む、各カテゴリーにおける変更点の簡潔な説明。
課題またはプルリクエストへのリンク: 各変更に関連する課題追跡項目またはプルリクエストへの参照で、ユーザーは必要に応じてより詳細な情報にアクセスできます。
アップグレード手順: 最新バージョンへのアップグレード方法に関するガイダンス、注意すべき変更点や移行手順を含みます。
コントリビューターの認識: リリースに多大な貢献をした貢献者を認識し、彼らの努力に対する感謝の気持ちと共同体意識を醸成します。

メンテナーはどのように使っているのか？#

多くの場合、変更履歴を見ることができます:

未リリースセクション#

未リリースのコミットは変更履歴の一番上にあり、一般的には Unreleased セクションにあります。ここには、前回のリリース以降にパッケージに追加された新しい修正、更新、機能を追加することができます。

このセクションは次のようなものです:

## Unreleased
* Fix: Fixed a bug.... more here. (@github_username, #issuenumber)
* Add: new feature to... more here. (@github_username, #issuenumber)

リリースセクション#

新しいリリースを作る準備ができたら、要素をその新しいリリース番号専用のセクションに移動させることができます。

この特定のリリースセクションは、未リリースセクションの下に位置し、更新、追加、非推奨、貢献者を含むことができます。

未発表のセクションは常にファイルの一番上にあり、新しい機能はそこに追加され続けます。同時に、v1.0のようなバージョンをリリースした後も、すべての機能はその特定のセクションに残ります。

## Unreleased

## v1.0

### Updates
* Fix: Fixed a bug.... more here. (@github_username, #issuenumber)

### Additions
* Add: new feature to ...more here (@github_username, #issuenumber)

### Deprecations

### Contributors to this release

それはどのようなものですか？#

この例はpyOpenSci受諾パッケージの Devicely から来ています。

# Changelog
All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

## [1.1.0] - 2021-08-24
- removed acceleration magnitude from devicely.EmpaticaReader and devicely.FarosReader since it was out of the scope of the package
- added more flexibility to missing files (e.g. ACC.csv, EDA.csv) to devicely.EmpaticaReader
- changed TagsReader to TimeStampReader to be more consistent with the class naming structure in devicely
- deprecated methods in devicely.SpacelabsReader: set_window and drop_EB
- fixed issue with the timestamp index and fixed column names in devicely.SpacelabsReader

## [1.0.0] - 2021-07-19
### Added
- devicely.FarosReader can both read from and write to EDF files and directories
- devicely.FarosReader has as attributes the individual dataframes (ACC, ECG, ...) and not only the joined dataframe

### Changed
- in devicely.SpacelabsReader, use xml.etree from the standard library instead of third-party "xmltodict"
- switch from setuptools to Poetry

### Removed
- removed setup.py because static project files such as pyproject.toml are preferred