diff --git a/ci-templates/azure-devops/azure-pipelines.yml b/ci-templates/azure-devops/azure-pipelines.yml index 358be6f..5326bce 100644 --- a/ci-templates/azure-devops/azure-pipelines.yml +++ b/ci-templates/azure-devops/azure-pipelines.yml @@ -33,7 +33,7 @@ stages: version: 22.x # An exact version: change it when you upgrade, as # https://docs.ingestron.io/docs/how-to/upgrade#choose-the-version-you-run says. - - script: npm install -g ingestron@2.3.0 + - script: npm install -g ingestron@2.3.1 displayName: Install Ingestron - script: ingestron check displayName: ingestron check diff --git a/ci-templates/azure-devops/ingestron-check.yml b/ci-templates/azure-devops/ingestron-check.yml index 0df120e..0e4dab4 100644 --- a/ci-templates/azure-devops/ingestron-check.yml +++ b/ci-templates/azure-devops/ingestron-check.yml @@ -15,7 +15,7 @@ steps: version: 22.x # An exact version: change it when you upgrade, as # https://docs.ingestron.io/docs/how-to/upgrade#choose-the-version-you-run says. - - script: npm install -g ingestron@2.3.0 + - script: npm install -g ingestron@2.3.1 displayName: Install Ingestron - script: ingestron check displayName: ingestron check diff --git a/ci-templates/github-actions/deploy.yml b/ci-templates/github-actions/deploy.yml index 922bf20..7c6c959 100644 --- a/ci-templates/github-actions/deploy.yml +++ b/ci-templates/github-actions/deploy.yml @@ -29,7 +29,7 @@ jobs: - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0 with: node-version: 22 - - run: npm install -g ingestron@2.3.0 + - run: npm install -g ingestron@2.3.1 - run: ingestron check build: diff --git a/ci-templates/github-actions/ingestron-check.yml b/ci-templates/github-actions/ingestron-check.yml index ea7efe5..e238faa 100644 --- a/ci-templates/github-actions/ingestron-check.yml +++ b/ci-templates/github-actions/ingestron-check.yml @@ -18,5 +18,5 @@ jobs: - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0 with: node-version: 22 - - run: npm install -g ingestron@2.3.0 + - run: npm install -g ingestron@2.3.1 - run: ingestron check diff --git a/content/docs/(reference)/reference/versions.mdx b/content/docs/(reference)/reference/versions.mdx index f65460b..65f5b2f 100644 --- a/content/docs/(reference)/reference/versions.mdx +++ b/content/docs/(reference)/reference/versions.mdx @@ -29,5 +29,5 @@ Connector maturity, such as Public Preview or Beta, is shown on each The [deployment templates](/docs/how-to/deploy-through-environments) pin the tools their stages run: `@microsoft/azure-data-factory-utilities` 1.0.3, the Databricks CLI v1.23.0, and sqlcmd (Go) v1.10.0. Their check stage installs -`ingestron@2.3.0`, and each GitHub action is pinned to a commit, with its +`ingestron@2.3.1`, and each GitHub action is pinned to a commit, with its version beside it. diff --git a/content/docs/(reference)/tools/vscode.mdx b/content/docs/(reference)/tools/vscode.mdx index a00248e..26f12e8 100644 --- a/content/docs/(reference)/tools/vscode.mdx +++ b/content/docs/(reference)/tools/vscode.mdx @@ -279,8 +279,8 @@ Explorer. ## See what will be generated diff --git a/content/docs/how-to/(build)/check-in-ci.mdx b/content/docs/how-to/(build)/check-in-ci.mdx index 3b3a371..9012170 100644 --- a/content/docs/how-to/(build)/check-in-ci.mdx +++ b/content/docs/how-to/(build)/check-in-ci.mdx @@ -8,7 +8,7 @@ from the definitions project folder on every pull request: it fails when someone changed the definitions without generating, so the files you deploy are always what the definitions say. It needs only Node.js 22.13 or later: each template installs an exact version of the command from npm, -`npm install -g ingestron@2.3.0`, then runs it. Change the version when you +`npm install -g ingestron@2.3.1`, then runs it. Change the version when you upgrade, as [Upgrade Ingestron and its packs](/docs/how-to/upgrade#choose-the-version-you-run) shows, so a new release never fails a pull request that changed nothing. diff --git a/content/docs/how-to/(build)/deploy-through-environments.mdx b/content/docs/how-to/(build)/deploy-through-environments.mdx index 4f34c5f..40019ed 100644 --- a/content/docs/how-to/(build)/deploy-through-environments.mdx +++ b/content/docs/how-to/(build)/deploy-through-environments.mdx @@ -43,7 +43,7 @@ The tools are pinned: Microsoft's `@microsoft/azure-data-factory-utilities` 1.0.3, the Databricks CLI v1.23.0 and sqlcmd (Go) v1.10.0, each download checked by its SHA-256 where the template downloads it. Each GitHub action is pinned to a full commit, with its version beside it, and the check installs an -exact Ingestron, `ingestron@2.3.0`: change them when you upgrade. The ADF +exact Ingestron, `ingestron@2.3.1`: change them when you upgrade. The ADF build fetches its build tool from `adf.azure.com`, so the build stage needs network access there. diff --git a/content/docs/how-to/(build)/start-from-a-template.mdx b/content/docs/how-to/(build)/start-from-a-template.mdx index 702b863..3042ae3 100644 --- a/content/docs/how-to/(build)/start-from-a-template.mdx +++ b/content/docs/how-to/(build)/start-from-a-template.mdx @@ -176,7 +176,7 @@ written for `dev` and for `prod`, counts once for `init` and twice for `plan`. For the project above, plan ends: ```text -9 values are still REPLACE_ME; ingestron check fails until each is written. +9 places are still REPLACE_ME; ingestron check fails until each is written. ``` Then make the rest yours: diff --git a/content/docs/how-to/(standards)/ask-the-platform-team.mdx b/content/docs/how-to/(standards)/ask-the-platform-team.mdx index 7c80550..c66ff7d 100644 --- a/content/docs/how-to/(standards)/ask-the-platform-team.mdx +++ b/content/docs/how-to/(standards)/ask-the-platform-team.mdx @@ -192,17 +192,27 @@ how to supply them in CI. ## When the definitions have problems -Any other error stops the request. The request is then only its title and -one line, and the command exits with `1`: +Any other error stops the request. The request is then its title, a note and +each error, written as `ingestron plan` writes a problem, and the command +exits with `1`. For an environment the project does not declare: -```text -# Platform request (dev) +````text +# Platform request (nope) + +The definitions have problems; fix them first: -The definitions have problems; fix them first. +```text +project.yaml:7:3 error UNKNOWN_ENVIRONMENT + Environment "nope" is not declared in project.yaml. + Declared environments: dev. ``` +```` -Run `ingestron plan` to see the problems. Unset variables alone never do -this: with nothing else wrong, the command exits with `0`. +The request reads the value of each variable that is set, so it can find an +error that `ingestron plan` does not: a value the deploying pipeline supplies, +written in your environment, that its setting does not accept. Unset variables +alone never stop the request: with nothing else wrong, the command exits with +`0`. ## Next diff --git a/content/docs/how-to/(standards)/upgrade.mdx b/content/docs/how-to/(standards)/upgrade.mdx index 8ad8ff0..a806fe1 100644 --- a/content/docs/how-to/(standards)/upgrade.mdx +++ b/content/docs/how-to/(standards)/upgrade.mdx @@ -46,7 +46,7 @@ choose to upgrade. The [CI templates](/docs/how-to/check-in-ci) and the [deployment templates](/docs/how-to/deploy-through-environments) do: ```sh -npm install -g ingestron@2.3.0 +npm install -g ingestron@2.3.1 ``` `npm ls -g ingestron` shows the version a computer has installed. @@ -95,7 +95,7 @@ next; see [Deploy through environments](/docs/how-to/deploy-through-environments ### The standard and the folders -1. Install `ingestron@2.3.0` and plan. Every pack is version 2, so a standard that +1. Install `ingestron@2.3.1` and plan. Every pack is version 2, so a standard that names `databricks@1`, `adf@1`, `synapse@1` or `duckdb@1` stops with `PACK_VERSION`, once for all the environments that have it: @@ -135,7 +135,7 @@ next; see [Deploy through environments](/docs/how-to/deploy-through-environments [`DEPLOY_VALUE`](/docs/reference/errors#DEPLOY_VALUE): write it in `project.yaml` for each environment. See [Supplied when deploying](/docs/concepts/yaml-references#supplied-when-deploying). -5. Change CI: the check templates install `ingestron@2.3.0`, and the deploy +5. Change CI: the check templates install `ingestron@2.3.1`, and the deploy pipelines deploy `build//` by target, parameter file or script, as [Deploy through environments](/docs/how-to/deploy-through-environments) shows. @@ -517,6 +517,20 @@ For code that calls the packages: - `@ingestron/authoring` 2.3 adds `ProjectSnapshot.replaceMeHelp`, what a `REPLACE_ME` stands for, and lists a table's intent in its hover. +Release 2.3.1 changes only what the command and the editor say; the generated +files are the same: + +- When an error stops `ingestron request`, the request lists each error, as + `ingestron plan` writes it, after its note. See + [When the definitions have problems](/docs/how-to/ask-the-platform-team#when-the-definitions-have-problems). +- `plan` and `apply` count the places still `REPLACE_ME`: + `8 places are still REPLACE_ME; …`. `init` counts the README's rows, one + per value, so a value written for each environment is one row there and + one place per environment here. +- In VS Code 2.2.1, completion offers a method's settings that are now intent, + such as `mode` and `sequence_by`, after the others, each with the intent + that replaces it. + ## What changed in a release Recent releases are commits whose message starts with the version, such as diff --git a/content/docs/platforms/adf.mdx b/content/docs/platforms/adf.mdx index 69749a4..a33fc91 100644 --- a/content/docs/platforms/adf.mdx +++ b/content/docs/platforms/adf.mdx @@ -185,7 +185,7 @@ appears on every plan, apply and check while the factory uses a runtime, as For the project created without `--set`, plan also warns about each value still `REPLACE_ME`, and ends -`9 values are still REPLACE_ME; ingestron check fails until each is written.`: +`9 places are still REPLACE_ME; ingestron check fails until each is written.`: it counts each place a value is written, where `init` counts names. The files are still written, and `ingestron check` fails until each is written. Run `ingestron apply` to write the files. diff --git a/content/docs/platforms/databricks.mdx b/content/docs/platforms/databricks.mdx index fabe722..73f79e2 100644 --- a/content/docs/platforms/databricks.mdx +++ b/content/docs/platforms/databricks.mdx @@ -168,7 +168,7 @@ create src/retail/silver/daily_sales.sql For the project created without `--set`, plan first warns about each value still `REPLACE_ME`, then lists the same files, and ends -`8 values are still REPLACE_ME; ingestron check fails until each is written.`: +`8 places are still REPLACE_ME; ingestron check fails until each is written.`: it counts each place a value is written, where `init` counts names. Plan and apply still write the files, and `ingestron check` fails until each is written. Run `ingestron apply` to write them. If plan reports a problem diff --git a/package.json b/package.json index 1992e38..3169caf 100644 --- a/package.json +++ b/package.json @@ -23,9 +23,9 @@ "sync:vscode": "node scripts/sync-vscode-commands.mjs" }, "dependencies": { - "@ingestron/authoring": "^2.3.0", - "@ingestron/cli": "^2.3.0", - "@ingestron/core": "^1.1.0", + "@ingestron/authoring": "^2.3.1", + "@ingestron/cli": "^2.3.1", + "@ingestron/core": "^1.1.1", "@ingestron/definitions": "^1.13.0", "@ingestron/pack-adf": "^2.3.0", "@ingestron/pack-databricks": "^2.3.0", diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 886d88c..79426e5 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -9,14 +9,14 @@ importers: .: dependencies: '@ingestron/authoring': - specifier: ^2.3.0 - version: 2.3.0 + specifier: ^2.3.1 + version: 2.3.1 '@ingestron/cli': - specifier: ^2.3.0 - version: 2.3.0 + specifier: ^2.3.1 + version: 2.3.1 '@ingestron/core': - specifier: ^1.1.0 - version: 1.1.0 + specifier: ^1.1.1 + version: 1.1.1 '@ingestron/definitions': specifier: ^1.13.0 version: 1.13.0 @@ -789,12 +789,12 @@ packages: cpu: [x64] os: [win32] - '@ingestron/authoring@2.3.0': - resolution: {integrity: sha512-ZtYvDOXzAglpLY607pCyTgYViSHAP98xJQr9TZ+nPxrT83oUg2khpS+e12j1lt3HJ3S1P9s84tcpiIspV+KRhA==} + '@ingestron/authoring@2.3.1': + resolution: {integrity: sha512-Z5yYloIYlyvbjGB4d961HVIdd8erWqjwYX/5of+bxu6jrWHJBdm3b/dVJV/H0l6bgydyVOpaP1NVFUCuJULDOQ==} engines: {node: '>=22.13.0'} - '@ingestron/cli@2.3.0': - resolution: {integrity: sha512-KdoApSz8ycGNDBwMsy2qqnhwDchqY8UkbmLxQa4yuvplR3OHsnsUe3xAFpsshA3CTeYyu73/lu8xm7fdjh6aeA==} + '@ingestron/cli@2.3.1': + resolution: {integrity: sha512-24CUipuWMChcmwF2Ez20vWEndyF6suIz1eRikesoSA1cTiPt8Zxn7V8axHi8ZbWGSHGLcya3N8B/viNCfUcovw==} engines: {node: '>=22.13.0'} hasBin: true @@ -802,8 +802,8 @@ packages: resolution: {integrity: sha512-ybWLmq4xf4RARirY24MxqwzAyS0KDMLMuoWVW71zRxaCXzclDeuKjNx8UYt6Kfhcqwy6aXty2zhJQhj/7LMmbQ==} engines: {node: '>=22.13.0'} - '@ingestron/core@1.1.0': - resolution: {integrity: sha512-6e1u6sJNRRsjcMLLhryH0gjDqCl7N2Exvc3CVEo1blvhvriSJBFsjt78tfQDfHHeL/CIcovFKGR5czEPF5eUJg==} + '@ingestron/core@1.1.1': + resolution: {integrity: sha512-srMNFH2s0vKkMs6BsK9AcKgi3M12301QGIkwguOzJtQoRr2jWt7yR2Cy7JodkxNtZeVg1oy4zG86b3c3aZJGHg==} engines: {node: '>=22.13.0'} '@ingestron/definitions@1.13.0': @@ -3334,18 +3334,18 @@ snapshots: '@img/sharp-win32-x64@0.35.5': optional: true - '@ingestron/authoring@2.3.0': + '@ingestron/authoring@2.3.1': dependencies: '@ingestron/config': 1.7.0 - '@ingestron/core': 1.1.0 + '@ingestron/core': 1.1.1 '@ingestron/definitions': 1.13.0 '@ingestron/generate': 1.1.0 yaml: 2.9.1 - '@ingestron/cli@2.3.0': + '@ingestron/cli@2.3.1': dependencies: '@ingestron/config': 1.7.0 - '@ingestron/core': 1.1.0 + '@ingestron/core': 1.1.1 '@ingestron/definitions': 1.13.0 '@ingestron/generate': 1.1.0 yaml: 2.9.1 @@ -3355,7 +3355,7 @@ snapshots: ajv: 8.20.0 yaml: 2.9.1 - '@ingestron/core@1.1.0': + '@ingestron/core@1.1.1': dependencies: '@ingestron/config': 1.7.0 '@ingestron/definitions': 1.13.0 diff --git a/public/images/vscode/platform-request-dark.png b/public/images/vscode/platform-request-dark.png index ce07502..e6ab432 100644 Binary files a/public/images/vscode/platform-request-dark.png and b/public/images/vscode/platform-request-dark.png differ diff --git a/public/images/vscode/platform-request-light.png b/public/images/vscode/platform-request-light.png index 85496c2..66470f8 100644 Binary files a/public/images/vscode/platform-request-light.png and b/public/images/vscode/platform-request-light.png differ diff --git a/public/images/vscode/reference-dark.png b/public/images/vscode/reference-dark.png index 4d6ee47..a72713b 100644 Binary files a/public/images/vscode/reference-dark.png and b/public/images/vscode/reference-dark.png differ diff --git a/public/images/vscode/reference-light.png b/public/images/vscode/reference-light.png index 608e344..b370e23 100644 Binary files a/public/images/vscode/reference-light.png and b/public/images/vscode/reference-light.png differ diff --git a/scripts/ci-templates.test.mjs b/scripts/ci-templates.test.mjs index 858ebdb..05ce41f 100644 --- a/scripts/ci-templates.test.mjs +++ b/scripts/ci-templates.test.mjs @@ -58,7 +58,7 @@ test("every YAML template parses, and the folder holds no other kind of file", ( * The ingestron bundle the templates install: an exact version, the one the * docs build with (test/standards-and-teams.test.ts checks the cli's version). */ -const bundle = "2.3.0"; +const bundle = "2.3.1"; test("each check installs an exact ingestron from npm, then runs ingestron check", () => { for (const file of [...checks, "github-actions/deploy.yml", "azure-devops/azure-pipelines.yml"]) { diff --git a/test/extracts.test.ts b/test/extracts.test.ts index f4c32b7..2b67948 100644 --- a/test/extracts.test.ts +++ b/test/extracts.test.ts @@ -243,7 +243,7 @@ describe("the platform request", () => { it("fails with the request's output when the request fails", () => { expect(() => exampleRequest("landing-only", "nope")).toThrow( - 'Example "landing-only": the request for nope fails:\n# Platform request (nope)\n\nThe definitions have problems; fix them first.\n', + 'Example "landing-only": the request for nope fails:\n# Platform request (nope)\n\nThe definitions have problems; fix them first:\n\n```text\nproject.yaml:5:3 error UNKNOWN_ENVIRONMENT\n Environment "nope" is not declared in project.yaml.\n Declared environments: dev, prod.\n```\n', ); }); diff --git a/test/platform-pages.test.ts b/test/platform-pages.test.ts index 8784c60..7853f2f 100644 --- a/test/platform-pages.test.ts +++ b/test/platform-pages.test.ts @@ -291,6 +291,6 @@ describe("reference/versions", () => { expect(tools).toContain(`\`@microsoft/azure-data-factory-utilities\` ${adf}`); expect(tools).toContain(`Databricks CLI ${databricks}`); expect(tools).toContain(`sqlcmd (Go) ${sqlcmd}`); - expect(tools).toContain("`ingestron@2.3.0`"); + expect(tools).toContain("`ingestron@2.3.1`"); }); }); diff --git a/test/standards-and-teams.test.ts b/test/standards-and-teams.test.ts index 0b8cb5b..ec0e23f 100644 --- a/test/standards-and-teams.test.ts +++ b/test/standards-and-teams.test.ts @@ -39,8 +39,11 @@ const joined = (text: string) => ); /** The page's request command, run in a folder: its exit code and output. */ -const request = (page: string, cwd: string) => - cli(cwd, command(commands(section(page, "## What each route asks for")), "request")); +const request = (page: string, cwd: string, environment?: string) => { + const args = command(commands(section(page, "## What each route asks for")), "request"); + if (environment) args[args.indexOf("--env") + 1] = environment; + return cli(cwd, args); +}; /** The `shop` project the request guide creates from the minimal starter, with its own commands. */ function shop(page: string): string { @@ -124,17 +127,16 @@ describe("how-to/ask-the-platform-team", () => { expect(values).toContain("`.env.dev`"); }); - it("is only the title and one line when the definitions have problems, and exits with 1", () => { + it("lists the errors when the definitions have problems, as the page shows, and exits with 1", () => { const problems = section(page, "## When the definitions have problems"); - const cwd = shop(page); - const connection = join(cwd, "connections/shop.yaml"); - writeFileSync( - connection, - readFileSync(connection, "utf8").replace("connector: files", "connector: nothing"), - ); - const broken = request(page, cwd); + // The page's example: an environment the project does not declare. Its block holds a + // fenced block, so it is fenced with four backticks. + const shown = /^````text\n([\s\S]*?)^````$/m.exec(problems)?.[1]; + expect(shown, "the four-backtick text block").toBeDefined(); + expect(problems).toContain("For an environment the project does not declare:"); + const broken = request(page, shop(page), "nope"); expect(broken.code).toBe(1); - expect(broken.output.trim()).toBe(fences(problems, "text")[0]!.trim()); + expect(broken.output.trim()).toBe(shown!.trim()); expect(problems).toContain("exits with `1`"); }); }); @@ -324,7 +326,7 @@ describe("how-to/upgrade", () => { it("pins the exact bundle these pages describe, as the templates install it", () => { // The ingestron bundle these pages describe: the installed cli's version. - const bundle = "2.3.0"; + const bundle = "2.3.1"; const choose = section(page, "## Choose the version you run"); const version = JSON.parse( readFileSync(join(process.cwd(), "node_modules/@ingestron/cli/package.json"), "utf8"),