Skip to content

Commit 9bcea41

Browse files
frankfarzanfrankfarzan
authored
Expand release and dev instructions in CONTRIBUTING doc. (#338)
* Expand release and dev instructions in CONTRIBUTING doc. * typo * Update NPM package README * Add gen-docs instructions * typo * Update CONTRIBUTING.md
1 parent fb39884 commit 9bcea41

File tree

3 files changed

+123
-15
lines changed

3 files changed

+123
-15
lines changed

‎CONTRIBUTING.md‎

Lines changed: 119 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -29,34 +29,142 @@ This project follows
2929

3030
## Additional Notes
3131

32-
The following sections give additional tips and best practices when submitting changes.
32+
The following sections give additional tips and best practices when submitting
33+
changes.
3334

3435
### Adding an NPM dependency
3536

36-
When adding a new dependency (especially in `dependency`), you
37-
need to perform due diligence.
37+
When adding a new dependency (especially in `dependency`), you need to perform
38+
due diligence.
3839

39-
1. Look at the transitive dependencies of the package:
40-
<http://npm.broofa.com/>
40+
1. Look at the transitive dependencies of the package: <http://npm.broofa.com/>
4141
1. Does the package depend on a lot of dependencies?
4242
1. What's size of the package? Will it cause binary bloat?
43-
1. Is the package and its transitive dependencies high quality, trust-worthy, and well-maintained projects?
43+
1. Is the package and its transitive dependencies high quality, trust-worthy,
44+
and well-maintained projects?
4445
1. What version of the package should we depend on?
45-
1. Are the licenses for the package and its transitive dependencies green? See next section for checking licenses.
46+
1. Are the licenses for the package and its transitive dependencies green? See
47+
next section for checking licenses.
4648

4749
### Checking NPM dependencies licenses
4850

49-
When adding any new dependencies or updating existing dependencies
50-
we need to check licenses:
51+
When adding any new dependencies or updating existing dependencies we need to
52+
check licenses:
5153

5254
```console
5355
npm run lint-license
5456
```
5557

58+
### Local development
59+
60+
When developing locally, you often want to use the the local modified version of
61+
NPM packages (`kpt-functions` and `create-kpt-functions`) used by function
62+
packages (e.g. `demo-functions`). You can do the following:
63+
64+
```console
65+
cd ts/demo-functions
66+
# May need to run as `sudo` depending on how you intalled NPM
67+
npm link ../kpt-functions
68+
npm run build
69+
```
70+
5671
### Releases
5772

58-
Release workflows are triggered by creating Releases in the GitHub UI with a tag following the
59-
format:
73+
This repo contains two NPM packages that are published to the NPM registry.
74+
75+
#### `kpt-functions`
76+
77+
This is the library used by all TS SDK functions.
78+
79+
##### NPM registry
80+
81+
https://www.npmjs.com/package/kpt-functions
82+
83+
##### Release candidates
84+
85+
Before releasing major changes, or whenever you want additinal verification, first create a `rc` release:
86+
87+
1. In pristine git repo, run:
88+
89+
```console
90+
./scripts/version-kpt-functions-sdk.sh 0.14.0-rc.1
91+
```
92+
93+
This automatically creates a Git commit in your local repo.
94+
95+
2. Create a PR and commit.
96+
[Example](https://github.com/GoogleContainerTools/kpt-functions-sdk/commit/d944c818f564a183c3cb092b282f5e83f770b18a)
97+
3. Create a release in GitHub which pushes the package to NPM registry. But,
98+
because this is marked as an `rc` release, it will not be pulled by default
99+
form the NPM registry.
100+
[Example](https://github.com/GoogleContainerTools/kpt-functions-sdk/releases/tag/release-kpt-functions-v0.14.0)
101+
102+
4. In a separate PR, update the dependant packages
103+
104+
```console
105+
./scripts/version-kpt-functions-sdk-deps.sh 0.14.0-rc.1
106+
```
107+
108+
5. Create a PR and commit.
109+
[Example](https://github.com/GoogleContainerTools/kpt-functions-sdk/commit/e1126e5a23fac3d3a79706ceaca924a9b4d31a18)
110+
This PR ensures that dependant packages are tested against the `rc` release.
111+
112+
6. Once you are confident that the `rc` release is good, you can then repeat
113+
the process with out the `rc` suffix:
114+
```console
115+
./scripts/version-kpt-functions-sdk.sh 0.14.0
116+
```
117+
7. In a separate PR, update the SDK API docs which are
118+
[hosted here](https://googlecontainertools.github.io/kpt-functions-sdk/api/)
119+
120+
```console
121+
cd ts/kpt-functions
122+
npm run gen-docs
123+
```
124+
125+
**NOTE**: You want to merge this PR. Do not squash or rebase this PR. The
126+
API docs refer to the commit SHA of the your local repo, so you want to make
127+
sure that commit will exist on the master branch after merging it.
128+
129+
#### `create-kpt-functions`
130+
131+
This is the CLI for TS SDK.
132+
133+
##### NPM registry
134+
135+
https://www.npmjs.com/package/create-kpt-functions
136+
137+
##### Release candidates
138+
139+
Before releasing major changes, you first want to create a `rc` release.
140+
141+
1. In pristine git repo, make changes following this
142+
[Example](https://github.com/GoogleContainerTools/kpt-functions-sdk/pull/102/files)
143+
but specifying an rc suffix (e.g. `0.16.0-rc.1`)
144+
2. Create a PR and commit.
145+
3. Create a release in GitHub which pushes the package to NPM registry. But,
146+
because this is marked as an `rc` release, it will not be pulled by default
147+
form the NPM registry.
148+
[Example](https://github.com/GoogleContainerTools/kpt-functions-sdk/releases/tag/release-create-kpt-functions-v0.16.0)
149+
4. In a separate PR, update the dependant packages following this
150+
[Example](https://github.com/GoogleContainerTools/kpt-functions-sdk/pull/103/files)
151+
(Ignore workflow change)
152+
153+
5. Create a PR and commit. This PR ensures that dependant packages are tested
154+
against the `rc` release.
155+
156+
6. Once you are confident that the `rc` release is good, you can then repeat
157+
the process with out the `rc` suffix (e.g. `0.16.0`).
158+
7. You can test the CLI for creating a new package using this script:
159+
```console
160+
./scripts/init-package.sh
161+
```
162+
This will update the the `init-package` in the repo.
163+
164+
#### GitHub Release Workflows
165+
166+
Release workflows are triggered by creating Releases in the GitHub UI with a tag
167+
following the format:
60168

61169
`release-<workflow>-vX.Y.Z`
62170

‎ts/create-kpt-functions/README.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
1-
# KPT Functions SDK
1+
# kpt Functions SDK CLI
22

33
Documentation:
44

5-
https://googlecontainertools.github.io/kpt-functions-sdk/
5+
https://kpt.dev/book/05-developing-functions/03-developing-in-Typescript

‎ts/kpt-functions/README.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
1-
# KPT Functions SDK
1+
# kpt Functions SDK Library
22

33
Documentation:
44

5-
https://googlecontainertools.github.io/kpt-functions-sdk/
5+
https://kpt.dev/book/05-developing-functions/03-developing-in-Typescript

0 commit comments

Comments
 (0)