Aller au contenu principal

Introduction à l'historique de l'API (GSoC 2024)

· 7 mins de lecture
piotrpdev
piotrpdev

L'historique des changements des différentes API Electron sera maintenant détaillé dans la documentation.

Bonjour 👋, je suis Peter, le contributeur Electron pour le Google Summer of Code (GSoC).

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: 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.

Détails​

Système de documentation de l’API / schéma YAML​

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.

#### `win.setTrafficLightPosition(position)` _macOS_

<!--
```YAML history
added:
  - pr-url: https://github.com/electron/electron/pull/22533
changes:
  - pr-url: https://github.com/electron/electron/pull/26789
    description: "Made `trafficLightPosition` option work for `customButtonOnHover` window."
deprecated:
  - pr-url: https://github.com/electron/electron/pull/37094
    breaking-changes-header: deprecated-browserwindowsettrafficlightpositionposition
```
-->

* `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 history
added: v10.0.0
deprecated: v25.0.0
removed: v28.0.0
changes:
  - version: v13.0.0
    pr-url: https://github.com/electron/electron/pull/26789
    description: Made `trafficLightPosition` option work for `customButtonOnHover` window.
```
-->

Un changement important est la suppression des numéros de version:

"[...] 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) via Slack

Nous n’avons pas non plus inclus les suppressions dans l’historique des APIs, car lorsqu’une API est supprimée d'Electron, elle est également supprimée de la documentation.

Implémentation JavaScript​

J'avais initialement prévu de créer un nouveau package npm @electron/docs-api-history-tools contenant des scripts pour extraire, valider/lint et faire la conversion de l'historique de l'API dans les fichiers de documentation.

Mais environ une semaine avant le début de la période de codage, et après une discussion avec mes mentors , j'ai réalisé que c'était probablement inutile:

"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?"

ProposedRevised
proposedrevised

— Piotr Płaczek (me) via Slack

Nous avons finalement décidé de ne pas suivre mon idée initiale:

"@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 🙂"

— Erick Zhao (@erickzhao) via Slack

Instead, we divided those various tools across the Electron repos that were most relevant to them:

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)
demo1demo2

Et voici à quoi ressemble la conception finale:

demo3

Pretty much the same as the prototype. The most significant addition is the use of SemVer ranges, which were chosen to better communicate which versions a feature is present in (thanks Samuel Attard (@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.

Guide d'utilisation et de style​

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.

Guide de migration​

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.

Livrables​

  • api-history.schema.json

  • lint-markdown-api-history.ts

    • Script for linting YAML API history written according to a custom YAML (technically JSON) schema.
      • Useful error messages
      • Comprehensive documentation / code comments
      • Extensive Jest Vitest tests
      • Good performance
    • Implemented in: electron/lint-roller#73
    • Used in: electron/electron#42982

  • 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 cannot parse them.
    • Implemented/Used in: electron/website#594

  • transformers/api-history.ts

    • Script for converting YAML API history blocks in the Markdown documentation files to Markdown/HTML React tables (ApiHistoryTable.tsx).
    • Implemented/Used in: electron/website#594

  • ApiHistoryTable.tsx

    • React table component used to display parsed API History data on the documentation website.
      • Uses styling that follows the rest of the website's design.
      • Responsive, accessible, and generally well written HTML, CSS, and JS.
    • Implemented/Used in: electron/website#594

  • styleguide.md

    • Usage/style guide section for new API history documentation system.
      • Easy to understand
      • Well written
      • Includes examples
    • Implemented/Used in: electron/electron#42982

  • api-history-migration-guide.md

    • Migration guide for new API history documentation system.
      • Easy to understand
      • Well written
      • Includes examples
    • Implemented/Used in: electron/electron#42982

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:

...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.