Guía de CHANGELOG.md#

Introducción#

El documento CHANGELOG.md sirve como un recurso valioso tanto para los desarrolladores como para los usuarios para seguir la evolución de un proyecto a lo largo del tiempo. Comprender la estructura y el propósito de un registro de cambios ayuda a los usuarios y colaboradores a mantenerse informados sobre nuevas características, correcciones de errores y otros cambios introducidos en cada versión.

¿Qué es CHANGELOG.md?#

El propósito principal de CHANGELOG.md es proporcionar un registro de los cambios notables realizados en el proyecto con cada nueva versión. Este documento ayuda a los usuarios a comprender qué se ha añadido, corregido, modificado o eliminado con cada versión del software.

Keep a Changelog is a great, simple resource for understanding what a changelog is and how to create a good changelog. It also includes examples of things to avoid.

Versionado de tu paquete de Python y versionado semántico

Un componente importante de un paquete que sirve como la columna vertebral del archivo de registro de cambios es un buen esquema de versiones. El Versionado Semántico es ampliamente utilizado en los paquetes de Python.

¿Por qué es importante?#

Un registro de cambios bien mantenido es esencial para una comunicación transparente con los usuarios y desarrolladores. Sirve como un centro centralizado para documentar los cambios y resalta el progreso realizado en cada versión. Al mantener el registro de cambios actualizado, los mantenedores del proyecto pueden generar confianza con su base de usuarios y demostrar su compromiso con la mejora del software.

¿Qué incluye?#

The contents of a CHANGELOG.md file typically follow a structured format, detailing the changes introduced in each release. While the exact format may vary depending on the project’s conventions, some common elements found in changelogs for Python packages include:

  • Versionado: Identificación clara de cada versión de lanzamiento utilizando el versionado semántico u otro esquema de versionado adoptado por el proyecto.

  • Fecha de lanzamiento: La fecha en que se lanzó cada versión al público, proporcionando contexto para la cronología de los cambios.

  • Categorías de los cambios: Organizar los cambios en categorías como «Añadido», «Cambiado», «Corregido» y «Eliminado» para facilitar la navegación y la comprensión.

  • Descripción de los cambios: Una descripción concisa de los cambios realizados en cada categoría, incluyendo nuevas características, mejoras, correcciones de errores y funcionalidades obsoletas.

  • Enlaces a problemas o Pull Requests: Referencias a elementos relevantes del seguimiento de problemas o pull requests asociados a cada cambio, lo que permite a los usuarios acceder a información más detallada si es necesario.

  • Instrucciones de Actualización: Guía para los usuarios sobre cómo actualizar a la última versión, incluyendo cualquier cambio que rompa la compatibilidad o los pasos de migración que deban tener en cuenta.

  • Reconocimiento a los colaboradores: Agradecimiento a los colaboradores que hicieron contribuciones significativas a la versión, fomentando un sentido de comunidad y aprecio por sus esfuerzos.

¿Cómo lo usan los mantenedores?#

A menudo verás un registro de cambios que documenta algunas cosas:

Sección Sin Publicar#

Los commits no publicados están en la parte superior del registro de cambios, comúnmente en una sección Sin publicar. Aquí es donde puedes añadir nuevas correcciones, actualizaciones y características que se han añadido al paquete desde la última versión.

Esta sección podría tener un aspecto similar a este:

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

Secciones de Publicación#

Cuando estés listo para publicar una nueva versión, puedes mover los elementos a una sección específica para ese nuevo número de versión.

This specific release section will sit below the unreleased section and can include any updates, additions, deprecations and contributors.

The unreleased section then always lives at the top of the file and new features continue to be added there. At the same time, after releasing a version like v1.0 all of its features remain in that specific section.

## 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

¿Cómo se ve?#

Este ejemplo es de Devicely, un paquete aceptado por pyOpenSci

# 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