search

ckeditor / ckeditor5

Powerful rich text editor framework with a modular architecture, modern integrations, and features like collaborative editing.
https://ckeditor.com/ckeditor-5
Other
9.49k stars 3.7k forks source link

Provide a single changelog that is easy to parse by a human being? #6058

Closed wwalc closed 4 years ago

wwalc commented 4 years ago

An idea for far far future. Not sure if the current changelog says much about what has changed in the software considering that all packages are getting new versions, even if nothing has changed in them. Considering the number of packages CKEditor 5 has, I'm not sure if anyone is able to tell what has changed from version to version. In CKEditor 4 it is much easier to say what has changed: https://github.com/ckeditor/ckeditor4/blob/major/CHANGES.md

Not sure if anyone needs such changelogs though since nobody reported it yet.

If the current format of the CKEditor 5 changelog is a major issue for you, add 👍 to this ticket.

Reinmar commented 4 years ago

Yup, the unfortunate regression of having everything in one version is that the main changelog is completely pointless. We need to rethink it, I've got it on my todo list already, but we didn't properly prioritized it yet.

Reinmar commented 4 years ago

Intro

I did a bit of a research and the changelog of a similar size that spoke best to me was https://github.com/angular/angular/blob/master/CHANGELOG.md. What I also found is that:

Proposal

You can find my proposal in https://gist.github.com/Reinmar/eb12358e84caae87dda862eb438089bd. It's heavily inspired by conventional changelog and Angular's changelog, but with adjustments for our standards and requirements.

Links:

wwalc commented 4 years ago

Look good to me :+1: I also find the Angular changelog easy to read & understand.

mlewand commented 4 years ago

@Reinmar Looks fine in general, it's actually quite similar to what I have proposed back in https://github.com/ckeditor/ckeditor5-dev/issues/606#issuecomment-605972964

Just to clarify:

Changes within one group (Bug fixes) should be sorted by the package name and date (asc). Non-scoped changes should be listed after scoped changes. Changes scoped to ckeditor5 should be listed first.

But this still means that the bug fixes can be reordered manually before the release, right? Sometimes we ship some critical bug fixes, important for the community, that should get proper exposure.

It would be great to wrap stuff in the "Released packages" section into a <details> & <summary> tags, so that it's folded by default and unfolded after clicking it. This will make it more human-oriented.

Reinmar commented 4 years ago

@Reinmar Looks fine in general, it's actually quite similar to what I have proposed back in ckeditor/ckeditor5-dev#606 (comment)

Haha :) Good to see that we came to the same conclusions.

But this still means that the bug fixes can be reordered manually before the release, right? Sometimes we ship some critical bug fixes, important for the community, that should get proper exposure.

I don't think it makes sense to reorder those items as this makes the order random at that point. If something's important, I'd add it to the release highlights.

However, your question made me think that perhaps we should order those changed by the date, not the scope. By ordering by the scope, I wanted to make it easier to check what changed in a particular package. But the truth is that with multi-package changes, you need to search for a specific name across all the items anyway. So, you will need to use the Ctrl+F to look e.g. for all things that changed in the engine. And that makes sorting by scope less reasonable. An alternative option would be to split a multi-package change to multiple items (one per scope name), but this will make the changelog longer.

So, I'd start with a changelog sorted by date (which is the simplest option) and we can think how to optimize this later. WDYT?

Reinmar commented 4 years ago

It would be great to wrap stuff in the "Released packages" section into a <details> & <summary> tags, so that it's folded by default and unfolded after clicking it. This will make it more human-oriented.

That's a great idea :+1:

wwalc commented 4 years ago

However, your question made me think that perhaps we should order those changed by the date, not the scope. By ordering by the scope, I wanted to make it easier to check what changed in a particular package. But the truth is that with multi-package changes, you need to search for a specific name across all the items anyway. So, you will need to use the Ctrl+F to look e.g. for all things that changed in the engine. And that makes sorting by scope less reasonable.

The problem with this approach is that unless you place dates in the changelog, for anyone looking at it from outside it will look messy and in a random order. Having it ordered by scope makes it easier to scroll all changes and stop on the packages that I'm interested in.

mlewand commented 4 years ago

By ordering by the scope, I wanted to make it easier to check what changed in a particular package.

I think it does it really well, and it is beneficial.

Group by change type vs package name 

If we group entries by package name, there would be benefit that you could easily inspect the package that interest you :+1: but there are some :-1: for that: we typically touch quite a few plugins during each release - so that would result with quite a few sections.

I think that grouping by change type has this benefit of placing features at the top. And I feel like this is what interests our community the most at this stage of the project. I personally also, before updating, check for braking changes first, then feature list. Rarely I check bug list, unless I really wait for something to be fixed (in which case I typically follow github issue for that).

To sum it up I think grouping by change type, sorted by package will be fine. It make sense to use highlights to expose most valuable bug fixes. :+1:

Reinmar commented 4 years ago

OK... so I lost 20 minutes of writing an answer here ;\<\<\< Gotta take another 20 minutes ;/

Reinmar commented 4 years ago

@mlewand, ordering by the type of the change is obviously a must have and wasn't under discussion.

What you may be missing is that a single change can touch multiple packages, in which case scanning just one fragment of the changelog for e.g. engine changes will not be enough as they may be spread across a couple locations. In fact, they will be spread across multiple places regardless of that, because we split changelog into new features, bug fixes and so on anyway.

Anyway, that's how the changelog will look if we go with what I originally proposed:

* core: Change in the core 1.
* core, engine: Change in the core 2.
* core, ui: Change in the core 3.
* engine, ui: Change in the engine 1.
* engine: Change in the engine 2.
* ui: Change in the ui 1.

To look for UI changes you need to scan the whole thing anyway. 

So, there are 4 options here:

All these options have their pros and cons. 3rd will give best results but may sometimes require more work from a developer. However, since unnecessary PRs to multiple repositories are to be avoided, perhaps this sort of motivation will be beneficial. Also, we don't always have to mention a change so if we made change in the engine and adjusted 3 packages to that change, we don't have to perhaps mention these 3 packages anyway.

mlewand commented 4 years ago

Also, we don't always have to mention a change so if we made change in the engine and adjusted 3 packages to that change, we don't have to perhaps mention these 3 packages anyway.

Just to clarify, you mean here to limit it down to a single package? What about having an option to skip the package name for these very generic changes (I don't think it will often be the case)

For instance in this iteration we picked up quite a few minor performance improvements. So far most of them are in the engine package, but what if we add couple more minor PRs like that to e.g. ui and utils packages.

It would be nice to conclude it with a generic "Improved processing editor performance. Closes #xyz, #xyz, #xyz, #xyz." note skipped package name (and as a result it should be sorted as a first item).

In general both options third and fourth sounds good to me - so the third is :+1:

Reinmar commented 4 years ago

Closes #xyz, #xyz, #xyz, #xyz.

BTW, I'm not sure support GH supports such notation (whether it will close all these tickets). Right now we use Closes #123. Closes #3456.

Reinmar commented 4 years ago

What we could do is turn the split notation (multiple "Closes") into one "Closes" when generating the changelog.

Reinmar commented 4 years ago

Just to clarify, you mean here to limit it down to a single package? What about having an option to skip the package name for these very generic changes (I don't think it will often be the case)

Yes, a single item in a commit message should be limited to a single package.

However, a single commit message can have multiple items.

An item may be scoped (generic) or not.

It makes sense to have ~5 items in a single commit message maximum. Above that, one generic item will usually be better.

tomalec commented 4 years ago

Closes #xyz, #xyz, #xyz, #xyz.

BTW, I'm not sure support GH supports such notation (whether it will close all these tickets). Right now we use Closes #123. Closes #3456.

Just tested that it closes only the first one. https://github.com/colliding-forks/test-issue-numbers-main/commit/6223f5db0963563eaab116fd082a10e0b5ab2158

tomalec commented 4 years ago

I'd like to put my tiny bit to the discussion.

Precisely the use of #xyz, org/repo#xyz vs https://github.com/org/repo/issues/xyz

As you can see in my example

Using just #xyz introduces a quite sneaky problem. If you marge from or to a fork it may close you some issues unintentionally. If you have separate issue boards in both repos, when you merge a commit with "Closes #123 (fix a typo in README)" from repo A to repo B, the issue #123 from repo B (the editor is crashing in Safari) will be closed as well. In my previous experience, it was really a sneaky foot gun, as we were losing the issues out of our radar, without apparent reason.

That's why personally, I prefer to use verbose links (full URL, or at least org/repo#123) in commit messages. It has a few benefits:

  1. Solves the problem mentioned above,
  2. Full URL allows simple click to open from any git client (not only Github one),
  3. Removes cognitive burden from the dev, like: "Was this issue reported in this repo, so I'd use #123, or from other repo, then repo#123..."
  4. Github shortens and prettifies them anyway so in GH you will see short descriptions. (https://github.com/colliding-forks/test-issue-numbers-main/commit/6223f5db0963563eaab116fd082a10e0b5ab2158, https://github.com/colliding-forks/test-issue-numbers-main/commit/e00a164e86b78916a87f95806da2f8f13d7c4082)

The high-level rationale behind such the approach is: Provide as complete data as possible, it's up to the git client to prettify and simplify the log.

jodator commented 4 years ago
  1. Github shortens and prettifies them anyway so in GH you will see short descriptions.

I'm too lazy to clone. Does it work if a commit message has a full link and Closes?

tomalec commented 4 years ago

You don't need to clone, just check git logs and issue boards

They are all pretty-printed by GitHub to hide unnecessary stuff.

Reinmar commented 4 years ago

I've got a problem with this. We agreed to use full links when referring to tickets in code comments.

To be consistent, we should do the same in PRs.

However:

So, I can see benefits, but I also see some issues and some of the benefits are not particularly big (due to their infrequency – reading git logs, merging across forks).

WDYT, @tomalec?

tomalec commented 4 years ago

In the changelog...

Totally agree, I consider the changelog a presentation of the data from git log. Shortening does not look like a complicated thing to achieve.

Sometimes we have multiple "Closes" phrases in a PR and then using full URLs may make that harder to write and validate before merging.

Personally, due to my dyslexia and poor memory, I rarely type issue number by hand, I usually paste it. Coping issue URL is even easier than copying its number. Same goes for validating, I cannot validate by just looking at the number, I'd rather open the issue (click on full URL).

I'm using an editor for markdown ...

Valid point, that workflow should work well.

Personally, I check git logs outside GitHub really rarely...

Personally, I check git logs outside my local client really rarely... ;) But I totally agree that I check the code waaay more often.

In general, I don't see full URLs a crucial thing, just a thing to consider. If the team is not reading the logs using local client often, we do not care about our or community forks too much, we do not have separated issue trackers for individual packages, and move towards monorepo, maybe that's not needed at all.

Reinmar commented 4 years ago

Thanks @tomalec. I gave it some time to "sink" and I'd still lean towards simplified notation. But we can change it if we see some recurring problems.

I'd like to close this ticket as most of the work on designing the new format was already done. The work on the changelog generator is tracked in ckeditor/ckeditor5-dev#606 and we can polish the tool in separate tickets one this lands.

Thank you all for fruitful brainstorming! I'm sure the new format will be much better than what we have now :)