@mnci/cli 4.13.1 → 4.15.0

package/README.md

@@ -102,6 +102,8 @@ mnci add python-vendor shared --lib core  # wire core's module into shared's bui
 
 # Go (@nx-go/nx-go — one root go.mod, golangci-lint + go test)
 mnci add go-app api            # executable -> apps/ (binary, zipped into the drop)
+mnci add go-app cli --release  # ...released: tag + per-platform zips on the GitHub Release
+mnci add go-app tray --cgo     # needs a C toolchain: built on a runner of each OS
 mnci add go-function-app fn    # serverless handler -> apps/
 mnci add go-lib core           # publishable (by git tag) -> packages/
 mnci add go-internal-lib util  # private shared package -> libs/
@@ -693,6 +695,7 @@ copy is discarded.
 | ------------------ | -------------------------------------------------------------- | -------------------------------------- |
 | `apps/`            | React / Node / Python / Go / Flutter apps (plain or Functions) | Never (packed into the drop)           |
 | `apps/` (tagged)   | VS Code extensions (`type:vscode-extension`)                   | Yes — `nx release`, `vsce publish`     |
+| `apps/` (tagged)   | Go apps added with `--release` (`release:go`)                  | Yes — `nx release` tag, zips on the GitHub Release |
 | `packages/`        | Publishable npm libraries, plus Go and Dart packages           | Yes — `nx release`, per-package tags   |
 | `python-packages/` | Publishable Python packages (hatchling wheels)                 | Yes — `twine upload` (Azure Artifacts) |
 | `libs/`            | Internal libraries (TS, Python, Go or Dart), never published   | Never                                  |
@@ -719,6 +722,11 @@ rewritten by every `mnci upgrade`, so a hand-added `apps/my-extension` would be
 lost, while a tag matcher is the same on every upgrade and covers every extension
 there will ever be.
 
+The third is an opt-in: a **Go app** added with `mnci add go-app <name> --release`
+is tagged `release:go` and joins the release the same way. Without the flag an app
+stays unreleased, because most Go apps are internal tools. See _Releasing a Go
+app_ in the Go section.
+
 Every kind builds to its own Nx-default output location (`apps/<name>/dist`,
 `packages/<name>/dist`, ...) — no post-generation build-output rewiring for
 any kind. `mnci add` is pure delegation to the official generators; each
@@ -1410,6 +1418,16 @@ pipeline installs `golangci-lint` itself (see below).
   per-project `go.mod` — which single-module mode does not have, so nothing
   is inferred. mnci writes them into `project.json` instead, as it already
   does for most kinds.
+- **The project graph is still inferred, so `affected` is correct.** What the
+  plugin does not infer is targets; it still derives the _graph_ from imports.
+  An app that imports `libs/<name>/<slice>` depends on that lib, transitively,
+  and every app sharing a lib is affected when it changes (measured on
+  `@nx-go/nx-go` 4.1.1 with Nx 23.2.0, including a dependency created only by a
+  test file's import). That matters because the pipeline verifies only the
+  affected projects on a pull request: a missing edge would let a lib change
+  pass without testing the apps that use it. The e2e pins the edges and the
+  affected sets (russoedu/MoNecromanCi#260), since they are the plugin's
+  behaviour rather than mnci's.
 - **Lint is `golangci-lint`, pinned deliberately.** The plugin's `lint`
   executor defaults to `go fmt`, which only reformats — a green lint step
   with that default would mean nothing. The generated target passes
@@ -1422,6 +1440,87 @@ pipeline installs `golangci-lint` itself (see below).
   `nx-release-publish` target is written: there is nothing to push. The only
   real difference between `go-lib` and `go-internal-lib` is intent, recorded
   in the `type:go-lib` tag and the `packages/` location.
+- **Pure-Go apps are cross-compiled; an app that needs a C toolchain is not
+  (`mnci add go-app <name> --cgo`).** `build-all` builds six static binaries from
+  one machine with `CGO_ENABLED=0`, which is right until the app needs cgo: a
+  system-tray icon (Cocoa on macOS, GTK on Linux), a native GUI toolkit, a cgo
+  database driver. Those can only be built where the C toolchain and the target
+  OS's libraries are, so a `--cgo` app is tagged `build:cgo` and gets
+  `build-native` and `package-native` (this machine only, `CGO_ENABLED=1`, the
+  same `VERSION` stamp and `-trimpath`, the zip named as `package-all` names a
+  platform's) **instead of** `package`, `build-all` and `package-all`. It keeps
+  `build`, `test`, `lint` and `start` for local work.
+  - **A `native` job, only when such an app exists.** The generated pipeline
+    gains a job with one leg each on `windows-latest`, `macos-latest` and
+    `ubuntu-latest` (GitHub Actions: a matrix; Azure Pipelines: a matrix of
+    `vmImage`s, with the original job moved under `jobs:`). Each leg lints,
+    tests, builds and packages the native apps and publishes its zips as an
+    artifact. The single-agent verify excludes them (`--exclude=tag:build:cgo`),
+    because it cannot build them. A workspace with no native app keeps a
+    pipeline byte-identical to the one it had: the job is decided when the file is
+    written, since neither provider can skip a whole job on a file's existence.
+  - **Run `mnci upgrade` after adding one.** `add` does not rewrite the
+    pipeline files, so until then CI would verify the app on the one agent that
+    cannot build it. `mnci add` says so, and `mnci doctor` fails while a
+    pipeline lacks the job, and while no C compiler is installed on the machine
+    (it reads `CC`, then `gcc`, `clang`, `cc`).
+  - **Linux prerequisites are yours to finish.** The leg installs a C compiler
+    and `pkg-config`, which is all mnci can know. The `-dev` packages your app
+    links (`libgtk-3-dev` and `libayatana-appindicator3-dev` for a tray icon) go
+    on that one marked line in the pipeline. The macOS runner ships Xcode's tools,
+    and the Windows leg relies on the hosted image's MinGW-w64 `gcc`: the nightly
+    e2e builds a cgo app on `windows-latest`, and says so loudly if it finds no
+    compiler there rather than passing.
+  - **Architectures: one per OS, the runner's own.** `windows-latest` and
+    `ubuntu-latest` are amd64 and `macos-latest` is arm64, so a native app ships
+    `windows-amd64`, `linux-amd64` and `darwin-arm64`. `darwin-amd64`,
+    `linux-arm64` and `windows-arm64` are not built: they need an Intel macOS
+    runner, an arm Linux runner or a cross-compiler. The legs are fixed in the
+    generated pipeline today, so adding one means editing a file `mnci upgrade`
+    rewrites (russoedu/MoNecromanCi#269 is about giving that a safe place).
+  - **Releasing one.** With `--release` as well, each leg, on a push to main and
+    after the `ci` job has tagged, runs
+    `node tools/go-app-release.cjs assets --native`, which builds
+    `package-native` with `VERSION` set to the tag's version and uploads that
+    OS's zip to the same GitHub Release, so one release collects a zip from every
+    runner. Azure Pipelines has no GitHub Release to attach to and stops at the
+    artifact.
+- **Releasing a Go app is an opt-in: `mnci add go-app <name> --release`.** The
+  app is tagged `release:go`, which `release.projects` selects by tag (as it
+  does for a VS Code extension, so `mnci upgrade` keeps it). Without the flag
+  an app is never released.
+  - **Versioned from its git tag, with no manifest.** Nx's default
+    `versionActions` reads a `package.json`, and a project without one aborts
+    the release for the whole workspace, so the app carries a project-level
+    `release.version` pointing at `tools/go-app-release.cjs` and resolving its
+    current version from the tag (`<name>@<version>`). The same file is the
+    `versionActions`: it declares no manifest and writes nothing, which fits
+    because mnci releases never commit. `mnci upgrade` rewrites it, so local
+    edits do not survive.
+  - **The first release is `0.0.1`.** With no tag yet, the base is `0.0.0` and
+    Nx bumps it by its own rule for a `0.x` version. To start somewhere else,
+    push a `<name>@<version>` tag before the first release (`mvd-cli@0.9.0`),
+    or set `RELEASE_SPECIFIER` to an exact version.
+  - **It carries a publish target that publishes nothing.** `nx release` tags
+    first and publishes last, and a project matched for publishing without an
+    `nx-release-publish` target made it exit 1 _after_ the tag existed
+    (measured). Publishing a Go app is its tag.
+  - **The platform zips are attached to the GitHub Release, GitHub Actions only.**
+    After `nx release`, the generated workflow runs
+    `node tools/go-app-release.cjs assets`: for each app tagged by this run it
+    builds `package-all` with `VERSION` set to the new version, so the binary
+    reports it, and uploads `dist/drop/go-app-<name>-<goos>-<goarch>.zip` with
+    `gh release upload --clobber`, so a re-run is harmless. A run that released
+    nothing uploads nothing. Azure Pipelines (and `--ci both`'s Azure side)
+    creates the tag but has no GitHub Release to attach to, so it attaches
+    nothing.
+  - **A change to a library the app imports releases it too.** Nx counts the
+    commits that touch an app's dependencies, not only its own folder (measured:
+    a `fix:` touching only an imported `go-internal-lib` produced a patch
+    release of the app), which is right for a binary that links the library in.
+  - An app that needs a C toolchain is released from several runners instead:
+    see _Pure-Go apps are cross-compiled_ above. This step builds all six
+    platforms on one runner, which is what `CGO_ENABLED=0` allows.
 - **No publish-time dependency injection**, unlike Python's vendoring: `go
 build` links statically, so the binary in the drop already contains
   everything it needs.