anuraghazra
Changelog
I think it would be quite useful for this project to log the changes. There have been quite a few significant changes over the past few months, including an updated of rank system, new language card layouts, the ability to show new data on the stats card, some query options have been removed, and more. Most users are unlikely to be able to see small changes in the documentation to learn about all these changes. Because of this, users often create many issues and discussions with the same questions. It would be nice to have some place, such as a CHANGELOG.md file, that would list all significant changes and the user could easily understand what has changed since his last visit to the repository. In this way, we would make it easier for ourselves to support the project, as we will spend less time answering issues and discussions. What do you think about this, @rickstaa?
@qwerty541 I like the idea of a changelog together with releases. I discussed this with @anuraghazra, but versioning could be better for libraries (see https://github.com/anuraghazra/github-readme-stats/issues/1768). When a new version is released, it is usually placed on an API/v2 namespace. We can, however, still release versions and an accompanying changelog for development purposes if @anuraghazra is okay with it 👍🏻. I use https://github.com/google-github-actions/release-please-action in most of my repositories to automatically version and create changelogs based on the Conventional commits convention. See https://github.com/rickstaa/stable-gym for an example.
@qwerty541 I like the idea of a changelog together with releases. I discussed this with @anuraghazra, but versioning could be better for libraries (see #1768). When a new version is released, it is usually placed on an
API/v2namespace. We can, however, still release versions and an accompanying changelog for development purposes if @anuraghazra is okay with it 👍🏻. I use https://github.com/google-github-actions/release-please-action in most of my repositories to automatically version and create changelogs based on the Conventional commits convention. See https://github.com/rickstaa/stable-gym for an example.
@rickstaa I suggest adding a changelog first of all for the convenience of users, so we don't need a listing of all commits, which can be viewed anyway, but a list of only significant changes, which will need to be maintained manually. Therefore, I think that this tool https://github.com/google-github-actions/release-please-action is not suitable.
I would like to see something like:
### 07-2023
- Added ability to show started and answered discussions count on stats card
### 06-2023
- Released new ranking system (some details...)
- Stats card no longer support query option `&count_private=true`
- Added ability to show reviews count on stats card
### 05-2023
- Added new layouts for top languages card (`donut`, `pie` and `donut-vertical`).
If instead every small change in documentation or code style is added, then the changelog will be useless, since it will be no easier to find out from it what's new in the project than from the commit history.
@qwerty541 I like the idea of a changelog together with releases. I discussed this with @anuraghazra, but versioning could be better for libraries (see #1768). When a new version is released, it is usually placed on an
API/v2namespace. We can, however, still release versions and an accompanying changelog for development purposes if @anuraghazra is okay with it 👍🏻. I use https://github.com/google-github-actions/release-please-action in most of my repositories to automatically version and create changelogs based on the Conventional commits convention. See https://github.com/rickstaa/stable-gym for an example.@rickstaa I suggest adding a changelog first of all for the convenience of users, so we don't need a listing of all commits, which can be viewed anyway, but a list of only significant changes, which will need to be maintained manually. Therefore, I think that this tool https://github.com/google-github-actions/release-please-action is not suitable.
I would like to see something like:
### 07-2023 - Added ability to show started and answered discussions count on stats card ### 06-2023 - Released new ranking system (some details...) - Stats card no longer support query option `&count_private=true` - Added ability to show reviews count on stats card ### 05-2023 - Added new layouts for top languages card (`donut`, `pie` and `donut-vertical`).If instead every small change in documentation or code style is added, then the changelog will be useless, since it will be no easier to find out from it what's new in the project than from the commit history.
By default, the https://github.com/google-github-actions/release-please-action tool only creates a release and accompanying changelog for fix and feat tagged commits. As a result, keys with doc, ci, or other conventional commits don't create a new release (see https://github.com/rickstaa/stable-gym/blob/main/CHANGELOG.md).
That said, I'm not a fan of manually maintained changelogs since it adds another component that can become outdated 😅. If people follow the conventional commit convention, the information you are looking for is already found under https://github.com/anuraghazra/github-readme-stats/pulls?q=is%3Apr+is%3Amerged+feat search query. GitHub's beta activity view is also very detailed (See https://github.com/anuraghazra/github-readme-stats/activity) 🤔.
@qwerty541 I like the idea of a changelog together with releases. I discussed this with @anuraghazra, but versioning could be better for libraries (see #1768). When a new version is released, it is usually placed on an
API/v2namespace. We can, however, still release versions and an accompanying changelog for development purposes if @anuraghazra is okay with it 👍🏻. I use https://github.com/google-github-actions/release-please-action in most of my repositories to automatically version and create changelogs based on the Conventional commits convention. See https://github.com/rickstaa/stable-gym for an example.@rickstaa I suggest adding a changelog first of all for the convenience of users, so we don't need a listing of all commits, which can be viewed anyway, but a list of only significant changes, which will need to be maintained manually. Therefore, I think that this tool https://github.com/google-github-actions/release-please-action is not suitable. I would like to see something like:
### 07-2023 - Added ability to show started and answered discussions count on stats card ### 06-2023 - Released new ranking system (some details...) - Stats card no longer support query option `&count_private=true` - Added ability to show reviews count on stats card ### 05-2023 - Added new layouts for top languages card (`donut`, `pie` and `donut-vertical`).If instead every small change in documentation or code style is added, then the changelog will be useless, since it will be no easier to find out from it what's new in the project than from the commit history.
By default, the https://github.com/google-github-actions/release-please-action tool only creates a release and accompanying changelog for
fixandfeattagged commits. As a result, keys withdoc,ci, or other conventional commits don't create a new release (see https://github.com/rickstaa/stable-gym/blob/main/CHANGELOG.md).That said, I'm not a fan of manually maintained changelogs since it adds another component that can become outdated 😅. If people follow the conventional commit convention, the information you are looking for is already found under https://github.com/anuraghazra/github-readme-stats/pulls?q=is%3Apr+is%3Amerged+feat search query. GitHub's beta activity view is also very detailed (See https://github.com/anuraghazra/github-readme-stats/activity) thinking.
I'm not sure that we need releases since this project is not published as NPM package or etc.
Maybe https://github.com/google-github-actions/release-please-action is good tool at all, but i think that not in our case, bacause we don't need releases and we can't generate changelog for recently added features since we not followed conventional commints rules.
Regarding to the fact that we are adding another component that may become outdated, I disagree here. For example, translations of documentation become outdate because we do not know the languages required for quality translation. That is, we completely lack the ability to fully support this component. In the case of a changelog, the only reason it can become outdated is laziness. It's not often that we add some significant functionality that is supposed to be reflected in the changelog.
Would you mind a merge pull request if I make a small changelog based on the example provided above?
My thoughts on changelog:
While the idea is good, in practice specifically in context of GRS changelogs won't really create any significant impact and instead introduce further process,steps & effort when merging PRs (from internal or external contributors)
I'm fine with a manual CHANGELOG.md also, just that automating it and making it a process will create lot of friction which isn't necessary for GRS.
Let's understand a typical need for a changelog:
- A package usually need changelog to not just communicate changes but also document BREAKING CHANGES, feature updates patches etc
- The changelog helps users while migration of the package to newer version or downgrading for whatever reason, they can look for a specific version see if there are any breaking changes and update their code as needed or recommended by the changelog changes
Now let's understand why it doesn't make sense for us:
- For the point 1, while the changelog will certainly help to document the changes I would recommend documenting them on the readme itself or in context of the feature, imagine we change something on ranking system once we change the ranking logic a user would never be able to roll back to the previous ranking system since our api will always serve the latest code, thus just document it should be enough.
- Again, as pointed out before a changelog is beneficial for general migration/breaking change migration, etc. For us our API will always return the latest code so users can never downgrade to previous versions or choose a specific version of GRS.
- And as for breaking changes I think so far we have never done a breaking change and moving forward we should not do any breaking changes unless it's absolutely needed because our API route itself isn't versioned so any breaking change will break thousands of GRS cards.
- Adding changelog will increase the friction and the changelog details you anyway have to manually write down properly, if you don't write meaningful changelogs it's as good as not having them, imagine for the ranking change we added a changelog with msg "Did some changes to ranking system, yolo" is that helpful? Not really. So anyway you have to make sure to write an essay of the changes, why we did the changes etc in a well documented manner and at this point just writing it properly in the readme itself will be better option either way.
So the TLDR is, unless our API routes itself are versioned there is no point of adding changelog just for documenting commits, if you want to document commits just put a description on the commit itself, and for large changes we should document them properly on the readme itself.
https://github.com/google-github-actions/release-please-action
@anuraghazra, thanks for your elaborate answer. I agree with you on most points.
As a changelog is nice to have but not a requirement, as can be seen from your response, I would not add it unless it is fully automated (i.e. elaborate https://github.com/google-github-actions/release-please-action) since manually maintaining changelogs gives us a new file that we have to maintain and can get outdated. Neverteless, these automated solutions need a clear versioning scheme 🤔. As you pointed out above and in an earlier discussion, such a versioning scheme would give no direct benefits to our API. Adding versioning would, therefore, just be a tool for the developers to generate a changelog and would have no direct effect on the user other than knowing what features were added without looking through the commits.