From cbd74ee46edd144e6b2d13e5be4b69faabe72e59 Mon Sep 17 00:00:00 2001 From: David Cramer Date: Wed, 22 Nov 2023 12:06:25 -0800 Subject: [PATCH] Overhaul contributor docs (#119) Fixes GH-89, GH-88, GH-84, GH-81 --- CONTRIBUTING.md | 38 ---------- README.md | 2 +- packages/website/astro.config.mjs | 10 +-- .../content/docs/contribute/changesets.mdx | 18 +++++ .../src/content/docs/contribute/docs.mdx | 14 ++++ .../src/content/docs/contribute/index.mdx | 69 +++++++++++++++++++ .../src/content/docs/contribute/releases.mdx | 9 +++ .../src/content/docs/guides/release.mdx | 41 ----------- 8 files changed, 117 insertions(+), 84 deletions(-) delete mode 100644 CONTRIBUTING.md create mode 100644 packages/website/src/content/docs/contribute/changesets.mdx create mode 100644 packages/website/src/content/docs/contribute/docs.mdx create mode 100644 packages/website/src/content/docs/contribute/index.mdx create mode 100644 packages/website/src/content/docs/contribute/releases.mdx delete mode 100644 packages/website/src/content/docs/guides/release.mdx diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index 38c084bb..00000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,38 +0,0 @@ -# Contributing to Spotlight - -## Local Setup - -- `pnpm install` -- `pnpm build` - -### Run Local Dev build - -If you want to run this locally for development, you have to open two terminals and run the following commands: - -1. Terminal 1: `pnpm dev:core` -2. Terminal 2: `pnpm dev:website` - -Then you can find the website under http://localhost:4321/spotlight. - -## Changesets - -Spotlight uses [Changesets](https://github.com/changesets/changesets) to track changes & versions. - -Whenever you make a change that is users facing, you should add a changeset to your PR. You can do this by runing the -following command: - -```bash -pnpm changeset:add -``` - -This will guide you through the process to define the changeset. You have to select which package(s) are affected by -this change, if it is a patch/minor/major change, and provide a description for the change. - -Note that not all PRs need a changeset (e.g. if you only write docs), and a PR can also have more than one changeset. - -## Publishing - -When you want to publish a new version, you need to trigger the -[Prepare Publish](https://github.com/getsentry/spotlight/actions/workflows/prepare-publish.yml) Github Action. This -action will open a PR with all versions bumped & changelogs updated according to the currently pending changesets. If -you approve & merge this PR, these versions will automatically be published to NPM. diff --git a/README.md b/README.md index e3fa003b..372e106f 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ overlay into development environments, and it does it by leveraging the existing ## Contributing / Running the repo -See [CONTIBUTING.md](./CONTRIBUTING.md) for how to contribute and develop Spotlight. +See [Contribute](https://spotlightjs.com/contribute/) for how to contribute and develop Spotlight. ## More on Architecture diff --git a/packages/website/astro.config.mjs b/packages/website/astro.config.mjs index 918a1eb0..be393bba 100644 --- a/packages/website/astro.config.mjs +++ b/packages/website/astro.config.mjs @@ -83,10 +83,6 @@ export default defineConfig({ label: 'Write an integration', link: '/guides/integration/', }, - { - label: 'How to make a Release', - link: '/guides/release/', - }, ], }, { @@ -95,6 +91,12 @@ export default defineConfig({ directory: 'integrations', }, }, + { + label: 'Contribute', + autogenerate: { + directory: 'contribute', + }, + }, { label: 'Reference', autogenerate: { diff --git a/packages/website/src/content/docs/contribute/changesets.mdx b/packages/website/src/content/docs/contribute/changesets.mdx new file mode 100644 index 00000000..e606dc16 --- /dev/null +++ b/packages/website/src/content/docs/contribute/changesets.mdx @@ -0,0 +1,18 @@ +--- +title: Changesets +description: How-to commit to Spotlight. +--- + +Spotlight uses [Changesets](https://github.com/changesets/changesets) to track changes & versions. + +Whenever you make a change that is users facing, you should add a changeset to your PR. You can do this by runing the +following command: + +```shell +pnpm changeset:add +``` + +This will guide you through the process to define the changeset. You have to select which package(s) are affected by +this change, if it is a patch/minor/major change, and provide a description for the change. + +Note that not all PRs need a changeset (e.g. if you only write docs), and a PR can also have more than one changeset. diff --git a/packages/website/src/content/docs/contribute/docs.mdx b/packages/website/src/content/docs/contribute/docs.mdx new file mode 100644 index 00000000..c740f5a6 --- /dev/null +++ b/packages/website/src/content/docs/contribute/docs.mdx @@ -0,0 +1,14 @@ +--- +title: Documentation +description: How-to contribute to documentation. +--- + +Docs are located within the `@spotlightjs/website` project (in `./packages/website`). + +You can run the documentation (website) build using: + +```shell +pnpm dev:website +``` + +You'll then find the Astro-based website available at http://localhost:4321/. diff --git a/packages/website/src/content/docs/contribute/index.mdx b/packages/website/src/content/docs/contribute/index.mdx new file mode 100644 index 00000000..a65999a8 --- /dev/null +++ b/packages/website/src/content/docs/contribute/index.mdx @@ -0,0 +1,69 @@ +--- +title: Get Started +description: A guide how to contribute to Spotlight. +--- + +Spotlight relies on a [pnpm](https://pnpm.io) monorepo. You'll need to install pnpm to get things going, which can be done with [Volta](https://volta.sh). + +Pull down the repo (or your fork): + +```shell +git clone https://github.com/getsentry/spotlight.git +``` + +Ensure the node and pnpm are available: + +```shell +volta install node pnpm +``` + +Lastly, install the package requirements: + +```shell +pnpm install +``` + +## Development + +From there you can spin up the Spotlight repo into watch mode: + +```shell +pnpm dev:core +``` + +Depending on what you're doing there's two paths to develop against the core. + +If you simply want to run Spotlight against the example application, you can spin that up using: + +```shell +pnpm dev:playground +``` + +Additionally you may want to link it into an existing project. This is a little brittle, and we're not experts here, so your mileage may vary. + +First, when in the Spotlight root directory, you'll need to link the packages you're referencing (likely `@spotlightjs/core` and `@spotlightjs/sidecar`): + +```shell +pnpm link --global -C packages/core +pnpm link --global -C packages/sidecar +``` + +You can now link these within your project. For example if you're using `pnpm`: + +```shell +pnpm link --global @spotlightjs/core +pnpm link --global @spotlightjs/sidecar +``` + +## Repository Structure + +The monorepo is mostly straight forward, but here's a quick summary: + +``` +spotlight +└── packages + ├── core // @spotlightjs/core - the main overlay + ├── sidecar // @spotlightjs/sidecar - the sidecar (proxy) for streaming data + ├── tsconfig // @spotlightjs/tsconfig - shared tsconfig + └── website // @spotlightjs/website - the main overlay +``` diff --git a/packages/website/src/content/docs/contribute/releases.mdx b/packages/website/src/content/docs/contribute/releases.mdx new file mode 100644 index 00000000..307c97fe --- /dev/null +++ b/packages/website/src/content/docs/contribute/releases.mdx @@ -0,0 +1,9 @@ +--- +title: Publishing +description: How-to publish a new release of Spotlight. +--- + +When you want to publish a new version, you need to trigger the +[Prepare Publish](https://github.com/getsentry/spotlight/actions/workflows/prepare-publish.yml) Github Action. This +action will open a PR with all versions bumped & changelogs updated according to the currently pending changesets. If +you approve & merge this PR, these versions will automatically be published to NPM. diff --git a/packages/website/src/content/docs/guides/release.mdx b/packages/website/src/content/docs/guides/release.mdx deleted file mode 100644 index 88133a73..00000000 --- a/packages/website/src/content/docs/guides/release.mdx +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: Contributing -description: How to make a release in the repo ---- - -## Local Setup - -- `pnpm install` -- `pnpm build` - -### Run Local Dev build - -If you want to run this locally for development, you have to open two terminals and run the following commands: - -1. Terminal 1: `pnpm dev:core` -2. Terminal 2: `pnpm dev:website` - -Then you can find the website under http://localhost:4321/spotlight. - -## Changesets - -Spotlight uses [Changesets](https://github.com/changesets/changesets) to track changes & versions. - -Whenever you make a change that is users facing, you should add a changeset to your PR. You can do this by runing the -following command: - -```bash -pnpm changeset:add -``` - -This will guide you through the process to define the changeset. You have to select which package(s) are affected by -this change, if it is a patch/minor/major change, and provide a description for the change. - -Note that not all PRs need a changeset (e.g. if you only write docs), and a PR can also have more than one changeset. - -## Publishing - -When you want to publish a new version, you need to trigger the -[Prepare Publish](https://github.com/getsentry/spotlight/actions/workflows/prepare-publish.yml) Github Action. This -action will open a PR with all versions bumped & changelogs updated according to the currently pending changesets. If -you approve & merge this PR, these versions will automatically be published to NPM.