search

microsoft / PowerToys

Windows system utilities to maximize productivity
MIT License
109.7k stars 6.46k forks source link

Ideas for the next changelog 0.31 #8816

Closed Aaron-Junker closed 3 years ago

Aaron-Junker commented 3 years ago

Three things we could make in the changelog for 0.31:

  1. Make better visible what's new and what is a bug fix. We could make it like Opera GX in their changelog and add "[New]" and "[Bug]" before every point in the changelog. Example:

    ...
FancyZones:
* [New] Added ...
* [New] Added ...
* [Bug] Fixed a bug where ...
Keyboard Manager:
...

  2. List the helpers in reversed alphabetic order

  3. Add a list with common known issues. (This list could be updated also after release) That would help preventing duplicates.

htcfreek commented 3 years ago

Regarding point 2: Not sure what the usecase would be.

Regarding point 3: We could create a version independent list ehich is simply to manage. Maybe in the new docs that they are manageable by PRs.

Aaron-Junker commented 3 years ago

@htcfreek

  1. That the helpers that be named the last in this changelog get named first in the next changelog
Jay-o-Way commented 3 years ago

Using categories like "new" and "fixed" and "improved" is a good idea. Question: what should be the first level? The PowerToy (as in your example), or these categories?

Suggestion: https://keepachangelog.com/en/1.0.0/ or https://co-pilot.dev/changelog

Jay-o-Way commented 3 years ago

I mean, would we prefer... (A)

or... (B)

Aaron-Junker commented 3 years ago

I mean, would we prefer... (A)

  • Color Picker

    • [new] function
    • [changed] function
    • [fixed] bug

  • FancyZones

    • [new] function
    • [changed] function
    • [fixed] bug

or... (B)

  • New

    • new function description
    • more new things

  • Fixed

    • bug description (#1234)
    • bug description (#5678)

  • Changed

    • from A to B

I like both. But i qould use (A) becuase it's the nearest to the one we have at the moment

taulantjj commented 3 years ago

[Bug] Fixed a bug where ...

taulantjj commented 3 years ago

Actual result

crutkas commented 3 years ago

this is hard be precise and very time since it requires going through every PR and issue for that release and fully understanding what it does and describing it.

If you look at what Opera did "[FIX] Crash fixes". Great, what crash?

crutkas commented 3 years ago

Lets pivot back to, who is asking for more detailed information that is not in the release notes already? no one has asked for more than what we currently put in the release notes which then DO link to the full issue list we've closed.

enricogior commented 3 years ago

Let's do a better job to label issues, and have very precise issue titles, since that provides the same information with a simple query and does also help the core team searching for regressions when they happen. Other than that I don't think that adding more detailed info in the release notes help anyone.

Aaron-Junker commented 3 years ago

OK. @enricogior @crutkas What is your opinion to Point 2 and 3.

Let's do a better job to label issues, and have very precise issue titles

The problem is with the triage perm you can't change titles of issues. Should I then tag someone from the core team who could change the title when I see an issue where we could add a better title?

enricogior commented 3 years ago

@Aaron-Junker I don't think the release notes are read by the majority of the users, but having a place to list current know issues might be a good idea, we should decide if the correct place is the release notes or a wiki page, since a problem may still be present from a previous release and we don't want to add too much work in preparing the release notes or the problem might be found way before the release notes and it would be better to log it right away and not wait for the release notes.

Regarding changing the titles, this should be part of the process of opening a PR, only at that moment we can set the appropriate title, it's kind of pointless to try to figure out the proper title before knowing exactly what the problem is and how it manifests. Often a bug report describe one specific case that may be misleading but it might be difficult to know that before finding the root cause.

crutkas commented 3 years ago

@Aaron-Junker how about taking the 0.29 release and give an example of what would be a better way to do the release notes if you feel they aren't at the quality you think they should be.

  1. For reverse alphabetical, why? I picked a common pattern and stuck with it across everything
  2. what do you feel are the current common issues?
just1a-person commented 3 years ago

I don't think the release notes are read by the majority of the users

I actually do that. I think people using PowerToys would be more inclined to read the changelog because most of them are excited about the new features that we might potentially add.

Aaron-Junker commented 3 years ago

So if I see that right @crutkas does always write the changelog. We could make it easier by adding a file and every time someone adds a feature or fixes a bug (s)he should add this to the changelog. Like I also do this and its much easier then writing the changelog at the end: https://github.com/Case-Games/USOC/blob/master/docs/CHANGELOG.md

Jay-o-Way commented 3 years ago

I don't think the release notes are read by the majority of the users

Got any statistics to back that assumption up?

enricogior commented 3 years ago

@Jay-o-Way

Got any statistics to back that assumption up?

I don't have page view numbers, but given we don't receive feedback on the release notes (no one is asking for clarification or other things) and given that the auto updates has removed the requirement to visit the release page to download the installer, I guess it's a safe bet.

crutkas commented 3 years ago

So is the ask to create a changelog.md versus change the format of the release notes? @Aaron-Junker I still do not believe my question was answered for what adjustments would be needed.

@jay-o-way, this is really the first time someone has asked for a tweak. And it with what i would say the core group. We follow a format that is close to VS Code / Terminal. Notable fixes and things that are important for end users, not for the people actively developing against PowerToys. I'm willing to bet a beverage of everyone's choice 99% of users don't are we are shifting from one data type to another or one framework to another. What they do care is we took multiple steps to support ARM64 and can link to the Issues / PRs.

crutkas commented 3 years ago

TLDR: Right now, i (aka person that does the change logs) really don't know what is actionable here

ghost commented 3 years ago

This issue has been automatically marked as stale because it has been marked as requiring author feedback but has not had any activity for 5 days. It will be closed if no further activity occurs within 5 days of this comment.