godotengine / godot-interactive-changelog Goto Github PK

An interactive tool to view a changelog for each version of Godot Engine

Home Page: https://godotengine.github.io/godot-interactive-changelog/

License: MIT License

JavaScript 96.44% HTML 0.70% Python 2.08% CSS 0.79%

godot-interactive-changelog's Introduction

Godot Interactive Changelog

This project is provided for Godot Engine users and contributors to document in a complete and comprehensive manner changes that go into each release and developer preview of the engine. This project aims to largely remove the manual labor from creating and maintaining a project changelog, and provides tools to generate static information, such as CHANGELOG.md and release notes for the blog.

The benefit of this automated system is that it allows to track PRs as well as individual commits, preserving important context for the work that goes into each release. For example, it can also detect commits that were cherry-picked, and identify their original PRs.

Live website: https://godotengine.github.io/godot-interactive-changelog/

Contributing

This project is written in JavaScript and is built using Node.JS. HTML and CSS are used for the presentation. The end result of the build process is completely static and can be server from any web server, no Node.JS required.

Front-end is designed in a reactive manner using industry standard Web Components (powered by lit-element). This provides native browser support, and results in a small overhead from the build process.

To build the project locally you need to have Node.JS installed (12.x and newer should work just fine).

This project uses GitHub's GraphQL API. To fetch live data you need to generate a personal OAuth token. You can supply your token to the scripts using the GRAPHQL_TOKEN environment variable. Note, that if you don't have member access to the organization, you may not be able to access all the information used when generating the database.

Building the website

Clone or download the project.
From the project root run npm install or yarn to install dependencies.
Run npm run build or yarn run build to build the pages.
Run npm run publish-db or yarn run publish-db to prepare and copy configs and data.
Serve the out/ folder with your method of choice (e.g. using Python 3: python -m http.server 8080 -d ./out).

rollup is used for browser packing of scripts and copying of static assets. The data fetching script is plain JavaScript with node-fetch used to polyfill fetch()-like API.

Adding a new version

Add a config file under the ./configs folder.

It must follow this format: <REPO_OWNER>.<REPO_NAME>.<VERSION>.json, e.g. godotengine.godot.1.2.3.json.

Run npm run compose-db version:<VERSION> or yarn run compose-db version:<VERSION> to fetch the data from GitHub.

This project defaults to godotengine/godot, but you can also customize it with owner:<REPO_OWNER> and repo:<REPO_NAME>.
By default the repo is checked out to the ./temp folder, you can skip this step with skip-checkout.
GitHub API is very flaky and requests can fail from time to time due to the server-side issues; the compose script has a few tricks to mitigate that, but ultimately it can still randomly fail on bigger changelogs. Just run it again.

Run npm run publish-db or yarn run publish-db to prepare and copy configs and data.

License

This project is provided under the MIT License.

godot-interactive-changelog's People

Contributors

Stargazers

Watchers

Forkers

boyquotes kure-developers loweredgames akien-mga clayjohn yurisizov

godot-interactive-changelog's Issues

Render inline code markup with code formatting

GitHub now supports inline code markup (using single backquotes) in PR titles, and I try to make use of it consistently for references to API properties or methods (but not for classes themselves, don't ask me why :P).

Would be nice if the interactive changelog supported this too.

Porting category: Add OS name as subcategory where it can be inferred

For issues with topic:porting label, we currently add the "Porting:" prefix, which is good.

I'm used to also specifying the platform if it's platform-specific (i.e. only one platform: label), e.g. "Porting: Linux: Blabla PR title" if the labels are topic:porting platform:linuxbsd). We should remember to also handle stripping already existing platform prefixes when they exist (e.g. a PR named "Android: Blabla").

If there are more than one platform: labels, then we should fall back to just "Porting:" as it's a cross-platform change.

For topic:linuxbsd, I would suggest using "Linux:" as prefix. It's worth noting that we have PRs using "X11:" or "[X11]" as prefix in their PR title, and sometimes it's indeed for X11 specific stuff, and sometimes just a shorthand for the Linux/X11 platform name. I think it's fine if those end up as "Porting: Linux: X11:" even if the change isn't specific to X11 code, it's not a big deal (and we can fix those by renaming the PRs when we spot them). Likely we should match existing prefixes like "LinuxBSD:" etc. and harmonize it to just "Linux:".

#8 may be a prerequisite to properly handle cases such as this one:

Porting: [iOS] Fix orientation change in runtime. ([GH-78132](https://github.com/godotengine/godot/pull/78132)).

Remove dot at the end of a PR title before adding the "(GH-#)." suffix

Some contributors write their PR titles with a dot at the end. It's fine, but since it's not done consistently, and it would be a bit overkill for us to edit all PR titles to remove trailing dots, I would suggest doing it as a post-processing step.

We can just remove the dot at the end before appending the "(GH-#)." suffix, unless it's "..." which we should likely keep as is.

Not sure about ".." which is something folks like reduz tend to use, we can assume this won't really happen and would be fixed by editing the PR itself.

Remove `[3.x]` / `(3.x)` prefixes and suffixes on 3.x changelogs

https://godotengine.github.io/godot-interactive-changelog/#3.6-beta2

We should strip those [3.x] or (3.x) prefixes or suffixes (most PRs use [3.x] as a prefix but @Calinou tends to use (3.x) as a suffix - a habit that might be worth changing for consistency, but we could still handle it here).

There can also be other variations like [3.5] or (3.5), and it's also relevant for PRs to stable 4.x branches as we've had a few already with [4.0] prefix. So we should probably match with a regex.

Extend to be usable for general repos

Hey, I came across this tool and I think it's a really great tool. I was wondering if it could be extended to be easily used for other repos? I can see this being useful for many other projects.

Strip "[MP]" prefix for `topic:multiplayer` PRs

Possibly depends on doing #8 first, and then treating MP as a known prefix for topic:multiplayer.

Strip "doc:" prefix for documentation PRs

I tend to use "doc:" as prefix for documentation PRs, it doesn't match the documentation label so doesn't get stripped, but I assume we have some logic that can be amended for this case.

Sort PRs with a single `platform:` label under "Porting:", even if not using `topic:porting` label

This is up for discussion, but when I was doing the changelogs manually, I would sort any platform-specific PR under Platforms/Porting, even if it doesn't explicitly have the topic:porting label.

Here's an example from 4.1-beta3 of a topic:rendering PR godotengine/godot#78235 which is Windows specific, and would IMO best be listed as "Porting: Windows: Fix for Win+M crashing the editor"

I don't know yet if it would always be the right decision though. For example it's up for debate when a PR like godotengine/godot#78120 should go under "Porting: Windows:" or "Buildsystem:". Intuitively I would say "Buildsystem:" is better, but maybe that's the only exception to the above rule?

Add button to copy markdown changelog

In the markdown view:

When using this as a base for a blog post, I usually copy the contents to a local file to edit. It would be nice to have a button to copy the whole text area, or support Ctrl+A when it has focus.

Capitalize first letter of PR title for the changelog

Some users write their PR titles without starting with a capital letter. We've recently started editing them to fix the formatting, so we could consider this solved as much as we want it to be.

But opening this issue anyway to discuss whether we'd want to do some auto-capitalization for the changelog.

Examples that would benefit from it:

Worth noting for those, they had a "GDScript: " prefix that was removed, so this would need to be taken into account in the capitalization logic.

But other cases wouldn't:

(This last one arguably warrants removing the doc: prefix, I'll open another issue #6.)

Reformat existing "[Context]" prefixes in PR titles to "Context:"

Some contributors add a contextualizing prefix to their PRs of the form [Context], e.g.:

[TextEdit] Expose all auto-wrap modes.

[RTL] Fix multithreaded resizing.

To ensure consistency, I'm used to change those to "TextEdit:" or "RTL:", so once formatted with the "GUI:" prefix inferred from their label (and removing the dot from #4), they would be:

GUI: TextEdit: Expose all auto-wrap modes (GH-74813).

GUI: RTL: Fix multithreaded resizing (GH-78241).