Page MenuHomePhabricator

Move Gerrit Javascript plugins from gerrit-theme.js to standalone files in the deploy repository
Closed, ResolvedPublic

Description

Gerrit offers a system to customize the web theme. When static/gerrit-theme.js exists, it is loaded as a plugin and we have been using it to load a few customization. The file is hosted in Puppet at modules/gerrit/files/homedir/review_site/static/gerrit-theme.js and contains several different features all mixed up in a single plugin registration.

That causes several issues:

  • when upgrading Gerrit to a new minor version we might have to do adjust the embedded plugin. Release-Engineering-Team can do the upgrade via scap but changes to gerrit-theme.js requires a Puppet change and thus synchronization with SRE.

I have found out Gerrit supports loading plugins from a single Javascript file in the plugins directory instead of having to create a JAR plugin. The name of the javascript file is used as a plugin name (MyCustomLink.js would be named MyCustomLink). It is hinted at: https://gerrit.wikimedia.org/r/Documentation/dev-plugins.html#deployment

Thus we can split gerrit-theme.js in multiple files that would be stored in operations/software/gerrit deployment branch under the plugins directory. The new .js files would sit along the existing .jar files.

When deploying a JavaScript plugin, we can rely on plugins.checkFrequency to have Gerrit reload it entirely every minute.

Event Timeline

The Gerrit.install() interface is:

polygerrit-ui/app/api/gerrit.ts
export declare interface Gerrit {
  install(
    callback: (plugin: PluginApi) => void,
    opt_version?: string,
    src?: string
  ): void;
  styles: Styles;
}

The optionals opt_version and src parameters are handled by the plugin loader. The opt_version is compared against the hardcoded constant API_VERSION=0.1 which never got changed in Gerrit. It is intended as a kill switch if one day PolyGerrit is changed in an incompatible way.

polygerrit-ui/app/elements/shared/gr-js-api-interface/gr-plugin-loader.ts
install(
  callback: (plugin: PluginApi) => void,
  version?: string,
  src?: string
) {
  // HTML import polyfill adds __importElement pointing to the import tag.
  const gerritScript = document.currentScript as GerritScriptElement | null;
  const script = gerritScript?.__importElement ?? gerritScript;
  if (!src && script && script.src) {
    src = script.src;
  }
  if ((!src || src.startsWith('data:')) && script && script.baseURI) {
    src = script && script.baseURI;
  }
  if (!src) {
    this._failToLoad('Failed to determine src.');
    return;
  }
  if (version && version !== API_VERSION) {
    this._failToLoad(
      `Plugin ${src} install error: only version ${API_VERSION} is supported in PolyGerrit. ${version} was given.`,
      src
    );
    return;
  }

  const url = this._urlFor(src);
  const pluginObject = this.getPlugin(url);
  let plugin = pluginObject && pluginObject.plugin;
  if (!plugin) {
    plugin = new Plugin(url);
  }
  try {
    callback(plugin);
    this._pluginInstalled(url, plugin);
  } catch (e) {
    this._failToLoad(`${e.name}: ${e.message}`, src);
  }
}

Change 853025 had a related patch set uploaded (by Hashar; author: Hashar):

[operations/software/gerrit@wmf/stable-3.4] Import gerrit-theme.js history from Puppet

https://gerrit.wikimedia.org/r/853025

Change 853052 had a related patch set uploaded (by Hashar; author: Hashar):

[operations/software/gerrit@deploy/wmf/stable-3.4] Import gerrit-theme.js history from Puppet

https://gerrit.wikimedia.org/r/853052

Change 853056 had a related patch set uploaded (by Hashar; author: Hashar):

[operations/software/gerrit@deploy/wmf/stable-3.4] Move test result table to a standalone plugin

https://gerrit.wikimedia.org/r/853056

Change 853057 had a related patch set uploaded (by Hashar; author: Hashar):

[operations/software/gerrit@deploy/wmf/stable-3.4] Move custom CSS style to a standalone plugin

https://gerrit.wikimedia.org/r/853057

Change 853058 had a related patch set uploaded (by Hashar; author: Hashar):

[operations/software/gerrit@deploy/wmf/stable-3.4] Move custom links to a standalone plugin

https://gerrit.wikimedia.org/r/853058

Change 853061 had a related patch set uploaded (by Hashar; author: Hashar):

[operations/puppet@production] gerrit: remove gerrit-theme.js

https://gerrit.wikimedia.org/r/853061

Change 853305 had a related patch set uploaded (by Hashar; author: Hashar):

[integration/config@master] Add npm test to Gerrit deployment branch

https://gerrit.wikimedia.org/r/853305

Change 853306 had a related patch set uploaded (by Hashar; author: Hashar):

[operations/software/gerrit@deploy/wmf/stable-3.4] build: add eslint for JavaScript plugins

https://gerrit.wikimedia.org/r/853306

Change 853061 merged by Filippo Giunchedi:

[operations/puppet@production] gerrit: remove gerrit-theme.js

https://gerrit.wikimedia.org/r/853061

On gerrit1001 and gerrit2002:

Info: Applying configuration version '(0ff3c7b7bc) Filippo Giunchedi - gerrit: remove gerrit-theme.js'
Notice: Applied catalog in 31.94 seconds

$ ls -la /var/lib/gerrit2/review_site/static/gerrit-theme.js
-rwxr-xr-x 1 gerrit2 gerrit2 8977 Aug 19 18:17 /var/lib/gerrit2/review_site/static/gerrit-theme.js
Info: Applying configuration version '(0ff3c7b7bc) Filippo Giunchedi - gerrit: remove gerrit-theme.js'
Notice: Applied catalog in 26.51 seconds

$ ls -la /var/lib/gerrit2/review_site/static/gerrit-theme.js
-rwxr-xr-x 1 gerrit2 gerrit2 8977 Aug 19 18:15 /var/lib/gerrit2/review_site/static/gerrit-theme.js

Change 853052 merged by jenkins-bot:

[operations/software/gerrit@deploy/wmf/stable-3.4] Import gerrit-theme.js history from Puppet

https://gerrit.wikimedia.org/r/853052

Change 853056 merged by jenkins-bot:

[operations/software/gerrit@deploy/wmf/stable-3.4] Move test result table to a standalone plugin

https://gerrit.wikimedia.org/r/853056

Change 853057 merged by jenkins-bot:

[operations/software/gerrit@deploy/wmf/stable-3.4] Move custom CSS style to a standalone plugin

https://gerrit.wikimedia.org/r/853057

Change 853058 merged by jenkins-bot:

[operations/software/gerrit@deploy/wmf/stable-3.4] Move custom links to a standalone plugin

https://gerrit.wikimedia.org/r/853058

Change 853305 merged by jenkins-bot:

[integration/config@master] Add npm test to Gerrit deployment branch

https://gerrit.wikimedia.org/r/853305

Mentioned in SAL (#wikimedia-operations) [2022-11-09T12:16:35Z] <hashar@deploy1002> Started deploy [gerrit/gerrit@b83625a]: gerrit2002: Gerrit JavaScript plugins as standalone files # T319378

Mentioned in SAL (#wikimedia-operations) [2022-11-09T12:16:45Z] <hashar@deploy1002> Finished deploy [gerrit/gerrit@b83625a]: gerrit2002: Gerrit JavaScript plugins as standalone files # T319378 (duration: 00m 10s)

I have published them to gerrit2002 (the replica). Gerrit automatically reloaded plugins, from error log:

[2022-11-09T12:17:00.676Z] [PluginScanner] INFO  com.google.gerrit.server.plugins.PluginLoader : Loaded plugin wm-app-theme, version app-theme
[2022-11-09T12:17:00.677Z] [PluginScanner] INFO  com.google.gerrit.server.plugins.PluginLoader : Loaded plugin wm-custom-links, version custom-links
[2022-11-09T12:17:00.677Z] [PluginScanner] INFO  com.google.gerrit.server.plugins.PluginLoader : Loaded plugin wm-test-result-table, version test-result-table

And I had to reinstall the builtin plugins with:

sudo -u gerrit2 java -jar /var/lib/gerrit2/review_site/bin/gerrit.war init --batch --install-all-plugins

It fails updating the Lucene index but otherwise regenerate the plugins.

Diff before/after of ssh -p 29418 gerrit-replica.wikimedia.org gerrit plugin ls:

@@ -19,4 +19,7 @@
 reviewnotes                    v3.4.6     3.4.6            ENABLED  reviewnotes.jar
 singleusergroup                v3.4.6     3.4.6            ENABLED  singleusergroup.jar
 webhooks                       v3.4.6     3.4.6            ENABLED  webhooks.jar
+wm-app-theme                   app-theme                   ENABLED  wm-app-theme.js
+wm-custom-links                custom-links                  ENABLED  wm-custom-links.js
+wm-test-result-table           test-result-table                  ENABLED  wm-test-result-table.js
 zuul                           16a217c    3.4.5            ENABLED  zuul.jar

And finally removed the obsolete gerrit-theme.js:

sudo rm /var/lib/gerrit2/review_site/static/gerrit-theme.js

Mentioned in SAL (#wikimedia-operations) [2022-11-09T12:25:52Z] <hashar@deploy1002> Started deploy [gerrit/gerrit@b83625a]: gerrit1001: Gerrit JavaScript plugins as standalone files # T319378

Mentioned in SAL (#wikimedia-operations) [2022-11-09T12:26:02Z] <hashar@deploy1002> Finished deploy [gerrit/gerrit@b83625a]: gerrit1001: Gerrit JavaScript plugins as standalone files # T319378 (duration: 00m 09s)

Done! I have confirmed the JavaScript plugins are properly loaded and gerrit-theme.js is gone :-]

Change 853306 merged by jenkins-bot:

[operations/software/gerrit@deploy/wmf/stable-3.4] build: add eslint for JavaScript plugins

https://gerrit.wikimedia.org/r/853306