Skip to content

Commit

Permalink
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: contrib docs refresh
Browse files Browse the repository at this point in the history
kanadgupta committed Dec 17, 2024
1 parent 109dfcb commit 7e793b9
Showing 2 changed files with 59 additions and 2 deletions.
29 changes: 28 additions & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -87,15 +87,42 @@ act -j simple

### Usage of `console`

<details>

<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>

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.

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

</details>

<details open>

<summary><b>Updated Guidance</b></summary>

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 easily add in [`oclif`'s support for JSON output](https://oclif.io/docs/json/).

[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.

If you rely on `console.log` (or something similar) during development, you can do the following to view your output:

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.

2. Add a statement like this in your test:

```js
const result = await run(['--key', key]); // add any other flags here as needed
expect(result).toStrictEqual({}); // this will fail, but it will output the entire result object, which you can inspect
```

</details>

<img align="right" width="25%" style="margin-bottom: 2em" src="https://owlbertsio-resized.s3.amazonaws.com/Blocks.psd.png">

### Making `fetch` requests

`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.
`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).

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

32 changes: 31 additions & 1 deletion MAINTAINERS.md
Original file line number Diff line number Diff line change
@@ -13,7 +13,7 @@ When code is merged into the `main` or `next` branches, a release workflow (powe

- 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) 🧐
- 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:
- A release tag like `v8.6.0` if on the `main` branch
- A release tag like `v8.6.0` if on the `main` or `v9` branches
- A prerelease tag like `v8.6.0-next.1` if on the `next` branch
- 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 🪵
- 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
- 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:
- 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).
- If on the `next` branch, the prerelease distribution tag (a.k.a. [`next`](https://www.npmjs.com/package/rdme/v/next)) is updated.
- 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.
- 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 🐙
- If on the `main` branch, the new changes are backported to the `next` branch so both branches remain in sync 🔄

### Maintaining two major release channels

We maintain two different release channels:

- 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))
- one for the latest release (`v10`, as of this writing — `v10` and onward are for customers on ReadMe Refactored only)

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.

Here's the recommended approach:

1. Once the pull request has been merged into `next`, grab the merge commit SHA.
2. Check out the `v9` branch, create a new branch based off of that branch, and cherry-pick the aformentioned commit SHA:

```sh
git checkout v9
git checkout -b my-v9-backport-branch
git cherry-pick SHA
```

3. Create a new pull request and set the base branch to `v9`.
4. Once CI passes and you get the necessary approvals, merge that pull request in.
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.

```sh
git checkout next
git merge v9
```

## One more thing ☝️

> [!NOTE]

0 comments on commit 7e793b9

Please sign in to comment.