Skip to content

Commit 2e5b1dc

Browse files
slinkydeveloperslinkydeveloper
authored
Improve a bit the readmes, to make them look nicer. (#571)
1 parent 0825d05 commit 2e5b1dc

File tree

8 files changed

+91
-114
lines changed

8 files changed

+91
-114
lines changed

‎DEVELOPMENT.md

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
# Development guidelines
2+
3+
## Prerequisites
4+
- [NodeJS (and npm)](https://nodejs.org) installed
5+
6+
## Building the SDK
7+
8+
Install the dependencies and transpile the TypeScript code:
9+
```shell
10+
npm install
11+
npm run build
12+
```
13+
14+
If everything goes well, the artifact would be created at `dist/`.
15+
16+
## Testing Changes
17+
18+
Run the tests via
19+
```shell
20+
npm run test
21+
```
22+
23+
Run the formatter and linter via
24+
```shell
25+
npm run format
26+
npm run lint
27+
```
28+
29+
Launch a sample program (requires no build)
30+
```shell
31+
npm run -w packages/restate-sdk-examples greeter
32+
npm run -w packages/restate-sdk-examples object
33+
npm run -w packages/restate-sdk-examples workflow
34+
```
35+
36+
## Testing end-to-end with Restate Server
37+
38+
E2E tests run automatically with
39+
40+
## Re-generating the discovery manifest
41+
42+
```shell
43+
npx --package=json-schema-to-typescript json2ts endpoint_manifest_schema.json packages/restate-sdk/src/types/discovery.ts
44+
```
45+
46+
## Releasing the package
47+
48+
### Releasing via release-it
49+
50+
Releasing a new npm package from this repo requires:
51+
52+
* [SSH access configured for Github](https://docs.github.com/en/authentication/connecting-to-github-with-ssh) in order to push commits and tags to GitHub
53+
* A GitHub personal access token with access to https://github.com/restatedev/sdk-typescript in your environment as `GITHUB_TOKEN` in order to create a Github release
54+
55+
```bash
56+
release-it
57+
```
58+
59+
The actual `npm publish` is run by GitHub actions once a GitHub release is created.
60+
61+
### Releasing manually
62+
63+
1. Bump the version field in package.json to `X.Y.Z`
64+
2. Create and push a tag of the form `vX.Y.Z` to the upstream repository
65+
3. [Create a new GitHub release](https://github.com/restatedev/sdk-typescript/releases)
66+
67+
Creating the GitHub release will trigger `npm publish` via GitHub actions.
68+
69+
After having created a new SDK release, you need to:
70+
71+
1. [Update and release the tour of Restate](https://github.com/restatedev/tour-of-restate-typescript#upgrading-typescript-sdk)
72+
2. [Update the Typescript SDK and Tour version in the documentation and release it](https://github.com/restatedev/documentation#upgrading-typescript-sdk-version)
73+
3. [Update and release the Node template generator](https://github.com/restatedev/node-template-generator#upgrading-typescript-sdk)
74+
4. [Update the examples](https://github.com/restatedev/examples#upgrading-the-sdk-dependency-for-restate-developers)

‎README.md

Lines changed: 4 additions & 72 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
[![Documentation](https://img.shields.io/badge/doc-reference-blue)](https://docs.restate.dev)
22
[![Examples](https://img.shields.io/badge/view-examples-blue)](https://github.com/restatedev/examples)
3+
[![NPM Version](https://img.shields.io/npm/v/%40restatedev%2Frestate-sdk)](https://www.npmjs.com/package/@restatedev/restate-sdk)
34
[![Discord](https://img.shields.io/discord/1128210118216007792?logo=discord)](https://discord.gg/skW3AZ6uGd)
45
[![Twitter](https://img.shields.io/twitter/follow/restatedev.svg?style=social&label=Follow)](https://twitter.com/intent/follow?screen_name=restatedev)
56

@@ -51,6 +52,8 @@ For brand-new projects, we recommend using the [Restate Node Template](https://g
5152
npx -y @restatedev/create-app@latest
5253
```
5354

55+
Check the [Quickstart](https://docs.restate.dev/get_started/quickstart) for more info.
56+
5457
## Versions
5558

5659
This library follows [Semantic Versioning](https://semver.org/).
@@ -74,75 +77,4 @@ We’re excited if you join the Restate community and start contributing!
7477
Whether it is feature requests, bug reports, ideas & feedback or PRs, we appreciate any and all contributions.
7578
We know that your time is precious and, therefore, deeply value any effort to contribute!
7679

77-
### Building the SDK
78-
79-
#### Prerequisites
80-
- [NodeJS (and npm)](https://nodejs.org) installed
81-
82-
Install the dependencies and transpile the TypeScript code:
83-
```shell
84-
npm install
85-
npm run build
86-
```
87-
88-
If everything goes well, the artifact would be created at `dist/`.
89-
90-
### Testing Changes
91-
92-
Run the tests via
93-
```shell
94-
npm run test
95-
```
96-
97-
Run the formatter and linter via
98-
```shell
99-
npm run format
100-
npm run lint
101-
```
102-
103-
Launch a sample program (requires no build)
104-
```shell
105-
npm run -w packages/restate-sdk-examples greeter
106-
npm run -w packages/restate-sdk-examples object
107-
npm run -w packages/restate-sdk-examples workflow
108-
```
109-
110-
### Testing end-to-end with Restate Server
111-
112-
See https://github.com/restatedev/e2e/ for more details.
113-
114-
### Re-generating the discovery manifest
115-
116-
```shell
117-
npx --package=json-schema-to-typescript json2ts endpoint_manifest_schema.json packages/restate-sdk/src/types/discovery.ts
118-
```
119-
120-
## Releasing the package
121-
122-
### Releasing via release-it
123-
124-
Releasing a new npm package from this repo requires:
125-
126-
* [SSH access configured for Github](https://docs.github.com/en/authentication/connecting-to-github-with-ssh) in order to push commits and tags to GitHub
127-
* A GitHub personal access token with access to https://github.com/restatedev/sdk-typescript in your environment as `GITHUB_TOKEN` in order to create a Github release
128-
129-
```bash
130-
release-it
131-
```
132-
133-
The actual `npm publish` is run by GitHub actions once a GitHub release is created.
134-
135-
### Releasing manually
136-
137-
1. Bump the version field in package.json to `X.Y.Z`
138-
2. Create and push a tag of the form `vX.Y.Z` to the upstream repository
139-
3. [Create a new GitHub release](https://github.com/restatedev/sdk-typescript/releases)
140-
141-
Creating the GitHub release will trigger `npm publish` via GitHub actions.
142-
143-
After having created a new SDK release, you need to:
144-
145-
1. [Update and release the tour of Restate](https://github.com/restatedev/tour-of-restate-typescript#upgrading-typescript-sdk)
146-
2. [Update the Typescript SDK and Tour version in the documentation and release it](https://github.com/restatedev/documentation#upgrading-typescript-sdk-version)
147-
3. [Update and release the Node template generator](https://github.com/restatedev/node-template-generator#upgrading-typescript-sdk)
148-
4. [Update the examples](https://github.com/restatedev/examples#upgrading-the-sdk-dependency-for-restate-developers)
80+
For more info about developing the SDK, check the [development guide](DEVELOPMENT.md).

‎packages/restate-sdk-clients/README.md

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
[![Documentation](https://img.shields.io/badge/doc-reference-blue)](https://docs.restate.dev)
22
[![Examples](https://img.shields.io/badge/view-examples-blue)](https://github.com/restatedev/examples)
3+
[![NPM Version](https://img.shields.io/npm/v/%40restatedev%2Frestate-sdk-clients)](https://www.npmjs.com/package/@restatedev/restate-sdk-clients)
34
[![Discord](https://img.shields.io/discord/1128210118216007792?logo=discord)](https://discord.gg/skW3AZ6uGd)
45
[![Twitter](https://img.shields.io/twitter/follow/restatedev.svg?style=social&label=Follow)](https://twitter.com/intent/follow?screen_name=restatedev)
56

@@ -36,7 +37,7 @@ To build Restate services using Typescript, checkout the SDK main package https:
3637
* 🙋 [Create a GitHub issue](https://github.com/restatedev/sdk-typescript/issues) for requesting a new feature or reporting a problem.
3738
* 🏠 [Visit our GitHub org](https://github.com/restatedev) for exploring other repositories.
3839

39-
## Using the SDK
40+
## Using the Restate client
4041

4142
To use this client, add the dependency to your project:
4243

‎packages/restate-sdk-core/README.md

Lines changed: 2 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
[![Documentation](https://img.shields.io/badge/doc-reference-blue)](https://docs.restate.dev)
22
[![Examples](https://img.shields.io/badge/view-examples-blue)](https://github.com/restatedev/examples)
3+
[![NPM Version](https://img.shields.io/npm/v/%40restatedev%2Frestate-sdk-core)](https://www.npmjs.com/package/@restatedev/restate-sdk-core)
34
[![Discord](https://img.shields.io/discord/1128210118216007792?logo=discord)](https://discord.gg/skW3AZ6uGd)
45
[![Twitter](https://img.shields.io/twitter/follow/restatedev.svg?style=social&label=Follow)](https://twitter.com/intent/follow?screen_name=restatedev)
56

@@ -9,41 +10,4 @@
910

1011
This package contains the core types used in the several SDK modules.
1112

12-
For the SDK main package, checkout https://www.npmjs.com/package/@restatedev/restate-sdk.
13-
14-
## Community
15-
16-
* 🤗️ [Join our online community](https://discord.gg/skW3AZ6uGd) for help, sharing feedback and talking to the community.
17-
* 📖 [Check out our documentation](https://docs.restate.dev) to get quickly started!
18-
* 📣 [Follow us on Twitter](https://twitter.com/restatedev) for staying up to date.
19-
* 🙋 [Create a GitHub issue](https://github.com/restatedev/sdk-typescript/issues) for requesting a new feature or reporting a problem.
20-
* 🏠 [Visit our GitHub org](https://github.com/restatedev) for exploring other repositories.
21-
22-
## Using the SDK
23-
24-
To use this SDK, add the dependency to your project:
25-
```shell
26-
npm install @restatedev/restate-sdk
27-
```
28-
29-
For brand-new projects, we recommend using the [Restate Node Template](https://github.com/restatedev/node-template-generator):
30-
```shell
31-
npx -y @restatedev/create-app@latest
32-
```
33-
34-
## Versions
35-
36-
This library follows [Semantic Versioning](https://semver.org/).
37-
38-
The compatibility with Restate is described in the following table:
39-
40-
| Restate Server\sdk-typescript | 1.0 - 1.3 | 1.4 | 1.5 - 1.6 | 1.7 |
41-
|-------------------------------|------------------|-----|-----------|------------------|
42-
| 1.0 | ✅ | ❌ | ❌ | ❌ |
43-
| 1.1 | ✅ <sup>(1)</sup> | ✅ | ❌ | ❌ |
44-
| 1.2 | ✅ | ✅ | ❌ | ❌ |
45-
| 1.3 | ✅ | ✅ | ✅ | ✅ <sup>(2)</sup> |
46-
| 1.4 | ✅ | ✅ | ✅ | ✅ |
47-
48-
<sup>(1)</sup> **Only** when upgrading from 1.0 to 1.1 you MUST rediscover all the existing deployments using `restate dp register <address> --force`. You don't need to update the SDK, nor change the code.
49-
<sup>(2)</sup> **Note** the new `options` in service/object/workflow constructors, together with some of the new options in the `handler`s too, work only from Restate 1.4 onward. Check the in-code documentation for more details.
13+
For the SDK main package, checkout [`@restatedev/restate-sdk`](../restate-sdk).

‎packages/restate-sdk-testcontainers/README.md

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
[![Documentation](https://img.shields.io/badge/doc-reference-blue)](https://docs.restate.dev)
22
[![Examples](https://img.shields.io/badge/view-examples-blue)](https://github.com/restatedev/examples)
3+
[![NPM Version](https://img.shields.io/npm/v/%40restatedev%2Frestate-sdk-testcontainers)](https://www.npmjs.com/package/@restatedev/restate-sdk-testcontainers)
34
[![Discord](https://img.shields.io/discord/1128210118216007792?logo=discord)](https://discord.gg/skW3AZ6uGd)
45
[![Twitter](https://img.shields.io/twitter/follow/restatedev.svg?style=social&label=Follow)](https://twitter.com/intent/follow?screen_name=restatedev)
56

@@ -10,7 +11,7 @@
1011
This package contains utilities to test Restate SDK services against a Restate server container.
1112
A usage example can be found in [`restate-sdk-examples/test/testcontainers.test.ts`](https://github.com/restatedev/sdk-typescript/blob/main/packages/restate-sdk-examples/test/testcontainers.test.ts)
1213

13-
For the SDK main package, checkout https://www.npmjs.com/package/@restatedev/restate-sdk.
14+
For the SDK main package, checkout [`@restatedev/restate-sdk`](../restate-sdk).
1415

1516
## Community
1617

‎packages/restate-sdk-zod/README.md

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
[![Documentation](https://img.shields.io/badge/doc-reference-blue)](https://docs.restate.dev)
22
[![Examples](https://img.shields.io/badge/view-examples-blue)](https://github.com/restatedev/examples)
3+
[![NPM Version](https://img.shields.io/npm/v/%40restatedev%2Frestate-sdk-zod)](https://www.npmjs.com/package/@restatedev/restate-sdk-zod)
34
[![Discord](https://img.shields.io/discord/1128210118216007792?logo=discord)](https://discord.gg/skW3AZ6uGd)
45
[![Twitter](https://img.shields.io/twitter/follow/restatedev.svg?style=social&label=Follow)](https://twitter.com/intent/follow?screen_name=restatedev)
56

@@ -38,7 +39,7 @@ export type Greeter = typeof greeter;
3839
restate.endpoint().bind(greeter).listen();
3940
```
4041

41-
For the SDK main package, checkout https://www.npmjs.com/package/@restatedev/restate-sdk.
42+
For the SDK main package, checkout [`@restatedev/restate-sdk`](../restate-sdk).
4243

4344
## Community
4445

‎packages/restate-sdk/README.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
[![Documentation](https://img.shields.io/badge/doc-reference-blue)](https://docs.restate.dev)
22
[![Examples](https://img.shields.io/badge/view-examples-blue)](https://github.com/restatedev/examples)
3+
[![NPM Version](https://img.shields.io/npm/v/%40restatedev%2Frestate-sdk)](https://www.npmjs.com/package/@restatedev/restate-sdk)
34
[![Discord](https://img.shields.io/discord/1128210118216007792?logo=discord)](https://discord.gg/skW3AZ6uGd)
45
[![Twitter](https://img.shields.io/twitter/follow/restatedev.svg?style=social&label=Follow)](https://twitter.com/intent/follow?screen_name=restatedev)
56

@@ -47,6 +48,8 @@ For brand-new projects, we recommend using the [Restate Node Template](https://g
4748
npx -y @restatedev/create-app@latest
4849
```
4950

51+
Check the [Quickstart](https://docs.restate.dev/get_started/quickstart) for more info.
52+
5053
## Versions
5154

5255
This library follows [Semantic Versioning](https://semver.org/).

‎typedoc.json

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
{
22
"$schema": "https://typedoc.org/schema.json",
3+
"name": "Restate Typescript SDK",
34
"entryPoints": [
45
"packages/restate-sdk-core",
56
"packages/restate-sdk",
@@ -12,7 +13,7 @@
1213
"entryPoints": [
1314
"src/public_api.ts"
1415
],
15-
"tsconfig": "tsconfig.json"
16+
"tsconfig": "tsconfig.json",
1617
},
1718
"out": "docs-out"
1819
}

0 commit comments

Comments
 (0)