docs: Deprecate temporalio meta package (#747)

- Fixes #727

Author: lorensr

CONTRIBUTING.md

@@ -1,8 +1,44 @@
 # How to Contribute
 
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+**Table of Contents**
+
+- [Maintenance](#maintenance)
+- [Getting started](#getting-started)
+  - [Contributor License Agreement (CLA)](#contributor-license-agreement-cla)
+  - [SDK Structure](#sdk-structure)
+  - [Environment setup](#environment-setup)
+- [Development](#development)
+  - [Testing](#testing)
+    - [Testing local changes to core](#testing-local-changes-to-core)
+      - [Integration tests](#integration-tests)
+    - [test-npm-init](#test-npm-init)
+  - [Style Guide](#style-guide)
+- [Publishing](#publishing)
+- [Updating the Java test server proto files](#updating-the-java-test-server-proto-files)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
 The TypeScript SDK (as well as the rest of the Temporal codebase) is open sourced under the MIT license.
 
-We welcome contributions from the community. To contribute please start by opening an [issue](https://github.com/temporalio/sdk-typescript/issues) and discussing the proposed change. Once a change has been agreed upon, development may start and be submitted via a [pull request](https://github.com/temporalio/sdk-typescript/pulls).
+We welcome contributions from the community. To contribute, please start by opening an [issue](https://github.com/temporalio/sdk-typescript/issues) and discussing the proposed change. Once a change has been agreed upon, development may start and be submitted via a [pull request](https://github.com/temporalio/sdk-typescript/pulls).
+
+## Maintenance
+
+The current maintainers are:
+
+- [Loren `lorensr`](https://github.com/lorensr)
+- [Roey `bergundy`](https://github.com/bergundy)
+
+If you'd like to join us, [email Loren](mailto:loren@temporal.io). We'd be happy to have help with any of these things:
+
+- Triaging issues
+- Reviewing PRs
+- Submitting PRs to close issues
+
+## Getting started
 
 ### Contributor License Agreement (CLA)
 
@@ -14,7 +50,7 @@ See [sdk-structure.md](./docs/sdk-structure.md)
 
 ### Environment setup
 
-- Install the system dependencies listed in [Getting started > Step 0: Prerequisites](https://docs.temporal.io/node/getting-started/#step-0-prerequisites)
+- Install Node 16 and [Temporal Server](https://github.com/temporalio/docker-compose#temporal-server-docker-compose-files)
 - Install the [Rust toolchain](https://rustup.rs/)
 - Clone the [sdk-typescript](https://github.com/temporalio/sdk-typescript) repo:
   ```sh
@@ -48,7 +84,7 @@ To update to the latest version of the Core SDK, run `git submodule update` foll
 
 > For cross compilation on MacOS follow [these instructions](https://github.com/temporalio/sdk-typescript/blob/main/docs/building.md) (only required for publishing packages).
 
-### Development Workflow
+## Development
 
 After your environment is set up, you can run these commands:
 
@@ -106,7 +142,7 @@ chore(samples): upgrade commander module
 
 The `scope` options are listed in [commitlint.config.js](https://github.com/temporalio/sdk-typescript/blob/main/commitlint.config.js).
 
-### Publishing
+## Publishing
 
 First, follow the instructions in [docs/building.md](docs/building.md).
 
@@ -165,7 +201,7 @@ npx lerna publish from-git # add `--dist-tag next` for pre-release versions
 rm $HOME/Downloads/packages-*
 ```
 
-### Updating the Java test server proto files
+## Updating the Java test server proto files
 
 [These files](https://github.com/temporalio/sdk-java/tree/master/temporal-test-server/src/main/proto) are taken from the `sdk-java` repo.
 

README.md

@@ -0,0 +1,32 @@
+# Temporal TypeScript SDK
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/temporalio">
+    <img src="https://img.shields.io/npm/v/temporalio.svg?style=for-the-badge" alt="NPM" />
+  </a>
+  <img src="https://img.shields.io/npm/l/temporalio?style=for-the-badge" alt="LICENSE" />
+</div>
+
+[Temporal](https://temporal.io) is a microservice orchestration platform that enables developers to build scalable applications without sacrificing productivity or reliability. Temporal Server executes units of application logic—Workflows—in a resilient manner that automatically handles intermittent failures and retries failed operations.
+
+Temporal is a mature technology—it's a fork of Uber's Cadence. Temporal is being developed by Temporal Technologies, a startup by the creators of Cadence.
+
+## Documentation
+
+The documentation is divided into several sections:
+
+- [TypeScript SDK docs](https://docs.temporal.io/typescript/introduction)
+- [TypeScript SDK API reference](https://typescript.temporal.io/)
+- [General Temporal docs](https://docs.temporal.io)
+
+We welcome help improving the docs. You can submit issues for things that aren't clear or send pull requests to this repository (for the API reference) or to the [`docs.temporal.io` repository](https://github.com/temporalio/documentation) (for everything else).
+
+## Contributors
+
+[/sdk-typescript/graphs/contributors](https://github.com/temporalio/sdk-typescript/graphs/contributors)
+
+Thank you to everyone who has contributed 😃🙌
+
+## Contributing
+
+We welcome issues and PRs! Read our [contributing guide](CONTRIBUTING.md) to learn about our development process, how to propose bugfixes and improvements, and how to build and test your changes to the SDK.

README.md

@@ -1,8 +1,56 @@
 {
+  "name": "typescript-sdk",
   "private": true,
+  "keywords": [
+    "temporal",
+    "workflow",
+    "isolate"
+  ],
+  "homepage": "https://github.com/temporalio/sdk-typescript#readme",
+  "bugs": {
+    "url": "https://github.com/temporalio/sdk-typescript/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/temporalio/sdk-typescript.git"
+  },
+  "license": "MIT",
+  "author": "Temporal Technologies Inc. <sdk@temporal.io>",
   "directories": {
     "doc": "docs"
   },
+  "files": [],
+  "scripts": {
+    "rebuild": "npm run clean && npm run build",
+    "build": "lerna run --stream build",
+    "build.watch": "lerna run --stream build.watch",
+    "test": "lerna run --stream test",
+    "test.watch": "lerna run --stream test.watch",
+    "ci-build-no-rust": "lerna run --ignore @temporalio/core-bridge --stream build",
+    "ci-stress": "node ./packages/test/lib/load/run-all-stress-ci-scenarios.js",
+    "ci-nightly": "node ./packages/test/lib/load/run-all-nightly-scenarios.js",
+    "wait-namespace": "node ./scripts/wait-on-temporal.mjs",
+    "lint": "eslint packages/*/src --ext .ts --no-error-on-unmatched-pattern && prettier --end-of-line auto --check .",
+    "lint.prune": "ts-prune -p tsconfig.prune.json --ignore \"used in module\" --skip \".d.ts\"",
+    "commitlint": "commitlint --from origin/main",
+    "format": "prettier --write .",
+    "clean": "node ./scripts/clean.mjs",
+    "docs": "lerna run --stream maybe-install-deps-and-build-docs"
+  },
+  "dependencies": {
+    "@temporalio/client": "file:packages/client",
+    "@temporalio/common": "file:packages/common",
+    "@temporalio/create": "file:packages/create-project",
+    "@temporalio/interceptors-opentelemetry": "file:packages/interceptors-opentelemetry",
+    "@temporalio/internal-non-workflow-common": "file:packages/internal-non-workflow-common",
+    "@temporalio/internal-workflow-common": "file:packages/internal-workflow-common",
+    "@temporalio/proto": "file:packages/proto",
+    "@temporalio/test": "file:packages/test",
+    "@temporalio/testing": "file:packages/testing",
+    "@temporalio/worker": "file:packages/worker",
+    "@temporalio/workflow": "file:packages/workflow",
+    "temporalio": "file:packages/meta"
+  },
   "devDependencies": {
     "@commitlint/cli": "^17.0.2",
     "@commitlint/config-conventional": "^17.0.2",
@@ -46,54 +94,6 @@
     "typescript": "^4.7.4",
     "uuid": "^8.3.2"
   },
-  "scripts": {
-    "rebuild": "npm run clean && npm run build",
-    "build": "lerna run --stream build",
-    "build.watch": "lerna run --stream build.watch",
-    "test": "lerna run --stream test",
-    "test.watch": "lerna run --stream test.watch",
-    "ci-build-no-rust": "lerna run --ignore @temporalio/core-bridge --stream build",
-    "ci-stress": "node ./packages/test/lib/load/run-all-stress-ci-scenarios.js",
-    "ci-nightly": "node ./packages/test/lib/load/run-all-nightly-scenarios.js",
-    "wait-namespace": "node ./scripts/wait-on-temporal.mjs",
-    "lint": "eslint packages/*/src --ext .ts --no-error-on-unmatched-pattern && prettier --end-of-line auto --check .",
-    "lint.prune": "ts-prune -p tsconfig.prune.json --ignore \"used in module\" --skip \".d.ts\"",
-    "commitlint": "commitlint --from origin/main",
-    "format": "prettier --write .",
-    "clean": "node ./scripts/clean.mjs",
-    "docs": "lerna run --stream maybe-install-deps-and-build-docs"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/temporalio/sdk-typescript.git"
-  },
-  "keywords": [
-    "temporal",
-    "workflow",
-    "isolate"
-  ],
-  "author": "Temporal Technologies Inc. <sdk@temporal.io>",
-  "license": "MIT",
-  "bugs": {
-    "url": "https://github.com/temporalio/sdk-typescript/issues"
-  },
-  "homepage": "https://github.com/temporalio/sdk-typescript#readme",
-  "files": [],
-  "name": "typescript-sdk",
-  "dependencies": {
-    "@temporalio/client": "file:packages/client",
-    "@temporalio/common": "file:packages/common",
-    "@temporalio/create": "file:packages/create-project",
-    "@temporalio/interceptors-opentelemetry": "file:packages/interceptors-opentelemetry",
-    "@temporalio/internal-non-workflow-common": "file:packages/internal-non-workflow-common",
-    "@temporalio/internal-workflow-common": "file:packages/internal-workflow-common",
-    "@temporalio/proto": "file:packages/proto",
-    "@temporalio/test": "file:packages/test",
-    "@temporalio/testing": "file:packages/testing",
-    "@temporalio/worker": "file:packages/worker",
-    "@temporalio/workflow": "file:packages/workflow",
-    "temporalio": "file:packages/meta"
-  },
   "engines": {
     "node": ">= 14.0.0",
     "npm": ">= 6.0.0",

package.json

@@ -0,0 +1,3 @@
+*.test.ts
+*.test.js
+test/

packages/create-project/.npmignore

@@ -7,7 +7,9 @@
   "type": "module",
   "scripts": {
     "build": "tsc --build",
-    "build.watch": "tsc --build --watch"
+    "build.watch": "tsc --build --watch",
+    "test": "ava ./lib/**/*.test.js",
+    "test.watch": "ava --watch ./lib/**/*.test.js"
   },
   "keywords": [
     "temporal",

packages/create-project/package.json

@@ -16,7 +16,7 @@ import {
 } from './helpers/samples.js';
 import { makeDir } from './helpers/make-dir.js';
 import { tryGitInit } from './helpers/git.js';
-import { install, updateNodeVersion, replaceTemporalVersion } from './helpers/install.js';
+import { install, updateNodeVersion, replaceSdkVersion } from './helpers/install.js';
 import { testIfThisComputerIsOnline } from './helpers/is-online.js';
 import { isWriteable } from './helpers/is-writeable.js';
 import { getErrorCode } from './helpers/get-error-code.js';
@@ -29,14 +29,14 @@ export async function createApp({
   appPath,
   useYarn,
   gitInit,
-  temporalioVersion,
+  sdkVersion,
   sample,
   samplePath,
 }: {
   appPath: string;
   useYarn: boolean;
   gitInit?: boolean;
-  temporalioVersion?: string;
+  sdkVersion?: string;
   sample: string;
   samplePath?: string;
 }): Promise<void> {
@@ -178,8 +178,8 @@ export async function createApp({
   console.log();
 
   await updateNodeVersion({ root });
-  if (temporalioVersion) {
-    await replaceTemporalVersion({ root, useYarn, temporalioVersion });
+  if (sdkVersion) {
+    await replaceSdkVersion({ root, useYarn, sdkVersion });
   }
 
   await install({ root, useYarn });

packages/create-project/src/create-project.ts

@@ -0,0 +1,46 @@
+import test from 'ava';
+import dedent from 'dedent';
+import { readFile, rm, writeFile } from 'fs/promises';
+import os from 'os';
+import path from 'path';
+import { v4 as uuid } from 'uuid';
+import { replaceSdkVersion } from './install.js';
+import { makeDir } from './make-dir.js';
+
+test('replaceSdkVersion according to configured level', async (t) => {
+  console.log('debug windows');
+  // console.log('import.meta.url', import.meta.url);
+  // console.log('URL', new URL('../../test', import.meta.url));
+  const tempDir = path.join(os.tmpdir(), uuid());
+  console.log('tempDir:', tempDir);
+  await makeDir(tempDir);
+
+  // const { pathname: tempDir } = new URL('../../test', import.meta.url);
+  const packageJson = path.join(tempDir, 'package.json');
+  console.log('packageJson', packageJson);
+  await writeFile(
+    packageJson,
+    dedent`
+  {
+    "name": "test-create-project",
+    "version": "0.1.0",
+    "private": true,
+    "dependencies": {
+      "@temporalio/activity": "^1.0.0",
+      "@temporalio/client": "^1.0.0",
+      "@temporalio/worker": "^1.0.0",
+      "@temporalio/workflow": "^1.0.0",
+      "nanoid": "3.x"
+    }
+  }
+  `
+  );
+
+  await replaceSdkVersion({ root: tempDir, sdkVersion: 'foo' });
+  const replaced = JSON.parse(await readFile(packageJson, 'utf8'));
+  t.is(replaced.dependencies['@temporalio/activity'], 'foo');
+  t.is(replaced.dependencies['@temporalio/client'], 'foo');
+  t.is(replaced.dependencies.nanoid, '3.x');
+
+  await rm(tempDir, { recursive: true });
+});

packages/create-project/src/helpers/install.test.ts

@@ -11,7 +11,7 @@ interface InstallArgs {
    * Indicate whether to install packages using Yarn.
    */
   useYarn?: boolean;
-  temporalioVersion?: string;
+  sdkVersion?: string;
 }
 
 /**
@@ -53,10 +53,14 @@ export async function updateNodeVersion({ root }: InstallArgs): Promise<void> {
   }
 }
 
-export async function replaceTemporalVersion({ root, temporalioVersion }: InstallArgs): Promise<void> {
+export async function replaceSdkVersion({ root, sdkVersion }: InstallArgs): Promise<void> {
   const fileName = `${root}/package.json`;
 
   const packageJson = JSON.parse(await readFile(fileName, 'utf8'));
-  packageJson.dependencies.temporalio = temporalioVersion;
+  for (const packageName in packageJson.dependencies) {
+    if (packageName.startsWith('@temporalio/')) {
+      packageJson.dependencies[packageName] = sdkVersion;
+    }
+  }
   await writeFile(fileName, JSON.stringify(packageJson));
 }

packages/create-project/src/helpers/install.ts

@@ -58,9 +58,9 @@ const program = new Command(packageJson.name)
 `
   )
   .option(
-    '--temporalio-version <version>',
+    '--sdk-version <version>',
     dedent`
-  Specify which version of the temporalio npm package to use
+  Specify which version of the @temporalio/* npm packages to use
 `
   )
   .allowUnknownOption()
@@ -72,7 +72,7 @@ interface Options {
   listSamples?: boolean;
   sample?: string;
   samplePath?: string;
-  temporalioVersion?: string;
+  sdkVersion?: string;
 }
 
 let opts: Options;
@@ -170,7 +170,7 @@ async function start(): Promise<void> {
     appPath: resolvedProjectPath,
     useYarn: !!opts.useYarn,
     gitInit: opts.gitInit,
-    temporalioVersion: opts.temporalioVersion,
+    sdkVersion: opts.sdkVersion,
     sample: sample.trim(),
     samplePath: typeof opts.samplePath === 'string' ? opts.samplePath.trim() : undefined,
   });

packages/create-project/src/index.ts

@@ -4,7 +4,6 @@
     "outDir": "./lib",
     "rootDir": "./src",
     "resolveJsonModule": true,
-    "lib": ["dom"],
     "module": "esnext"
   },
   "include": ["./src/**/*.ts"]