electron / clerk

Verify PRs have release notes

📝 Available Translations: 🇨🇳 🇧🇷 🇪🇸 🇯🇵 🇷🇺 🇫🇷 🇺🇸 🇩🇪. View these docs in other languages on our Crowdin project.

The Electron framework lets you write cross-platform desktop applications using JavaScript, HTML and CSS. It is based on Node.js and Chromium and is used by the Visual Studio Code and many other apps.

Follow @electronjs on Twitter for important announcements.

This project adheres to the Contributor Covenant code of conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to [email protected].

Installation

To install prebuilt Electron binaries, use npm. The preferred method is to install Electron as a development dependency in your app:

npm install electron --save-dev

For more installation options and troubleshooting tips, see installation. For info on how to manage Electron versions in your apps, see Electron versioning.

Platform support

Each Electron release provides binaries for macOS, Windows, and Linux.

• macOS (Catalina and up): Electron provides 64-bit Intel and ARM binaries for macOS. Apple Silicon support was added in Electron 11.
• Windows (Windows 10 and up): Electron provides ia32 (x86), x64 (amd64), and arm64 binaries for Windows. Windows on ARM support was added in Electron 5.0.8. Support for Windows 7, 8 and 8.1 was removed in Electron 23, in line with Chromium's Windows deprecation policy.
• Linux: The prebuilt binaries of Electron are built on Ubuntu 20.04. They have also been verified to work on:
  • Ubuntu 18.04 and newer
  • Fedora 32 and newer
  • Debian 10 and newer

Quick start & Electron Fiddle

Use Electron Fiddle to build, run, and package small Electron experiments, to see code examples for all of Electron's APIs, and to try out different versions of Electron. It's designed to make the start of your journey with Electron easier.

Alternatively, clone and run the electron/electron-quick-start repository to see a minimal Electron app in action:

git clone https://github.com/electron/electron-quick-start
cd electron-quick-start
npm install
npm start

Resources for learning Electron

• electronjs.org/docs - All of Electron's documentation
• electron/fiddle - A tool to build, run, and package small Electron experiments
• electron/electron-quick-start - A very basic starter Electron app
• electronjs.org/community#boilerplates - Sample starter apps created by the community

Programmatic usage

Most people use Electron from the command line, but if you require electron inside your Node app (not your Electron app) it will return the file path to the binary. Use this to spawn Electron from Node scripts:

const electron = require('electron')
const proc = require('node:child_process')

// will print something similar to /Users/maf/.../Electron
console.log(electron)

// spawn Electron
const child = proc.spawn(electron)

Mirrors

• China

See the Advanced Installation Instructions to learn how to use a custom mirror.

Documentation translations

We crowdsource translations for our documentation via Crowdin. We currently accept translations for Chinese (Simplified), French, German, Japanese, Portuguese, Russian, and Spanish.

Contributing

If you are interested in reporting/fixing issues and contributing directly to the code base, please see CONTRIBUTING.md for more information on what we're looking for and how to get started.

Community

Info on reporting bugs, getting help, finding third-party tools and sample apps, and more can be found on the Community page.

License

MIT

When using Electron logos, make sure to follow OpenJS Foundation Trademark Policy.

clerk's Issues

Release notes status is sometimes not reported

In some multi-line release notes, the release notes status is sometimes not reported.

electron/electron#25219.

This appears to happen when there is a newline between Notes: and the bullet list. The check resolves when the newline is removed.

Improper parsing of certain symbols

electron/electron#36934 (comment) - <datalist> was parsed as <datalist>

Readme

Project: Release Notes Service

Clerk currently serves a single purpose, validating that every PR has a valid Notes: .* block in the PR body and then storing those notes on merge to ensure they are frozen.

As part of electron/electron#30516 we need to extend Clerk to be the primary source of complete release notes generation. Implementation aside Clerk should implement a single API endpoint

POST /notes

Request Body

{
  "startVersion": "9.1.2",
  "endVersion": "10.0.1",
}

Response Body

Request Started: 201 Created

If the cache does not have notes between the given versions, we should queue notes generation and return a 201 Created status code immediately with an empty body.

Request In Progress: 202 Accepted

If the cache does not have notes between the given versions and a notes generation for the given range is already queued or in progress we should return a 202 Accepted status code with an empty response body.

Notes Complete: 200 OK

type Change = {
  type: "fix" | "feature" | "breaking_change" | "docs";
  // Some notes are multi-line, this should be an array of each line
  description: string[];
  // PR that caused this change
  prNumber: number;
  // If the PR that caused this change was a backport, this field should be populated
  // as the number of the original PR that landed to "main"
  originalPrNumber: number;
  // The version this change was first released in, in the context of this release notes request
  // just because this change may have been released in other versions it doesn't matter
  landedInVersion: string;
};

type Response = {
  // Changes that landed between startVersion and endVersion
  additions: Change[];
  // Changes that were available in startVersion but were backported
  // to a version in the endVersion major line AFTER the endVersion
  // i.e. in order to retain the change you have to update to a newer
  // patch version of endVersion
  removals: Change[];
}

Algorithm for determining changes

Given a startVersion and endVersion each with known properties major, minor, patch, preReleaseTag and preReleaseNumber.

Version	Major	Minor	Patch	Pre Release Tag	Pre Release Number
12.0.0-alpha.1	12	0	0	alpha	1
13.1.2	13	1	2

Very pseudo code 😄

changes = []
removals = []

# returns the last commit hash that the branch for the given major release
# shares with the "main" branch.
# This can be simplified as the "newest common ancestor between main and majorRelease"
def branchPoint(majorRelease);

# returns a "Change" object for the given commit or null if no change could be
# identified.
# This should follow normal logic of:
# --> Find PR that landed commit
# --> Pull notes from PR
# --> Check if PR was backport, if so find original PR
def buildChange(commit);

# returns True if no change in the given list matches / is identical to the provided
# change.  This is determined via either the PR numbers matching (backport of th
# same PR) or the description strings being idential.
def noChangeMatches(changeList, change);

already_present_changes = []
duplicated_changes = []

for commit in range(branchPoint(startVersion.major), startVersion):
  change = buildChange(commit)
  if change is not None:
    already_present_changes.append(change)

for commit in range(branchPoint(startVersion.major), endVersion):
  change = buildChange(commit)
  if change is not None:
    # Only include the change if it wasn't already in the startVersion
    if noChangeMatches(already_present_changes, change):
      changes.append(change)
    else:
      duplicated_changes.append(change)

# Any change that was already present after the branch point but we did not find a duplicate of
# in the target version should be considered "removed"
removals = inverse_intersect(already_present_changes, duplicated_changes)

Every single part of this logic needs to be heavily cached in PSQL / Redis. We should only calculate the release notes between two versions once regardless of how many people request it.

All GitHub API requests should be heavily cached internally as well, requests for commit information can be cached indefinitely. PR information should not be cached. Notes should be cached indefinitely, if we need to cache bust we should be able to do so by re-deploying Clerk with an incremented cache key.

Support multiple lines of release notes

This will have to be supported in trop as well

https://github.com/electron/clerk/pull/47#issue-485105705https://tse1.mm.bing.net/th?id=OGC.1535c34168181b328c55a02040d0f2d9&pid=Api&rurl=https%3a%2f%2fmedia.giphy.com%2fmedia%2fd3FycW8RlZ88LwIg%2fgiphy.gif&ehk=dTVmjO9sq%2fwA%2bzz1o05WvjKZpKHlBp1eJtV4ujcTN1k%3d

https://tse1.mm.bing.net/th?id=OGC.1535c34168181b328c55a02040d0f2d9&pid=Api&rurl=https%3a%2f%2fmedia.giphy.com%2fmedia%2fd3FycW8RlZ88LwIg%2fgiphy.gif&ehk=dTVmjO9sq%2fwA%2bzz1o05WvjKZpKHlBp1eJtV4ujcTN1k%3d

Originally posted by @Amirnateghi1 in #47 (comment)

add Codeowners

This protection is needed given automatic heroku deployment.

/cc @MarshallOfSound

`no-notes` is not always detected as not-a-note?

electron/electron#17947 (comment) reads

Release Notes Persisted

no-notes

But should have been:

No Release Notes

Shouldn't require a note unless the PR is an `add:` or `fix:`

Most PRs with other semantic commits are procedural items that don't matter.

It will be tedious to add a notes: no-notes for every chore:, style:, refactor:, test: etc..

if the check doesn't pass, add a comment explaining to the PR submitter why it failed

Seen in #hack-week-2018-08 by @zcbenz:

it would be great if the bots can give the reason why the check does not pass, I had to look into the bot's source code to know I have to add note: in PR body, and prefixes like vendor and spec are not valid semantic prefixes.

Clerk includes comments in the release note body

Example:

{
  "body": "**Release Notes Persisted**\n\n> <!-- One-line Change Summary Here--> improved tray icon context menu and menu bar accessibility"
}

Our release notes script could sniff for these comments and remove them, but it might be better to handle it in Clerk.

Thoughts?

new icon

Hey I started working on a new icon. What do you think?

clerk repo should be public

When sharing #2 into #hack-week-2018-08:

Do you want to show a rich preview for #2?
The link you shared is from a private repository. Not everyone in this workspace may have access to the associated GitHub content.