ivanhercaz

ivanhercaz

Strategies for use changelogs and bump versions

Hi!
I usually keep changelogs for my projects because I think they are really useful, not only to track the changes and not to be lost between them, but also to share with work mates or even to share with the project managers.

I follow different strategies to track the changes and it always depends of some facts, for example:

  • If I already release a first version of the project, I apply the semantic versioning specification. So I try to keep a changelog related with the version.
  • But sometimes I have not release a version yet, because it is a project under development of the first version or we don’t consider it to have the features needed to be considered as 0.1.0 version. In these cases I also write a changelog, but usually date-based. For example, I am working in a #nerves project in which I have not released a first version of the firmware yet, but I have to present the changes and new features done or in which I am working, so I attached to the release file name a date and then in the changelog I track what is done in this version.

I also have used another strategies but I am interested to know what others do and how they usually track the changes, because it is probably that I could improve my workflow knowing more about how other developers works.

Of course, there are practices that I don’t seem very useful, like the changelogs that are composed of commits, because I think it can be confused and for that I can see directly the commits made in the repository.

I usually work with #elixir so I am also interested in tools that can help to use changelogs or even to bump the version (something that sometimes I miss because I am bit clueless hehe). I searched on Hex for “changelog” and I found some packages to work with that, like git_ops (git_ops | Hex) and version_release (https://hex.pm/version_release).

I already have some pending reading, like Keep a Changelog, that seems a spec for writing changelogs with useful advices. If you know some interesting reading about it, I will be really grateful if you share it here.

And, as an extra (:joy:) bonus question: if you a project in which you are working that it is not prepared yet to be considered as a 0.1.0 version but you have to show to your work mates and to the project manager, do you think it would be appropriate and useful to present them as release candidate versions?

I wish someone finds this topic as interesting as it is for me :smiling_face_with_three_hearts:

Most Liked

Eiji

Eiji

If I would decide then I would like to have something between Keep a Changelog and Elixir/Phoenix changelog files.

  1. Firstly I would use a text from Keep a Changelog as a top information:
# Changelog

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

The format is based on [Keep a Changelog](keepachangelog.com),
This project adheres to [Semantic Versioning](semver.org).
  1. Secondly based on Elixir and Phoenix repositories I would like to split a CHANGELOG.md between branches, so it would not be too long.

  2. From Elixir changelog a -dev release would be a huge inspiration as well as -rc. (release candidate) naming

  3. I would link related wikis, issues and pull requests

  4. Finally again following Elixir and Phoenix repositories I would like to link to a previous CHANGELOG.md file in other branch

Yeah, I also think that mentioning commits does not makes sense. Instead I would like to have a quick links to:

  1. Wiki which describes the features of application from user perspective
  2. Issue which describes the features from developer perspective
  3. PR which describes implementation details

The PR itself contains all lists of commits and references Issue. The Issue also references to Wiki. This way everyone can quickly navigate between Release/Changelog, PR (implementation), Issue (dev discussion) and Wiki (user needs), so the whole project stays clean and allows everyone to understand the project at all levels.

Something like:

## v1.1.0-dev

### Features

#### App name (in case umbrella)

##### Feature name

* **User perspective**: wiki#1
* **Developer perspective**: issue#1
* **Implementation details**: pr#1, pr#2, … (more than one in case of PR for each bug fix)

### Enhancements

#### App name (in case umbrella)

##### Enhancement name

* **User perspective**: wiki#2
* **Developer perspective**: issue#2
* **Enhances**: issue#1
* **Implementation details**: pr#3

### Bug fixes

#### App name (in case umbrella)

##### Bug name

* **Developer perspective (i.e. bug report)**: issue#4
* **Affect feature/enhancement**: issue#1
* **Implementation details**: pr#4

### 3. Soft deprecations (no warnings emitted)

#### App name (in case umbrella)

##### Deprecated feature/enhancement

* **Deprecates**: issue#5
* **In favor of**: issue#6

### Hard deprecations

#### App name (in case umbrella)

##### Deprecated feature/enhancement

* **Deprecates**: issue#5
* **In favor of**: issue#6

## v1.0

The CHANGELOG for v1.0 releases can be found [in the v1.0 branch](<link to changelog in 1.0 branch>).

As above 0.1.0-dev branch and it’s README.md file.

Where Next?

Popular General Dev topics Top

Devtalk
Reading something? Working on something? Planning something? Changing jobs even!? If you’re up for sharing, please let us know what you’...
1033 17470 383
New
AstonJ
:smiling_imp: What is your preferred syntax style and why? Perhaps we can add examples and use the code below as a simple reference poi...
New
AstonJ
If you could work on any project, what would it be? :upside_down_face:
New
AstonJ
Do you think it’s worth worrying about? Do you think it’s going to be an even bigger issue in future? If so what can the teams of smaller...
New
jamiedumont
This is all going to be a bit hand-wavey and straight off the top of my head, so bear with me, but it’s a thought/debate that’s been ratt...
New
dwaynebradley
For those that are interested, Snyk (developer security tool) announced support for Elixir earlier this week: Just thought I’d pass it...
New
AstonJ
Slightly different to the What does your mobile phone home screen look like? thread, what is your lock screen image?
New
AstonJ
I’ve been watching Prag Dave’s Elixir course and I noticed he uses tree: Tree is a recursive directory listing program that produces a ...
New
ivanhercaz
Hi! I usually keep changelogs for my projects because I think they are really useful, not only to track the changes and not to be lost b...
New
harwind
I’m working on a Spring Boot project and I have a controller where I want to map multiple request paths to a single method. Let’s say I h...
New

Other popular topics Top

Rainer
My first contact with Erlang was about 2 years ago when I used RabbitMQ, which is written in Erlang, for my job. This made me curious and...
New
AstonJ
I have seen the keycaps I want - they are due for a group-buy this week but won’t be delivered until October next year!!! :rofl: The Ser...
New
AstonJ
This looks like a stunning keycap set :orange_heart: A LEGENDARY KEYBOARD LIVES ON When you bought an Apple Macintosh computer in the e...
New
Rainer
Not sure if following fits exactly this thread, or if we should have a hobby thread… For many years I’m designing and building model air...
New
AstonJ
We’ve talked about his book briefly here but it is quickly becoming obsolete - so he’s decided to create a series of 7 podcasts, the firs...
New
PragmaticBookshelf
Author Spotlight Jamis Buck @jamis This month, we have the pleasure of spotlighting author Jamis Buck, who has written Mazes for Prog...
New
Help
I am trying to crate a game for the Nintendo switch, I wanted to use Java as I am comfortable with that programming language. Can you use...
New
PragmaticBookshelf
Author Spotlight: Karl Stolley @karlstolley Logic! Rhetoric! Prag! Wow, what a combination. In this spotlight, we sit down with Karl ...
New
First poster: bot
Large Language Models like ChatGPT say The Darnedest Things. The Errors They MakeWhy We Need to Document Them, and What We Have Decided ...
New
AstonJ
If you’re getting errors like this: psql: error: connection to server on socket “/tmp/.s.PGSQL.5432” failed: No such file or directory ...
New