From 267da8a28a06af86f02b8125977efc6f15482f8e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Piotr=20P=C5=82aczek?= Date: Wed, 21 Aug 2024 18:16:57 +0100 Subject: [PATCH] blog: introducing api history (#627) * docs(blog): introducing api history * docs: flatten structure Reference: https://github.com/electron/website/pull/627#discussion_r1722097096 * docs: link to style guide * Update blog/introducing-api-history.md * Apply suggestions from code review Co-authored-by: Erick Zhao * Update blog/introducing-api-history.md Co-authored-by: Erick Zhao * Update blog/introducing-api-history.md Co-authored-by: Erick Zhao * Apply suggestions from code review Co-authored-by: Erick Zhao * Update blog/introducing-api-history.md * Update blog/introducing-api-history.md * docs: link to local styleguide Reference: https://github.com/electron/website/pull/627#discussion_r1722098978 * docs: absolute styleguide link * docs: piotrpdev author alphabetical Reference: https://github.com/electron/website/pull/627#discussion_r1724083337 * docs: link to api history post in 32 post --------- Co-authored-by: Erick Zhao --- blog/authors.yml | 5 + blog/electron-32-0.md | 2 +- blog/introducing-api-history.md | 270 ++++++++++++++++++++++++++++++++ 3 files changed, 276 insertions(+), 1 deletion(-) create mode 100644 blog/introducing-api-history.md diff --git a/blog/authors.yml b/blog/authors.yml index 80c4b727c..6791bccd4 100644 --- a/blog/authors.yml +++ b/blog/authors.yml @@ -58,6 +58,11 @@ nornagon: url: https://github.com/nornagon image_url: https://github.com/nornagon.png?size=96 +piotrpdev: + name: piotrpdev + url: https://github.com/piotrpdev + image_url: https://github.com/piotrpdev.png?size=96 + sofianguy: name: sofianguy url: https://github.com/sofianguy diff --git a/blog/electron-32-0.md b/blog/electron-32-0.md index cb8154a8f..44148c1e0 100644 --- a/blog/electron-32-0.md +++ b/blog/electron-32-0.md @@ -18,7 +18,7 @@ If you have any feedback, please share it with us on [Twitter](https://twitter.c ### Highlights -- Added new API version history in our documentation, a feature created by @piotrpdev as part of Google Summer of Code. [#42982](https://github.com/electron/electron/pull/42982) +- Added new API version history in our documentation, a feature created by @piotrpdev as part of Google Summer of Code. You can learn more about it in [this blog post](./introducing-api-history.md). [#42982](https://github.com/electron/electron/pull/42982) - Removed nonstandard File.path extension from the Web File API. [#42053](https://github.com/electron/electron/pull/42053) - Aligned failure pathway in Web [File System API](https://developer.mozilla.org/en-US/docs/Web/API/File_System_API) with upstream when attempting to open a file or directory in a blocked path. [#42993](https://github.com/electron/electron/pull/42993) - Added the following existing navigation-related APIs to `webcontents.navigationHistory`: `canGoBack`, `goBack`, `canGoForward`, `goForward`, `canGoToOffset`, `goToOffset`, `clear`. The previous navigation APIs are now deprecated. [#41752](https://github.com/electron/electron/pull/41752) diff --git a/blog/introducing-api-history.md b/blog/introducing-api-history.md new file mode 100644 index 000000000..80a4e0ae7 --- /dev/null +++ b/blog/introducing-api-history.md @@ -0,0 +1,270 @@ +--- +title: Introducing API History (GSoC 2024) +date: 2024-08-21T00:00:00.000Z +authors: piotrpdev +slug: introducing-api-history +tags: [community] +--- + +Historical changes to Electron APIs will now be detailed in the docs. + +--- + +Hi 👋, I'm Peter, the 2024 [Google Summer of Code (GSoC)](https://summerofcode.withgoogle.com/) +contributor to Electron. + +Over the course of the GSoC program, I implemented an API history feature for the +Electron documentation and its functions, classes, etc. in a similar fashion to the +[Node.js documentation](https://nodejs.org/en/docs): by allowing the +use of a simple but powerful YAML schema in the API documentation Markdown files +and displaying it nicely on the Electron documentation website. + + + +## Details + +### API history documentation system / YAML schema + +In the Markdown API documentation, the history for a function/class/etc. is now placed directly after the +header for that item in the form of a YAML code block encapsulated by +an HTML comment. + +````yaml +#### `win.setTrafficLightPosition(position)` _macOS_ + + + +* `position` [Point](structures/point.md) + +Set a custom position for the traffic light buttons. Can only be used with `titleBarStyle` set to `hidden`. +```` + +I believe using YAML like the Node.js docs do was the best approach because it +is easy to read. The API history isn't extremely complicated and should ideally +be as easy to write and read as possible. + +The final design shown above is actually significantly different to the one I proposed: + +````yaml + +```` + +One large change is the removal of version numbers: + +> "[...] There’s one somewhat significant change we’d like to call out about +> the proposal, which came up during discussion when we were reviewing proposals. +> [...] +> +> [we] decided that the approach with the [fewest] drawbacks would be to only +> use PR URLs (the root PRs to main) instead of hardcoded version strings as in +> the proposal. +> +> This can serve as a single source of truth which can then be used +> to derive exact version numbers, and no further documentation changes on main +> are necessary if the change is backported to other branches." +> +> — David Sanders [(@dsanders11)][dsanders11] via Slack + +We also didn't include removals in the API History, since when an API is removed +from Electron, it is also removed from the documentation. + +### JavaScript implementation + +I originally planned to create a new `@electron/docs-api-history-tools` +npm package that would contain scripts for extracting, validating/linting and converting +the API history in the documentation files. + +About a week before the coding period began, and after some discussion with my +mentors, I realized that was probably unnecessary: + +> "Hi everyone, I was thinking about the project after our huddle: Considering +> that extraction logic will have to be handled differently in `e/website` and +> `e/lint-roller` because of their dependencies, maybe there is no need for a +> separate package for API history stuff?" +> +> | Proposed | Revised | +> | :----------------------: | :--------------------: | +> | ![proposed][js-proposed] | ![revised][js-revised] | +> +> — Piotr Płaczek (me) via Slack + +We ultimately decided to not go ahead with my original idea: + +> "@Piotr Płaczek that seems fine to me! I think we can always refactor out to a +> separate module in a later iteration if we find that we need to share a lot of +> code between the two implementations anyways :slightly_smiling_face:" +> +> — Erick Zhao ([@erickzhao][erickzhao]) via Slack + +Instead, we divided those various tools across the Electron repos that were most +relevant to them: + +- `yaml-api-history-schema.json` + - -> `electron/electron` ([`api-history.schema.json`](https://github.com/electron/electron/blob/main/docs/api-history.schema.json)) +- `lint-yaml-api-history.ts` + - -> `electron/lint-roller` ([`lint-markdown-api-history.ts`](https://github.com/electron/lint-roller/blob/3d87b7ba8f99868a28648297f31a1587945045ab/bin/lint-markdown-api-history.ts#L4)) +- `extract-yaml-api-history.ts` + - -> `electron/website` ([`preprocess-api-history.ts`](https://github.com/electron/website/blob/f7e9446dd7d04b3369e9454f7c95f638fa061f1e/scripts/tasks/preprocess-api-history.ts#L4)) +- `yaml-api-history-to-markdown.ts` + - -> `electron/website` ([`transformers/api-history.ts`](https://github.com/electron/website/blob/f7e9446dd7d04b3369e9454f7c95f638fa061f1e/src/transformers/api-history.ts)) + - -> `electron/website` ([`ApiHistoryTable.tsx`](https://github.com/electron/website/blob/f7e9446dd7d04b3369e9454f7c95f638fa061f1e/src/components/ApiHistoryTable.tsx)) + +### UI and styling for Electron documentation website + +I originally proposed a simple table to display the API History data: + +| Design Prototype (Closed) | Design Prototype (Open) | +| :---------------------------------: | :-------------------------------: | +| ![demo1][prototype-closed-proposed] | ![demo2][prototype-open-proposed] | + +This is what the final implemented design looks like: + +![demo3][open-implemented] + +Pretty much the same as the prototype. The most significant addition is the use +of [SemVer](https://semver.org/) ranges, which were chosen to better communicate +which versions a feature is present in (thanks Samuel Attard +[(@MarshallOfSound)](https://github.com/MarshallOfSound) for the suggestion!). + +This is important because changes are frequently backported across supported +Electron release lines e.g. a fix may make it into Electron v32.0.0, v31.1.0 and v30.2.0. +This means it is not present in v31.0.0 which a user might mistakenly deduce based +on the fact it is present in a v30.x.x release. + +### Usage/style guide + +I added a usage/style guide dedicated to writing API history documentation for +new features. I described proper usages of the YAML schema in detail, provided +typical/useful examples, etc. You can find it +[here](https://github.com/electron/electron/blob/main/docs/styleguide.md#api-history). + +### Migration guide + +Since existing APIs have to be migrated to the new documentation system, I created +a migration guide. It features the typical steps of what a developer has +to do when migrating old APIs: looking through breaking changes, browsing through +the past releases, maybe looking through old commits, etc. +Then instructing the developer to follow the usage/style guide to add API history +documentation for each previously existing class/function/etc. + +Sadly, I couldn't think of a way to automate this effectively. This would probably +be a great task for an AI/ML engineer; however, I don't possess those skills and +was too afraid of accidentally introducing [hallucinations]() +into the API history. Even if automated, the information would still probably have +to be verified by a human in the end 😕. This task will probably have to be done +manually, on a file-by-file basis, +[just like it was done for the Node.js documentation](https://github.com/nodejs/node/issues/6578). + +## Deliverables + +- `api-history.schema.json` + + - A comprehensive YAML schema for documenting API history which includes support + for: + - [x] Additions + - [x] Deprecations + - [x] Changes + - [x] Links to relevant pull requests + - [x] Backports + - [x] Proposed in: [electron/rfc#6][rfc] + - [x] Implemented/Used in: [electron/electron#42982][electron] + - [x] Used in: [electron/website#594][website] + +- `lint-markdown-api-history.ts` + + - Script for linting YAML API history written according to a custom YAML + (technically JSON) schema. + - [x] Useful error messages + - [x] Comprehensive documentation / code comments + - [x] Extensive ~~Jest~~ Vitest tests + - [x] Good performance + - [x] Implemented in: [electron/lint-roller#73][lint-roller] + - [x] Used in: [electron/electron#42982][electron] + +- `preprocess-api-history.ts` + + - Performs simple validation just in case incorrect API History manages to make + it into the repo. Also strips the HTML comment tags that wrap API History blocks + since [Docusaurus](https://docusaurus.io/) cannot parse them. + - [x] Implemented/Used in: [electron/website#594][website] + +- `transformers/api-history.ts` + + - Script for converting YAML API history blocks in the Markdown documentation files + to ~~Markdown/HTML~~ [React](https://react.dev/) tables (`ApiHistoryTable.tsx`). + - [x] Implemented/Used in: [electron/website#594][website] + +- `ApiHistoryTable.tsx` + + - React table component used to display parsed API History data on the + documentation website. + - [x] Uses styling that follows the rest of the website's design. + - [x] Responsive, accessible, and generally well written HTML, CSS, and JS. + - [x] Implemented/Used in: [electron/website#594][website] + +- `styleguide.md` + + - Usage/style guide section for new API history documentation system. + - [x] Easy to understand + - [x] Well written + - [x] Includes examples + - [x] Implemented/Used in: [electron/electron#42982][electron] + +- `api-history-migration-guide.md` + - Migration guide for new API history documentation system. + - [x] Easy to understand + - [x] Well written + - [x] Includes examples + - [x] Implemented/Used in: [electron/electron#42982][electron] + +## Conclusion + +I had a lot of fun working on this feature and was able to earn valuable experience +from code reviews and discussing its various implementation details with the team. + +I believe the addition of API history to the documentation will make the lives of +developers using Electron a lot easier, especially ones attempting to migrate their +existing app from a several year old Electron version. + +I also want to sincerely thank my mentors: + +- David Sanders [(@dsanders11)][dsanders11] +- Keeley Hammond [(@VerteDinde)](https://github.com/VerteDinde) +- Erick Zhao [(@erickzhao)][erickzhao] + +...and the rest of the Electron team for answering my questions +and taking the time to give me feedback on my pull requests. +It is very much appreciated. + +[dsanders11]: https://github.com/dsanders11 +[erickzhao]: https://github.com/erickzhao +[js-proposed]: https://github.com/user-attachments/assets/3ec6c87b-1569-443b-8b63-eb20ee4fd96b +[js-revised]: https://github.com/user-attachments/assets/321745a4-ad09-4717-94cc-7b3e08a85d3c +[prototype-closed-proposed]: https://github.com/user-attachments/assets/a1c329d0-9f6b-4079-94d3-f9ff5b80c9ea +[prototype-open-proposed]: https://github.com/user-attachments/assets/f1556d89-8fc8-485f-995c-1edaf8ee1413 +[open-implemented]: https://github.com/user-attachments/assets/a8ceb931-ac10-46bc-b747-bf8fd97c839f +[electron]: https://github.com/electron/electron/pull/42982 +[website]: https://github.com/electron/website/pull/594 +[lint-roller]: https://github.com/electron/lint-roller/pull/73 +[rfc]: https://github.com/electron/rfcs/pull/6