I want to thank David Sanders (@dsanders11) and the rest of the Electron team for answering my questions and taking the time to give me feedback on my draft proposals. It is very much appreciated.

You can click here to view this proposal as a nicely formatted GitHub Gist.

• Name: Piotr Płaczek (you can call me Peter)
• Email: [email protected]
• Website: piotrp.dev
• Resume: cv.piotrp.dev
• Location: Waterford, Ireland

• GitHub: piotrpdev
• Twitter: @piotrpdev
• LinkedIn: piotrpdev

• Time Zone: UTC+1 (Ireland)
• Working Hours: 9:00 - 18:00 (flexible, just want to avoid burnout)

The Electron documentation currently doesn't feature API history for its functions, classes, etc. This proposal aims to implement the missing API history 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.

The API history for a function/class/etc. will be placed directly after the Markdown header for that item in the form of a YAML code block encapsulated by a HTML comment.

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

I believe using YAML like the Node.js docs do is 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. At first thought Markdown might seem like a plausible alternative, however I don't think it provides the information efficiency needed for the task. API history can be efficiently and clearly conveyed through key value pairs, a table, etc. while I believe Markdown is more suited for writing paragraphs and such.

"Why not just place the YAML directly in the code block?" - I believe my approach provides the best readability and ease of use. A developer can create a fenced code block with YAML history specified to get syntax highlighting (putting history after YAML doesn't mess up highlighting) and just comment it out with a shortcut once they're done. This also reduces the possibility of a formatting error messing something up (since indentation is so important in YAML).

I believe this is the best approach since it indicates the API history is metadata rather than a prop of the item or something similar. I think this also makes the documentation easier to read when rendered on GitHub (since comments are hidden) although the user can still switch to the code view and see the API history if they desire.

I plan to create a new @electron/docs-api-history-tools NPM package that will contain scripts for extracting, validating/linting and converting the API history in the documentation files.

I then plan to introduce a lint:docs-history script into the electron/electron package.json file and add it to the end of the lint:docs script. This will run a linting script provided by my package (probably re-exported by @electron/lint-roller) and validate the YAML API history in the Markdown docs against a custom schema using the ajv package. This schema will support additions, depreciations etc. and will help ensure consistency for API history across the docs.

If validating the entire docs at once is too slow, I will look at other approaches e.g. creating a GitHub Action that only validates the API history schema in pull requests.

Furthermore, I will modify the scripts/pre-build.ts script in electron/website to use my package in order to convert the YAML API history into a Markdown table (or maybe a HTML table if the design calls for it) for the website. I will also modify the website CSS files to style this API history table nicely (see UI section below for details).

The YAML API history blocks will be extracted and transformed using the parsed Markdown AST (probably generated from mdast-util-from-markdown like in electron/lint-roller).

Instead of the library that the Node.js doctool uses for parsing YAML (js-yaml), I plan to use the yaml package since it is regularly maintained and has no dependencies. David Sanders (@dsanders11) suggested this and also mentioned that the Electron team is moving new code to this package.

Of course, this package will have extensive tests written for it (probably using Jest).

I am planning on creating a simple GitHub Action/Bot that replaces placeholder version values. This is needed so a developer can add API history documentation along with their new feature, have it merged into a beta release, and when the official release comes out the API documentation for the feature lists that official version as the version the feature was added in.

Usage of my package for this will likely not be necessary; running a simple file text find and replace will likely be sufficient (that is what Node.js does).

I will display the parsed API history data in a nice-looking format on the documentation website. I plan on keeping it simple and readable like the Node.js documentation does, but maybe make it look a bit nicer / more modern since Node.js's one looks very basic. A responsive table will probably work best for most scenarios.

Design Prototype (Closed)	Design Prototype (Open)

I will add a section to the electron/docs/styleguide.md usage/style guide dedicated to writing API history documentation for new features. I will describe proper usages of the YAML schema in detail, provide typical/useful examples, etc. I'm aiming for it to make the process of documenting API history as easy as possible, especially considering that a lot of existing APIs will have to be migrated to the new system.

Since existing API's have to be migrated to the new documentation system, I will create a migration guide (probably in electron/docs/api-history-guide.md). It will likely feature the typical steps of what a developer currently has to do when migrating an old Electron app to a new release: Read through the Electron breaking-changes.md file, browse the through the past releases, maybe look through old commits, etc. They will then be instructed to follow the usage/style guide to add API history documentation for each previously existing class/function/etc.

The (archived) electron-api-historian project should be able to speed up the process of finding when APIs were first added (thanks David Sanders (@dsanders11) for the idea). However, finding when individual functions, parameters, etc. were changed is a lot more complicated.

Sadly, I can'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 would be 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.

I will however try using git log -L :<funcname>:<file> along with some other Git tricks and see it if is useful.

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 think this feature would also increase the credibility of Electron and entice more people to use it.

• @electron/docs-api-history-tools NPM package with:

  • Scripts for parsing and linting/validating YAML API history written according to a custom YAML (technically JSON) schema.
  • Script for converting YAML API history blocks in the Markdown documentation files to Markdown/HTML tables.
  • Useful error messages
  • Comprehensive documentation / code comments
  • Extensive Jest tests
  • Good performance
  • Code following best coding practices, Electron linting/style guide, etc.

• A comprehensive YAML schema for documenting API history which includes support for:

  • Additions
  • Depreciations
  • Removals
  • Changes
  • Links to relevant pull requests
  • Backports
  • etc.

• A GitHub Action/Bot that will replace placeholder version values in the API history documentation.

  • This is needed so a developer can add API history documentation along with their new feature, have it merged into a beta release, and when the official release comes out the API documentation for the feature lists that official version as the version the feature was added in.

• Nice UI and styling for API history on the Electron documentation website.

  • Styling that follows the rest of the website's design.
  • Responsive, accessible, and generally well written HTML, CSS, and JS.
  • etc.

• Usage/style guide section for new API history documentation system that is:

  • Easy to understand.
  • Well written.
  • Includes examples.
  • etc.

• Migration guide for new API history documentation system that is:

  • Easy to understand.
  • Well written.
  • Includes examples.
  • etc.

As suggested in the original idea, I plan to implement an API history documentation system similar to the one used in the Node.js documentation (Node.js doctool, example). After researching it and looking at how it works, I really like it and think it would be a good fit for the Electron documentation.

I like the way Flask displays API changes in their API documentation as well, however they use reStructuredText and include all of the historical API changes for a function in the source code itself, which I don't really like.

I plan to take inspiration from various API history examples out there.

• I am 20 years old
• I was born in Poland
• I am currently living in Waterford, Ireland
• I started programming back in 2018 with C++
• My first real project was a Python web scraper I made in 2020

• I did a 7 month work placement at Red Hat in 2023 as part of my university course. I mainly worked on an AI/ML model delivery pipeline running on Red Hat OpenShift using Tekton. I also wrote a Medium article detailing my work, here is a link.

• University: South East Technological University
• Degree: BSc (Hons.) in Software Systems Development
• Expected Graduation: May, 2025

Some of my open-source work that showcases I have the prior experience necessary to implement the proposal:

• electron/electron (#41642): A simple bugfix PR I made.

  • Set-up electron/build-tools on a Hetzner VPS.
  • Ran the build, linting, and test scripts.
  • Created a PR, implemented suggested changes and rebased before merge.

• piotrpdev/cao-calculator: Android app for calculating university entrance points, built with React Native and TypeScript.

• piotrpdev/WIT-Timetable-Generator: Web scraper for my university's timetable page, built with JavaScript.

• piotrpdev/resume: My resume, built with React and JavaScript.

• Music (performance, composition, listening, etc.)
• Electronics (Arduino, Raspberry Pi, ESP32, etc.)
• Gaming (Arma 3, Dark Souls, Pokémon, etc.)