Merge branch 'master' into nav--menu

Author: jorgeorpinel

.circleci/config.yml

@@ -8,7 +8,7 @@ defaults: &defaults
   working_directory: ~/repo
   docker:
     # Specify the version you desire here.
-    - image: circleci/node:16
+    - image: cimg/node:18.14.1
 
     # Specify service dependencies here if necessary.
     # CircleCI maintains a library of pre-built images,

.github/workflows/check-deployment.yml

@@ -0,0 +1,16 @@
+name: Check Deployment
+on:
+  workflow_dispatch:
+    inputs:
+      passci:
+        description: 'Pass CI'
+        required: true
+        type: boolean
+  pull_request:
+    types: [opened, synchronize, reopened, labeled]
+
+jobs:
+  check-deployment:
+    uses: iterative/gatsby-theme-iterative/.github/workflows/check-deployment.yml@main
+    with:
+      passci: ${{ inputs.passci || false }}

.github/workflows/link-check-all.yml

@@ -5,4 +5,4 @@ on:
     - cron: '0 0 * * *'
 jobs:
   run:
-    uses: iterative/link-check/.github/workflows/link-check-all.yml@v0.13.1
+    uses: iterative/link-check/.github/workflows/link-check-all.yml@v0.14.0

.github/workflows/link-check-deploy.yml

@@ -3,4 +3,4 @@ on:
   deployment_status:
 jobs:
   run:
-    uses: iterative/link-check/.github/workflows/link-check-deployment-status.yml@v0.13.1
+    uses: iterative/link-check/.github/workflows/link-check-deployment-status.yml@v0.14.0

content/docs/cml-with-dvc.md

@@ -21,8 +21,6 @@ jobs:
     # container: docker://ghcr.io/iterative/cml:0-dvc2-base1
     steps:
       - uses: actions/checkout@v3
-        with:
-          ref: ${{ github.event.pull_request.head.sha }}
       - uses: actions/setup-python@v4
         with:
           python-version: '3.x'
@@ -91,8 +89,6 @@ Windows, Python 3 should be setup first.
 ```yaml
 steps:
   - uses: actions/checkout@v3
-    with:
-      ref: ${{ github.event.pull_request.head.sha }}
   - uses: iterative/setup-dvc@v1
 ```
 
@@ -103,8 +99,6 @@ steps:
 runs-on: windows-latest
 steps:
   - uses: actions/checkout@v3
-    with:
-      ref: ${{ github.event.pull_request.head.sha }}
   - uses: actions/setup-python@v4
     with:
       python-version: '3.x'
@@ -126,16 +120,16 @@ to the [latest release](https://github.com/iterative/dvc/releases)).
 </tab>
 <tab title="GitLab">
 
-![](/img/github/dvc-report.png 'GitLab DVC report example')
+![](/img/gitlab/dvc-report.png 'GitLab DVC report example')
 
 The `.gitlab-ci.yml` file to create this report is:
 
 ```yaml
 train-and-report:
   image: iterativeai/cml:0-dvc2-base1 # Python, DVC, & CML pre-installed
   script:
-    - dvc pull data --run-cache # Pull data & run-cache from S3
     - pip install -r requirements.txt # Install dependencies
+    - dvc pull data --run-cache # Pull data & run-cache from S3
     - dvc repro # Reproduce pipeline
 
     # Create CML report
@@ -156,6 +150,39 @@ See the [example repository](https://gitlab.com/iterative.ai/cml-dvc-case) for
 more, or check out the
 [use cases for machine learning](https://dvc.org/doc/use-cases/ci-cd-for-machine-learning).
 
+</tab>
+<tab title="Bitbucket">
+
+![](/img/bitbucket/dvc-report.png 'Bitbucket DVC report example')
+
+The `bitbucket-pipelines.yml` file to create this report is:
+
+```yaml
+image: iterativeai/cml:0-dvc2-base1 # Python, DVC, & CML pre-installed
+pipelines:
+  default:
+    - step:
+        name: Train model
+        script:
+          - pip install -r requirements.txt # Install dependencies
+          - dvc pull data --run-cache # Pull data & run-cache from S3
+          - dvc repro # Reproduce pipeline
+    - step:
+        name: Create CML report
+        script:
+          - echo "## Metrics: workflow vs. main" >> report.md
+          - git fetch --depth=1 origin main:main
+          - dvc metrics diff --show-md main >> report.md
+
+          - echo "## Plots" >> report.md
+          - echo "### Training loss function diff" >> report.md
+          - dvc plots diff --target loss.csv --show-vega main > vega.json
+          - vl2png vega.json > plot.png
+          - echo '![](./plot.png "Training Loss")' >> report.md
+
+          - cml comment create report.md
+```
+
 </tab>
 </toggle>
 

content/docs/ref/comment.md

@@ -2,7 +2,7 @@
 
 ## create
 
-Post a Markdown report as a comment on a commit or pull/merge request.
+Post a markdown report as a comment on a commit, pull/merge request, or issue.
 
 ```usage
 cml comment create [options] <markdown report file>
@@ -19,36 +19,58 @@ cml comment update [options] <markdown report file>
 
 <admon type="tip">
 
-If there's an associated pull/merge request, consider using `update` with the
-`--pr` flag.
-
-</admon>
-
-<admon type="tip">
-
-If [`cml pr`](/doc/ref/pr) was used earlier in the workflow, use
-`--commit-sha=HEAD` to post comments to the new PR if desired.
+When using multiple reports, use
+[`--watermark-title=<...>`](#managing-multiple-comments) to specify which
+comment to `update`.
 
 </admon>
 
 ## Options
 
 Any [generic option](/doc/ref) in addition to:
 
-- `--commit-sha=<rev>`, `--head-sha=<rev>`:
-  [Git revision](https://git-scm.com/docs/gitrevisions) linked to this comment
-  [default: `HEAD`].
-- `--pr`: Post to an existing PR/MR associated with the specified commit.
+- `--target=<pr|commit|issue>[/ref]`: Where to post/associate with the comment
+  (`pr`, `commit`, `issue`), optionally with a reference (`issue/12`, `pr/17`,
+  `commit/`[rev](https://git-scm.com/docs/gitrevisions) [default: `pr` falling
+  back to `commit/HEAD`].
 - `--watch`: Watch for changes and automatically update the comment (doesn't
   exit, consider
   [appending `&` to run in the background](<https://en.wikipedia.org/wiki/Job_control_(Unix)#Implementation>)).
 - `--publish=<true|false>`: Upload any local images found in the Markdown report
   [default: `true`].
 - `--publish-native`: Use `--driver`'s native capabilities to `--publish` assets
   instead of `--publish-url` (not available on `--driver=github`).
-- `--publish-url=<url>`: Self-hosted image server URL [default:
+- `--publish-url=<...>`: Self-hosted image server URL [default:
   `https://asset.cml.dev`], see
   [minroud-s3](https://github.com/iterative/minroud-s3).
+- `--watermark-title=<...>`: Hidden comment marker (useful to
+  [specify which comment to update](#managing-multiple-comments) in subsequent
+  `cml comment update` calls); `"{workflow}"` and `"{run}"` are auto-replaced.
+
+## Examples
+
+### Managing multiple comments
+
+Repeatedly running `cml comment create` may produce too many comments. Meanwhile
+`cml comment update` will only produce/update one comment. What if you'd like to
+have exactly two comments (corresponding to two different markdown reports,
+possibly from different parallel workflows) visible at a time?
+
+To mark and subsequently update a particular comment, use
+`--watermark-title="some text"`. To mark a comment according to the workflow or
+run ID, include the placeholder text `"{workflow}"` and `"{run}"`. For example:
+
+```cli
+# Create and constantly update 2 separate comments
+$ cml comment update --watch --watermark-title='first {workflow} report' report.md &
+$ cml comment update --watch --watermark-title='second {workflow} report' debug.md &
+$ python train.py --report-file=report.md --debug-file=debug.md
+
+# Same, but create a new pair of comments if rerunning a workflow
+$ cml comment update --watch --watermark-title='first {run} report' report.md &
+$ cml comment update --watch --watermark-title='second {run} report' debug.md &
+$ python train.py --report-file=report.md --debug-file=debug.md
+```
 
 ## FAQs and Known Issues
 

content/docs/ref/pr.md

@@ -6,7 +6,7 @@ cml pr create [options] <pathspec>...
 
 Commit specified files to a new branch and create a pull request. If sending a
 report afterwards, consider using
-[`cml comment update --pr`](/doc/ref/comment#update).
+[`cml comment update`](/doc/ref/comment#update).
 
 <admon type="info">