CHANGELOG or History.txt

Implementation
1

Is there a CHANGELOG or History.txt for the spec / implementation?

That would be great to help following major changes.

True, we can follow the git log, but that is going to contain much more noise, like internals and typos.

2

I think

is going to be it for the forseeable future. Unless you’d rather @jgm spent his valuable time editing a bunch of commit comments versus getting improvements to the spec in :wink:

3

I think it might be worth the overhead: a one liner on important changes is simple to do, helps users a lot, and many projects deem it worthy (complex optimization problems of course).

No need to make a changelog for what has already been done, we could just start one.

1 Like
4

The “one liner” already exists in the existing commit comments, does it not?

1 Like
5

Yes, but it will contain noise like like internals, typos and very tiny changes which don’t matter to end users.

I think most of the commitst on that screenshot are minor internal changes that don’t matter to the end users of the compilers (not sure because don’t know much about the implementations).

In particular, I am only concerned with the spec so I will focus on changes to the spec file (which are the ones I can understand): https://github.com/jgm/CommonMark/commits/master/spec.txt But even that is not very good. Let’s analyse the last commits there:

  • Version 0.12. Will be a header on the changelog.
  • Added a link. What link? -> open commit ->Ah, formatting minor improvement. Should not be on CHANGELOG.
  • Allow images to contain images. Good, this should be on CHANGELOG.
  • Bump spec version to 0.11. Header.
  • Spec: use terminology of “image description” rather than “alt text”. Too minor for changelog since just clarification.
  • Fixed spec tests. Too minor.
  • Fixed 2 typos in spec tests. Nope.
  • Updated spec for links. Hmm, how? Let’s see the commit. Second commit line: Still a work in progress. Hmm, not in CHANGELOG.

So I would filter all of that to just:

0.12

  • Allow images to contain images

0.11

going down from 8 lines to just 3, and easier to see where versions start and end.

6

Well, the way we deal with this on the Discourse project is to include a prefix on changes that are “significant”, e.g:

FIX: divide by zero error in blah.js
FEATURE: add a fooblatz meter

Then you can just filter all changes for the prefixes – all changes without prefixes are more trivial – and you have the significant changes.

1 Like
7

Commit tagging would be good enough for me :wink:

8

Yes, I agree this is important.

Just yesterday I added infrastructure to the spec release/website generation code that will add a link to a side-by-side diff with changes to the spec, for each new version going forward. So far there’s only an example for the 0.12 release. See http://spec.commonmark.org and click on the link to “changes” by the 0.12 release.

9

I have tagged the last couple releases and will do so going forward.

3 Likes
10

Changelogs are useful. The proposed git solution is elegant too - it is always worth looking for simpler solutions. That point is relevant to any aspect of the project. In some cases, additional features (e.g. proposed extensions) have be scaled not just to reference implementations but to multiple implementations, apps, and end users (user comprehension).