Merge branch 'master' into no-envars

bin/cml.js

@@ -10,24 +10,7 @@ const yargs = require('yargs');
 const CML = require('../src/cml').default;
 const { jitsuEventPayload, send } = require('../src/analytics');
 
-const setupOpts = (opts) => {
-  const legacyEnvironmentVariables = {
-    TB_CREDENTIALS: 'CML_TENSORBOARD_DEV_CREDENTIALS',
-    DOCKER_MACHINE: 'CML_RUNNER_DOCKER_MACHINE',
-    RUNNER_IDLE_TIMEOUT: 'CML_RUNNER_IDLE_TIMEOUT',
-    RUNNER_LABELS: 'CML_RUNNER_LABELS',
-    RUNNER_SINGLE: 'CML_RUNNER_SINGLE',
-    RUNNER_REUSE: 'CML_RUNNER_REUSE',
-    RUNNER_NO_RETRY: 'CML_RUNNER_NO_RETRY',
-    RUNNER_DRIVER: 'CML_RUNNER_DRIVER',
-    RUNNER_REPO: 'CML_RUNNER_REPO',
-    RUNNER_PATH: 'CML_RUNNER_PATH'
-  };
-
-  for (const [oldName, newName] of Object.entries(legacyEnvironmentVariables)) {
-    if (process.env[oldName]) process.env[newName] = process.env[oldName];
-  }
-
+const aliasLegacyEnvironmentVariables = () => {
   const legacyEnvironmentPrefixes = {
     CML_CI: 'CML_REPO',
     CML_PUBLISH: 'CML_ASSET',
@@ -46,6 +29,25 @@ const setupOpts = (opts) => {
     }
   }
 
+  const legacyEnvironmentVariables = {
+    TB_CREDENTIALS: 'CML_TENSORBOARD_CREDENTIALS',
+    DOCKER_MACHINE: 'CML_RUNNER_DOCKER_MACHINE',
+    RUNNER_IDLE_TIMEOUT: 'CML_RUNNER_IDLE_TIMEOUT',
+    RUNNER_LABELS: 'CML_RUNNER_LABELS',
+    RUNNER_SINGLE: 'CML_RUNNER_SINGLE',
+    RUNNER_REUSE: 'CML_RUNNER_REUSE',
+    RUNNER_NO_RETRY: 'CML_RUNNER_NO_RETRY',
+    RUNNER_DRIVER: 'CML_RUNNER_DRIVER',
+    RUNNER_REPO: 'CML_RUNNER_REPO',
+    RUNNER_PATH: 'CML_RUNNER_PATH'
+  };
+
+  for (const [oldName, newName] of Object.entries(legacyEnvironmentVariables)) {
+    if (process.env[oldName]) process.env[newName] = process.env[oldName];
+  }
+};
+
+const setupOpts = (opts) => {
   const { markdownfile } = opts;
   opts.markdownFile = markdownfile;
   opts.cml = new CML(opts);
@@ -117,6 +119,7 @@ const handleError = (message, error) => {
 };
 
 (async () => {
+  aliasLegacyEnvironmentVariables();
   setupLogger({ log: 'debug' });
 
   try {

bin/cml.test.js

@@ -1,4 +1,5 @@
 const { exec } = require('../src/utils');
+const fetch = require('node-fetch');
 
 describe('command-line interface tests', () => {
   test('cml --help', async () => {
@@ -31,3 +32,21 @@ describe('command-line interface tests', () => {
     `);
   });
 });
+
+describe('Valid Docs URLs', () => {
+  test.each([
+    'workflow/rerun',
+    'tensorboard/connect',
+    'runner/launch',
+    'repo/prepare',
+    'pr/create',
+    'comment/create',
+    'comment/update',
+    'check/create',
+    'asset/publish'
+  ])('Check Docs Link', async (cmd) => {
+    const { DOCSURL } = require(`./cml/${cmd}`);
+    const { status } = await fetch(DOCSURL);
+    expect(status).toBe(200);
+  });
+});

bin/cml/asset/publish.js

@@ -4,8 +4,11 @@ const winston = require('winston');
 
 const { CML } = require('../../../src/cml');
 
+const DESCRIPTION = 'Publish an asset';
+const DOCSURL = 'https://cml.dev/doc/usage#cml-reports';
+
 exports.command = 'publish <asset>';
-exports.description = 'Publish an asset';
+exports.description = `${DESCRIPTION}\n${DOCSURL}`;
 
 exports.handler = async (opts) => {
   if (opts.gitlabUploads) {
@@ -56,6 +59,7 @@ exports.options = kebabcaseKeys({
   rmWatermark: {
     type: 'boolean',
     description: 'Avoid CML watermark.',
+    hidden: true,
     telemetryData: 'name'
   },
   mimeType: {
@@ -76,3 +80,4 @@ exports.options = kebabcaseKeys({
       'Specifies the repo to be used. If not specified is extracted from the CI ENV.'
   }
 });
+exports.DOCSURL = DOCSURL;

bin/cml/asset/publish.test.js

@@ -20,12 +20,11 @@ describe('CML cli test', () => {
             --help    Show help                                              [boolean]
 
       Options:
-            --md            Output in markdown format [title || name](url)   [boolean]
-        -t, --title         Markdown title [title](url) or ![](url title)     [string]
-            --native        Uses driver's native capabilities to upload assets instead
-                            of CML's storage; not available on GitHub        [boolean]
-            --rm-watermark  Avoid CML watermark.                             [boolean]
-            --mime-type     MIME type [string] [default: infer from the file contents]"
+            --md         Output in markdown format [title || name](url)      [boolean]
+        -t, --title      Markdown title [title](url) or ![](url title)        [string]
+            --native     Uses driver's native capabilities to upload assets instead of
+                         CML's storage; not available on GitHub              [boolean]
+            --mime-type  MIME type    [string] [default: infer from the file contents]"
     `);
   });
 });

bin/cml/check/create.js

@@ -1,8 +1,11 @@
 const fs = require('fs').promises;
 const kebabcaseKeys = require('kebabcase-keys');
 
+const DESCRIPTION = 'Create a check report';
+const DOCSURL = 'https://cml.dev/doc/ref/check';
+
 exports.command = 'create <markdown file>';
-exports.description = 'Create a check report';
+exports.description = `${DESCRIPTION}\n${DOCSURL}`;
 
 exports.handler = async (opts) => {
   const { cml, markdownfile } = opts;
@@ -53,3 +56,4 @@ exports.options = kebabcaseKeys({
     description: 'Title of the check'
   }
 });
+exports.DOCSURL = DOCSURL;

bin/cml/comment/create.js

@@ -1,7 +1,10 @@
 const kebabcaseKeys = require('kebabcase-keys');
 
+const DESCRIPTION = 'Create a comment';
+const DOCSURL = 'https://cml.dev/doc/ref/comment#create';
+
 exports.command = 'create <markdown file>';
-exports.description = 'Create a comment';
+exports.description = `${DESCRIPTION}\n${DOCSURL}`;
 
 exports.handler = async (opts) => {
   const { cml } = opts;
@@ -63,6 +66,15 @@ exports.options = kebabcaseKeys({
     type: 'boolean',
     description:
       'Avoid watermark; CML needs a watermark to be able to distinguish CML comments from others',
+    hidden: true,
     telemetryData: 'name'
+  },
+  watermarkTitle: {
+    type: 'string',
+    description:
+      'Hidden comment marker (used for targeting in subsequent `cml comment update`); "{workflow}" & "{run}" are auto-replaced',
+    default: '',
+    conflicts: ['rmWatermark']
   }
 });
+exports.DOCSURL = DOCSURL;

bin/cml/comment/create.test.js

@@ -3,7 +3,6 @@ const { exec } = require('../../../src/utils');
 describe('Comment integration tests', () => {
   test('cml send-comment --help', async () => {
     const output = await exec(`node ./bin/cml.js send-comment --help`);
-
     expect(output).toMatchInlineSnapshot(`
       "cml.js send-comment <markdown file>
 
@@ -31,8 +30,9 @@ describe('Comment integration tests', () => {
         --publish-native, --native  Uses driver's native capabilities to upload assets
                                     instead of CML's storage; not available on GitHub
                                                                              [boolean]
-        --rm-watermark              Avoid watermark; CML needs a watermark to be able
-                                    to distinguish CML comments from others  [boolean]"
+        --watermark-title           Hidden comment marker (used for targeting in
+                                    subsequent \`cml comment update\`); \\"{workflow}\\" &
+                                    \\"{run}\\" are auto-replaced   [string] [default: \\"\\"]"
     `);
   });
 });

bin/cml/comment/update.js

@@ -1,10 +1,14 @@
 const { builder, handler } = require('./create');
 
+const DESCRIPTION = 'Update a comment';
+const DOCSURL = 'https://cml.dev/doc/ref/comment#update';
+
 exports.command = 'update <markdown file>';
-exports.description = 'Update a comment';
+exports.description = `${DESCRIPTION}\n${DOCSURL}`;
 
 exports.handler = async (opts) => {
   await handler({ ...opts, update: true });
 };
 
 exports.builder = builder;
+exports.DOCSURL = DOCSURL;

bin/cml/pr/create.e2e.test.js

@@ -12,6 +12,7 @@ describe('CML e2e', () => {
       Commands:
         cml.js pr create <glob path...>  Create a pull request with the specified
                                          files
+                                         https://cml.dev/doc/ref/pr
 
       Global Options:
         --log     Logging verbosity

bin/cml/pr/create.js

@@ -6,8 +6,11 @@ const {
   GIT_USER_EMAIL
 } = require('../../../src/cml');
 
+const DESCRIPTION = 'Create a pull request with the specified files';
+const DOCSURL = 'https://cml.dev/doc/ref/pr';
+
 exports.command = 'create <glob path...>';
-exports.description = 'Create a pull request with the specified files';
+exports.description = `${DESCRIPTION}\n${DOCSURL}`;
 
 exports.handler = async (opts) => {
   const { cml, globpath: globs } = opts;
@@ -78,3 +81,4 @@ exports.options = kebabcaseKeys({
     description: 'Git user name'
   }
 });
+exports.DOCSURL = DOCSURL;

bin/cml/repo/prepare.js

@@ -2,8 +2,11 @@ const kebabcaseKeys = require('kebabcase-keys');
 
 const { GIT_USER_NAME, GIT_USER_EMAIL } = require('../../../src/cml');
 
+const DESCRIPTION = 'Prepare the cloned repository';
+const DOCSURL = 'https://cml.dev/doc/ref/ci';
+
 exports.command = 'prepare';
-exports.description = 'Prepare the cloned repository';
+exports.description = `${DESCRIPTION}\n${DOCSURL}`;
 
 exports.handler = async (opts) => {
   const { cml } = opts;
@@ -17,10 +20,15 @@ exports.builder = (yargs) =>
     .options(exports.options);
 
 exports.options = kebabcaseKeys({
+  fetchDepth: {
+    type: 'number',
+    description: 'Number of commits to fetch (use `0` for all branches & tags)'
+  },
   unshallow: {
     type: 'boolean',
     description:
-      'Fetch as much as possible, converting a shallow repository to a complete one'
+      'Fetch as much as possible, converting a shallow repository to a complete one',
+    hidden: true
   },
   userEmail: {
     type: 'string',
@@ -33,3 +41,4 @@ exports.options = kebabcaseKeys({
     description: 'Git user name'
   }
 });
+exports.DOCSURL = DOCSURL;

bin/cml/repo/prepare.test.js

@@ -20,10 +20,10 @@ describe('CML e2e', () => {
         --help    Show help                                                  [boolean]
 
       Options:
-        --unshallow   Fetch as much as possible, converting a shallow repository to a
-                      complete one                                           [boolean]
-        --user-email  Git user email         [string] [default: \\"[email protected]\\"]
-        --user-name   Git user name                  [string] [default: \\"Olivaw[bot]\\"]"
+        --fetch-depth  Number of commits to fetch (use \`0\` for all branches & tags)
+                                                                              [number]
+        --user-email   Git user email        [string] [default: \\"[email protected]\\"]
+        --user-name    Git user name                 [string] [default: \\"Olivaw[bot]\\"]"
     `);
   });
 });

bin/cml/runner/launch.js

@@ -404,8 +404,11 @@ const run = async (opts) => {
   else await runLocal(opts);
 };
 
+const DESCRIPTION = 'Launch and register a self-hosted runner';
+const DOCSURL = 'https://cml.dev/doc/ref/runner';
+
 exports.command = 'launch';
-exports.description = 'Launch and register a self-hosted runner';
+exports.description = `${DESCRIPTION}\n${DOCSURL}`;
 
 exports.handler = async (opts) => {
   ({ cml } = opts);
@@ -492,7 +495,8 @@ exports.options = kebabcaseKeys({
   cloudType: {
     type: 'string',
     description:
-      'Instance type. Choices: [m, l, xl]. Also supports native types like i.e. t2.micro'
+      'Instance type. Choices: [m, l, xl]. Also supports native types like i.e. t2.micro',
+    telemetryData: 'full'
   },
   cloudPermissionSet: {
     type: 'string',
@@ -515,7 +519,8 @@ exports.options = kebabcaseKeys({
     type: 'string',
     description:
       'GPU type. Choices: k80, v100, or native types e.g. nvidia-tesla-t4',
-    coerce: (val) => (val === 'nogpu' ? undefined : val)
+    coerce: (val) => (val === 'nogpu' ? undefined : val),
+    telemetryData: 'full'
   },
   cloudHddSize: {
     type: 'number',
@@ -579,3 +584,4 @@ exports.options = kebabcaseKeys({
       'Seconds to wait for collecting logs on failure (https://github.com/iterative/cml/issues/413)'
   }
 });
+exports.DOCSURL = DOCSURL;

bin/cml/runner/launch.test.js

@@ -11,6 +11,7 @@ describe('CML e2e', () => {
 
       Commands:
         cml.js runner launch  Launch and register a self-hosted runner
+                              https://cml.dev/doc/ref/runner
 
       Global Options:
         --log     Logging verbosity

bin/cml/tensorboard/connect.js

@@ -73,8 +73,12 @@ const launchAndWaitLink = async (opts = {}) => {
 };
 
 exports.tbLink = tbLink;
+
+const DESCRIPTION = 'Connect to tensorboard.dev and get a link';
+const DOCSURL = 'https://cml.dev/doc/ref/tensorboard';
+
 exports.command = 'connect';
-exports.description = 'Connect to tensorboard.dev and get a link';
+exports.description = `${DESCRIPTION}\n${DOCSURL}`;
 
 exports.handler = async (opts) => {
   const { file, credentials, name, description } = opts;
@@ -141,6 +145,8 @@ exports.options = kebabcaseKeys({
   rmWatermark: {
     type: 'boolean',
     description: 'Avoid CML watermark',
+    hidden: true,
     telemetryData: 'name'
   }
 });
+exports.DOCSURL = DOCSURL;

bin/cml/tensorboard/connect.test.js

@@ -20,17 +20,16 @@ describe('CML e2e', () => {
             --help    Show help                                              [boolean]
 
       Options:
-        -c, --credentials   TensorBoard credentials as JSON, usually found at
-                            ~/.config/tensorboard/credentials/uploader-creds.json
+        -c, --credentials  TensorBoard credentials as JSON, usually found at
+                           ~/.config/tensorboard/credentials/uploader-creds.json
                                                                    [string] [required]
-            --logdir        Directory containing the logs to process          [string]
-            --name          Tensorboard experiment title; max 100 characters  [string]
-            --description   Tensorboard experiment description in Markdown format; max
-                            600 characters                                    [string]
-            --md            Output as markdown [title || name](url)          [boolean]
-        -t, --title         Markdown title, if not specified, param name will be used
-                                                                              [string]
-            --rm-watermark  Avoid CML watermark                              [boolean]"
+            --logdir       Directory containing the logs to process           [string]
+            --name         Tensorboard experiment title; max 100 characters   [string]
+            --description  Tensorboard experiment description in Markdown format; max
+                           600 characters                                     [string]
+            --md           Output as markdown [title || name](url)           [boolean]
+        -t, --title        Markdown title, if not specified, param name will be used
+                                                                              [string]"
     `);
   });
 });