Skip to content

Commit 03b9c4d

Browse files
authored
docs: contrib docs refresh (#1124)
## 🧰 Changes updating our contrib docs to reflect our new release process and guidance for writing commands in an `oclif`-friendly way.
1 parent 650c50a commit 03b9c4d

File tree

2 files changed

+59
-2
lines changed

2 files changed

+59
-2
lines changed

CONTRIBUTING.md

Lines changed: 28 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -87,15 +87,42 @@ act -j simple
8787

8888
### Usage of `console`
8989

90+
<details>
91+
92+
<summary>⚠️ <b>Outdated guidance</b> (you'll notice we still use this paradigm in a few commands, but don't use this guidance for new commands!)</summary>
93+
9094
As you'll learn in our commands logic (see [`bin/run.js`](bin/run.js) and the [`src/commands`](src/commands) directory), we wrap our command outputs in resolved/rejected [`Promise` objects](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) and use [`bin/run.js`](bin/run.js) file to log the results to the console and return the correct status code. This is so we can write more resilient tests, ensure that the proper exit codes are being returned, and make debugging easier.
9195

9296
When writing command logic, avoid using `console` statements (and correspondingly, avoid mocking `console` statements in tests) when possible.
9397

98+
</details>
99+
100+
<details open>
101+
102+
<summary><b>Updated Guidance</b></summary>
103+
104+
When writing command logic, avoid using `console` statements. As modeled by [the `openapi upload` command](./src/commands/openapi/upload.ts), we use [`oclif`'s command methods](https://oclif.io/docs/commands/#command-methods) for writing to the console. This allows us to seamlessly integrate [`oclif`'s support for JSON output](https://oclif.io/docs/json/).
105+
106+
[The `@oclif/test` helper](https://github.com/oclif/test) automatically mocks any writes to `stdout` or `stderr`. This is great for properly asserting `rdme` outputs, but can be a bit confusing to develop with at first if you rely on `console.log` as part of your debugging since those statements won't get written to the console the way you'd expect.
107+
108+
If you rely on `console.log` (or something similar) during development, you can do the following to view your output:
109+
110+
1. Make sure you're using the `runCommand` helper in [this file](./__tests__/helpers/oclif.ts) and **not** `runCommandAndReturnResult`. See [this test file](./__tests__/commands/openapi/upload.test.ts) for an example.
111+
112+
2. Add a statement like this in your test:
113+
114+
```js
115+
const result = await run(['--key', key]); // add any other flags here as needed
116+
expect(result).toStrictEqual({}); // this will fail, but it will output the entire result object, which you can inspect
117+
```
118+
119+
</details>
120+
94121
<img align="right" width="25%" style="margin-bottom: 2em" src="https://owlbertsio-resized.s3.amazonaws.com/Blocks.psd.png">
95122

96123
### Making `fetch` requests
97124

98-
`fetch` requests are very common in this codebase. When sending `fetch` requests to the ReadMe API (i.e., [dash.readme.com](https://dash.readme.com)), make sure to use the `fetch` wrapper function located in [`src/lib/readmeAPIFetch.ts`](src/lib/readmeAPIFetch.ts). We have an ESLint rule to flag this.
125+
`fetch` requests are very common in this codebase. When sending `fetch` requests to the ReadMe API (i.e., [dash.readme.com](https://dash.readme.com) or [api.readme.com](https://api.readme.com)), make sure to use the `fetch` wrapper function located in [`src/lib/readmeAPIFetch.ts`](src/lib/readmeAPIFetch.ts).
99126

100127
In that wrapper function, we set several important request headers and configure the proxy, if the user added one via `HTTPS_PROXY`.
101128

MAINTAINERS.md

Lines changed: 31 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ When code is merged into the `main` or `next` branches, a release workflow (powe
1313

1414
- All commit messages since the last release are analyzed to determine whether or not the new changes warrant a new release (i.e., if the changes are features or fixes as opposed to smaller housekeeping changes) 🧐
1515
- Based on the changes, the version is bumped in [`package.json`](./package.json) 🥊 For example, say the current version is `8.5.1` and the commit history includes a new feature. This would result in a minor semver bump, which would produce the following tags:
16-
- A release tag like `v8.6.0` if on the `main` branch
16+
- A release tag like `v8.6.0` if on the `main` or `v9` branches
1717
- A prerelease tag like `v8.6.0-next.1` if on the `next` branch
1818
- A few other files, such as [`CHANGELOG.md`](./CHANGELOG.md), [the command reference pages](./documentation/commands), and our GitHub Actions bundle files, are updated based on this code 🪵
1919
- A build commit (like [this](https://github.com/readmeio/rdme/commit/533a2db50b39c3b6130b3af07bebaed38218db4c)) is created with all of the updated files (e.g., `package.json`, `CHANGELOG.md`, etc.) 🆕
@@ -22,9 +22,39 @@ When code is merged into the `main` or `next` branches, a release workflow (powe
2222
- The new version is published to the `npm` registry 🚀 The package [distribution tag](https://docs.npmjs.com/adding-dist-tags-to-packages) will depend on which branch is being pushed to:
2323
- If on the `main` branch, a version is pushed on the main distribution tag (a.k.a. `latest`, which is used when someone runs `npm i rdme` with no other specifiers).
2424
- If on the `next` branch, the prerelease distribution tag (a.k.a. [`next`](https://www.npmjs.com/package/rdme/v/next)) is updated.
25+
- If on the `v9` branch, there is no distribution tag, but any minor/patch changes on this branch are automatically released to the 9.x release channel.
2526
- A [GitHub release is created](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository#creating-a-release) for the tag 🐙
2627
- If on the `main` branch, the new changes are backported to the `next` branch so both branches remain in sync 🔄
2728

29+
### Maintaining two major release channels
30+
31+
We maintain two different release channels:
32+
33+
- one for `v9` (so we can have a release that supports all functionality pre-ReadMe Refactored, more in [our migration guide](./documentation/migration-guide.md))
34+
- one for the latest release (`v10`, as of this writing — `v10` and onward are for customers on ReadMe Refactored only)
35+
36+
All new feature development should be on the `next` branch. If the feature does not interact with the ReadMe API in anyway (e.g., a docs change, an OpenAPI utility command), we can backport the change to the `v9` branch.
37+
38+
Here's the recommended approach:
39+
40+
1. Once the pull request has been merged into `next`, grab the merge commit SHA.
41+
2. Check out the `v9` branch, create a new branch based off of that branch, and cherry-pick the aformentioned commit SHA:
42+
43+
```sh
44+
git checkout v9
45+
git checkout -b my-v9-backport-branch
46+
git cherry-pick SHA
47+
```
48+
49+
3. Create a new pull request and set the base branch to `v9`.
50+
4. Once CI passes and you get the necessary approvals, merge that pull request in.
51+
5. The final step ensures that everything in the `next` branch is a superset of everything in the `v9` branch. To do this, checkout the `next` branch and merge `v9` into it.
52+
53+
```sh
54+
git checkout next
55+
git merge v9
56+
```
57+
2858
## One more thing ☝️
2959

3060
> [!NOTE]

0 commit comments

Comments
 (0)