search

CartoDB / carto-vl

CARTO VL: a Javascript library to create vector-based visualizations
BSD 3-Clause "New" or "Revised" License
129 stars 26 forks source link

Keep a Changelog #642

Closed IagoLast closed 6 years ago

IagoLast commented 6 years ago

I see 3 possible approaches here:

Manual Changelog

On every version bump/release manually update the changelog (something like the news.md file in builder)

Automated Changelog

Some tools like conventional changelog allow to create a well formated changelog with a command, the bad part if we had to use some commit standard for example: https://conventionalcommits.org/

Devlog

We had a similar issue with CARTO.js and we created a tool to generate a changelog without changing our commit rules, just using a quick code in the github merges

you know the pros & cons of each one so feel free to share your point of view @davidmanzanares @elenatorro @jgoizueta @Jesus89 @rochoa

davidmanzanares commented 6 years ago

I propose to use the guidelines shown here: https://keepachangelog.com/en/1.0.0/

From my point of view, we should update the changelog in each PR manually. I don't like the idea of automatizing it because usually there are many commits for just one feature, while there is one PR for each feature.

I think that we should enforce this convention by checking at code-review time that the changelog is updated.

rochoa commented 6 years ago

What if we could automate it based on the contents of the PR description?

Jesus89 commented 6 years ago

I'm not very fan of automation in this case, because IMO there is always a particular case that can not be covered with automation and external APIs. For example, a feature closed in two PRs or a dev-happiness PR you don't want to include in the changelog.

I think we can update manually the changelog in each PR, if required, as we did in Builder, but following the keepachangelog format: Added, Changed, Fixed, Removed (Deprecated, Security).

rochoa commented 6 years ago

Fair enough. If you are happy doing manually, I'm also happy. 😃We have been doing that in Engine API projects for years.

davidmanzanares commented 6 years ago

Manual then :rocket:

davidmanzanares commented 6 years ago

Do we agree on starting it after the next release?

I don't say to start it now because we would need to look back for previous changes to make the version complete.

Jesus89 commented 6 years ago

We have the changelog info for v0.6.0 version so I think we could add the information and continue after that.

Maybe for the public release, we should do a summary for the previous versions.

Jesus89 commented 6 years ago

I have added a branch with the changes from 0.6.0 (0.6.2 and unreleased) https://github.com/CartoDB/carto-vl/pull/814.

Please add anything that you miss since 0.6.0 in the file. And remember to follow always the principles https://keepachangelog.com/en/1.0.0/#how :scroll:

davidmanzanares commented 6 years ago

:+1:

Jesus89 commented 6 years ago

Closed by https://github.com/CartoDB/carto-vl/pull/814