From ae463989696df1917a39364b48ba6704c59c888d Mon Sep 17 00:00:00 2001 From: Jonathan Summers-Muir Date: Thu, 22 Sep 2022 16:37:45 +0200 Subject: [PATCH 1/8] init --- DEVELOPERS.md | 203 ++++++++++------------------------- apps/reference/DEVELOPERS.md | 98 +++++++++++++++++ 2 files changed, 156 insertions(+), 145 deletions(-) create mode 100644 apps/reference/DEVELOPERS.md diff --git a/DEVELOPERS.md b/DEVELOPERS.md index a0dd47cb371..c86166fe98e 100644 --- a/DEVELOPERS.md +++ b/DEVELOPERS.md @@ -2,44 +2,46 @@ 1. [Development setup](#development-setup) - [Install dependencies](#install-dependencies) - - [Fork the repository](#fork-the-repository) -1. [Build Supabase](#build-supabase) - - [Choose a directory](#choose-a-directory) -1. [Start a development server](#start-a-development-server) - - [Supabase Website](#supabase-website) - - [Supabase Docs](#supabase-docs) - - [Supabase Studio](#supabase-studio) -1. [Create a pull request](#create-a-pull-request) +2. [Local development](#local-development) + - [Fork the repository](#fork-the-repository) + - [Clone the repo](#clone-the-repo) + - [Running turborepo](#running-turborepo) + - [Shared components](#shared-components) + - [Installing packages](#installing-packages) +3. [Create a pull request](#create-a-pull-request) - [Common tasks](#common-tasks) - [Add a redirect](#add-a-redirect) -- [Monorepo](#monorepo) - - [Getting started](#getting-started) - - [Shared components](#shared-components) - - [Installing packages](#installing-packages) - - [Development](#development) - [Community channels](#community-channels) -## Development setup +## Getting started -Thanks for your interest in Supabase and for wanting to contribute! Before you begin, read the +Thanks for your interest in [Supabase](https://supabase.com) and for wanting to contribute! Before you begin, read the [code of conduct](https://github.com/supabase/.github/blob/main/CODE_OF_CONDUCT.md) and check out the [existing issues](https://github.com/supabase/supabase/issues). -This document describes how to set up your development environment to build and test Supabase. +This document describes how to set up your development environment to build and test [Supabase](https://supabase.com). ### Install dependencies -You need to install and configure the following dependencies on your machine to build Supabase: +You need to install and configure the following dependencies on your machine to build [Supabase](https://supabase.com): - [Git](http://git-scm.com/) - [Node.js v16.x (LTS)](http://nodejs.org) - [npm](https://www.npmjs.com/) version 7+ or [Yarn](https://yarnpkg.com/) +## Local development + +We are in the process of migrating this repository to monorepo, using [Turborepo](https://turborepo.org/docs). + +Eventually, all the apps will be run using [Turborepo](https://turborepo.org/docs), which will significantly improve the developer workflow. + +If you are working on the ([docs site](https://supabase.com/docs)), please refer to this [developers guide](https://github.com/supabase/supabase/tree/master/apps/reference/DEVELOPERS.md). + ### Fork the repository -To contribute code to Supabase, you must fork the [Supabase Repository](https://github.com/supabase/supabase). +To contribute code to [Supabase](https://supabase.com), you must fork the [Supabase Repository](https://github.com/supabase/supabase). -## Build Supabase +### Clone the repo 1. Clone your GitHub forked repository: @@ -52,142 +54,39 @@ To contribute code to Supabase, you must fork the [Supabase Repository](https:// cd supabase ``` -### Choose a directory +### Running turborepo -Choose if you want to work on the [Supabase Website](https://supabase.com), [Supabase Docs](https://supabase.com/docs), or [Supabase Studio](https://app.supabase.com). - -1. Go to the [Supabase Website](https://supabase.com) directory +[Supabase](https://supabase.com) uses [Turborepo](https://turborepo.org/docs) to manage and run this monorepo. +1. Install the dependences in the root of the repo. ```sh - cd apps/www + npm install # install dependencies ``` - Go to the [Supabase Docs](https://supabase.com/docs) directory - +2. You can then run the apps simultaneously with the following. ```sh - cd apps/reference + npm run dev # start all the applications ``` - Go to the [Supabase Studio](https://app.supabase.com) directory +Then visit, and edit, any of the following sites: - ```sh - cd studio - ``` +Site | Directory | Scope name | Description | Local development server +---- | --------- | ---------- | ----------- | ------------------------ +[supabase.com](https://supabase.com) | `/apps/www` | www | The main website | http://localhost:3000 +[app.supabase.com](https://app.supabase.com) | `/studio` | studio | Studio dashboard | http://localhost:8082 +[POC] Next.js based Docs site | `/apps/temp-docs` | temp-docs | Guides and Reference (Next.js based) | http://localhost:3001 +[POC] Community forum | `/apps/temp-community-forum` | forum | GitHub Discussions | http://localhost:3002 +[POC] DEV articles site | `/apps/temp-community-tutorials` | tutorials | DEV articles (which community members can write) | http://localhost:3003 -1. Install npm/yarn dependencies: +The following sites are temporarily not run using turborepo, and must be run independently. - npm +Site | Directory | Scope name | Description | Local development server +---- | --------- | ---------- | ----------- | ------------------------ +[supabase.com/docs](https://supabase.com/docs) | `/apps/reference` | N/A | Guides and Reference (Currently not in Turborepo) | http://localhost:3010/docs - ```sh - npm install - ``` +For the docs website, please refer to this [developers guide](https://github.com/supabase/supabase/tree/master/apps/reference/DEVELOPERS.md). - or with yarn - - ```sh - yarn install - ``` - -## Start a development server - -To debug code and to see your changes in real time, it is often useful to have a local HTTP server. Click one of the three links below to choose which development server you want to start. - -- [Supabase Website](#supabase-website) -- [Supabase Docs](#supabase-docs) -- [Supabase Studio](#supabase-studio) - -### Supabase Website - -The website is moving to a new monorepo setup. See the [Monorepo](#monorepo) section below. - -### Supabase Docs - -1. Build development server - - npm - - ```sh - npm run build - ``` - - or with yarn - - ```sh - yarn build - ``` - -1. Start development server - - npm - - ```sh - npm run start - ``` - - or with yarn - - ```sh - yarn start - ``` - -1. Access the local server in your web browser at http://localhost:3010/docs. - -### Supabase Studio - -1. Start development server - - npm - - ```sh - npm run dev - ``` - - or with yarn - - ```sh - yarn dev - ``` - -1. Access the local server in your web browser at http://localhost:8082/. -See the [Supabase Studio readme](./studio/README.md) for more information. - -## Create a pull request - -After making your changes, open a pull request (PR). Once you submit your pull request, others from the Supabase team/community will review it with you. - -Did you have an issue, like a merge conflict, or don't know how to open a pull request? Check out [GitHub's pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests) tutorial on how to resolve merge conflicts and other issues. Once your PR has been merged, you will be proudly listed as a contributor in the [contributor chart](https://github.com/supabase/supabase/graphs/contributors). - ---- - -## Common tasks - -### Add a redirect - -Create a new entry in the [`next.config.js`](https://github.com/supabase/supabase/blob/master/apps/www/next.config.js) file in our main site. - -## Monorepo - -We are in the process of migrating this repository to monorepo, using Turborepo. -Eventually, the docs and the Studio will be run using Turborepo, which will significantly improve the developer workflow. -You must be using NPM 7 or higher. - -### Getting started - -```sh -npm install # install dependencies -npm run dev # start all the applications -``` - -Then edit and visit any of the following sites: - -Site | Directory | Description | Local development server ----- | --------- | ----------- | ------------------------ -[supabase.com](https://supabase.com) | `/apps/www` | The main website | http://localhost:3000 -[supabase.com/docs](https://supabase.com/docs) | `apps/reference` | Guides and Reference documentaion | http://localhost:3010/docs -[POC] Community forum | `/apps/temp-community-forum` | GitHub Discussions in a Next.js site | http://localhost:3002 -[POC] DEV articles site | `/apps/temp-community-tutorials` | A Next.js site for our DEV articles (which community members can write) | http://localhost:3003 - -### Shared components +#### Shared components The monorepo has a set of shared components under `/packages`: @@ -196,7 +95,7 @@ The monorepo has a set of shared components under `/packages`: - `/packages/spec`: Generates documentation using spec files. - `/packages/tsconfig`: Shared Typescript settings -### Installing packages +#### Installing packages Installing a package with NPM workspaces requires you to add the `-w` flag to tell NPM which workspace you want to install into. @@ -206,12 +105,26 @@ For example: - `npm install @supabase/ui -w common`: installs into `./packages/common` - `npm install @supabase/ui -w www`: installs into `./apps/www` +- `npm install @supabase/ui -w studio`: installs into `./studio` You do not need to install `devDependencies` in each workspace. These can all be installed in the root package. -### Development +--- -`npm run dev` +## Create a pull request + +After making your changes, open a pull request (PR). Once you submit your pull request, others from the Supabase team/community will review it with you. + +Did you have an issue, like a merge conflict, or don't know how to open a pull request? Check out [GitHub's pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests) tutorial on how to resolve merge conflicts and other issues. Once your PR has been merged, you will be proudly listed as a contributor in the [contributor chart](https://github.com/supabase/supabase/graphs/contributors). + + +--- + +## Common tasks + +### Add a redirect + +Create a new entry in the [`next.config.js`](https://github.com/supabase/supabase/blob/master/apps/www/next.config.js) file in our main site. --- diff --git a/apps/reference/DEVELOPERS.md b/apps/reference/DEVELOPERS.md new file mode 100644 index 00000000000..f5d9bca5207 --- /dev/null +++ b/apps/reference/DEVELOPERS.md @@ -0,0 +1,98 @@ +# Developing Supabase Docs + +1. [Development setup](#development-setup) + - [Install dependencies](#install-dependencies) + - [Fork the repository](#fork-the-repository) +2. [Build Supabase](#build-supabase) + - [Running docs](#running-docs) +3. [Create a pull request](#create-a-pull-request) + +- [Monorepo](#monorepo) +- [Community channels](#community-channels) + +## Development setup + +Thanks for your interest in Supabase and for wanting to contribute! Before you begin, read the +[code of conduct](https://github.com/supabase/.github/blob/main/CODE_OF_CONDUCT.md) and check out the +[existing issues](https://github.com/supabase/supabase/issues). +This document describes how to set up your development environment to build and test Supabase. + +### Install dependencies + +You need to install and configure the following dependencies on your machine to build Supabase: + +- [Git](http://git-scm.com/) +- [Node.js v16.x (LTS)](http://nodejs.org) +- [npm](https://www.npmjs.com/) version 7+ or [Yarn](https://yarnpkg.com/) + +### Fork the repository + +To contribute code to Supabase, you must fork the [Supabase Repository](https://github.com/supabase/supabase). + +## Build Supabase + +1. Clone your GitHub forked repository: + + ```sh + git clone https://github.com//supabase.git + ``` + +1. Go to the Supabase directory: + ```sh + cd supabase + ``` + +### Running docs + +We'll be running the [Supabase Docs](https://supabase.com/docs) + +1. Build development server + + npm + + ```sh + npm run build + ``` + + or with yarn + + ```sh + yarn build + ``` + +1. Start development server + + npm + + ```sh + npm run start + ``` + + or with yarn + + ```sh + yarn start + ``` + +1. Access the local server in your web browser at http://localhost:3010/docs. + +--- + +## Create a pull request + +After making your changes, open a pull request (PR). Once you submit your pull request, others from the Supabase team/community will review it with you. + +Did you have an issue, like a merge conflict, or don't know how to open a pull request? Check out [GitHub's pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests) tutorial on how to resolve merge conflicts and other issues. Once your PR has been merged, you will be proudly listed as a contributor in the [contributor chart](https://github.com/supabase/supabase/graphs/contributors). + +--- + +## Monorepo + +We are in the process of migrating this repository to monorepo, using Turborepo. +This app is currently not in that workflow, but if you want to contribute to any of the other apps, please refer to [the developers readme](https://github.com/supabase/supabase/blob/master/DEVELOPERS.md). + +--- + +## Community channels + +Stuck somewhere? Have any questions? Join the [Discord Community Server](https://discord.supabase.com/) or the [Github Discussions](https://github.com/supabase/supabase/discussions). We are here to help! From 6f6d122b68dad77e3d3dd0310945efe76021d178 Mon Sep 17 00:00:00 2001 From: Jonathan Summers-Muir Date: Thu, 22 Sep 2022 16:44:19 +0200 Subject: [PATCH 2/8] Apply suggestions from code review --- DEVELOPERS.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/DEVELOPERS.md b/DEVELOPERS.md index c86166fe98e..9d9d428ba7b 100644 --- a/DEVELOPERS.md +++ b/DEVELOPERS.md @@ -103,9 +103,9 @@ The format is: `npm install -w=`. For example: -- `npm install @supabase/ui -w common`: installs into `./packages/common` -- `npm install @supabase/ui -w www`: installs into `./apps/www` -- `npm install @supabase/ui -w studio`: installs into `./studio` +- `npm install react -w common`: installs into `./packages/common` +- `npm install react -w www`: installs into `./apps/www` +- `npm install react -w studio`: installs into `./studio` You do not need to install `devDependencies` in each workspace. These can all be installed in the root package. From c5dcbcbd89987a1300d3bf5c23d8241991105ea8 Mon Sep 17 00:00:00 2001 From: Terry Sutton Date: Fri, 23 Sep 2022 16:00:56 -0230 Subject: [PATCH 3/8] Update with a note about generated files --- apps/reference/DEVELOPERS.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/apps/reference/DEVELOPERS.md b/apps/reference/DEVELOPERS.md index f5d9bca5207..9002b525f22 100644 --- a/apps/reference/DEVELOPERS.md +++ b/apps/reference/DEVELOPERS.md @@ -78,6 +78,14 @@ We'll be running the [Supabase Docs](https://supabase.com/docs) --- +### Which files to edit? + +Our docs site are comprised of guides, tutorials, quickstarts as well as reference docs. It's important to note that these reference docs (located at https://supabase.com/docs/reference) are generated from spec files. + +If you go to any page in the [https://supabase.com/docs](Supabase Docs), you'll see an `Edit this page` link at the bottom. This link will indicate which file you need to edit. + +The [https://supabase.com/docs/guides/with-nextjs](NextJS Quickstart), for example, is a markdown file that you can edit directly. This [https://supabase.com/docs/reference/javascript/auth-signup](supabase-js reference doc), however, is generated from a [https://github.com/supabase/supabase/edit/master/spec/supabase_js_v1_legacy.yml](spec file). + ## Create a pull request After making your changes, open a pull request (PR). Once you submit your pull request, others from the Supabase team/community will review it with you. From c52cb56a45286ae823b253f1566411c864f6b468 Mon Sep 17 00:00:00 2001 From: Jonathan Summers-Muir Date: Sat, 24 Sep 2022 22:00:33 +0800 Subject: [PATCH 4/8] Apply suggestions from code review Co-authored-by: dng --- DEVELOPERS.md | 2 +- apps/reference/DEVELOPERS.md | 15 +++++++-------- 2 files changed, 8 insertions(+), 9 deletions(-) diff --git a/DEVELOPERS.md b/DEVELOPERS.md index 9d9d428ba7b..35e435952e1 100644 --- a/DEVELOPERS.md +++ b/DEVELOPERS.md @@ -97,7 +97,7 @@ The monorepo has a set of shared components under `/packages`: #### Installing packages -Installing a package with NPM workspaces requires you to add the `-w` flag to tell NPM which workspace you want to install into. +Installing a package with NPM workspaces requires you to add the `-w` flag to tell NPM which workspace you want to install into. Do not install dependencies in their local folder, install them from the route using the `-w` flag. The format is: `npm install -w=`. diff --git a/apps/reference/DEVELOPERS.md b/apps/reference/DEVELOPERS.md index 9002b525f22..27630b4d569 100644 --- a/apps/reference/DEVELOPERS.md +++ b/apps/reference/DEVELOPERS.md @@ -42,11 +42,10 @@ To contribute code to Supabase, you must fork the [Supabase Repository](https:// cd supabase ``` -### Running docs +### Run the docs locally -We'll be running the [Supabase Docs](https://supabase.com/docs) -1. Build development server +1. Build the development server npm @@ -60,7 +59,7 @@ We'll be running the [Supabase Docs](https://supabase.com/docs) yarn build ``` -1. Start development server +1. Start the development server npm @@ -78,13 +77,13 @@ We'll be running the [Supabase Docs](https://supabase.com/docs) --- -### Which files to edit? +### Editing files -Our docs site are comprised of guides, tutorials, quickstarts as well as reference docs. It's important to note that these reference docs (located at https://supabase.com/docs/reference) are generated from spec files. +Our docs site are comprised of guides, tutorials, quickstarts, and reference docs. Note that the [reference docs](https://supabase.com/docs/reference) are generated from spec files. -If you go to any page in the [https://supabase.com/docs](Supabase Docs), you'll see an `Edit this page` link at the bottom. This link will indicate which file you need to edit. +If you go to any page in the [Supabase docs](https://supabase.com/docs), you'll see an **Edit this page** link at the bottom. This link indicates which file you need to edit. -The [https://supabase.com/docs/guides/with-nextjs](NextJS Quickstart), for example, is a markdown file that you can edit directly. This [https://supabase.com/docs/reference/javascript/auth-signup](supabase-js reference doc), however, is generated from a [https://github.com/supabase/supabase/edit/master/spec/supabase_js_v1_legacy.yml](spec file). +For example, the [NextJS Quickstart](https://supabase.com/docs/guides/with-nextjs) is a markdown file you can edit directly. However, this [signUp() reference doc](https://supabase.com/docs/reference/javascript/auth-signup) is generated from a [spec file](https://github.com/supabase/supabase/edit/master/spec/supabase_js_v1_legacy.yml). ## Create a pull request From a6e23fb17fb227723cd453ebb9683835c308003f Mon Sep 17 00:00:00 2001 From: Jonathan Summers-Muir Date: Sat, 24 Sep 2022 22:02:25 +0800 Subject: [PATCH 5/8] Apply suggestions from code review Co-authored-by: dng --- DEVELOPERS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/DEVELOPERS.md b/DEVELOPERS.md index 35e435952e1..7e2b13c1374 100644 --- a/DEVELOPERS.md +++ b/DEVELOPERS.md @@ -1,6 +1,6 @@ # Developing Supabase -1. [Development setup](#development-setup) +1. [Getting started](#getting-started) - [Install dependencies](#install-dependencies) 2. [Local development](#local-development) - [Fork the repository](#fork-the-repository) From 74a95d8734e3ea08dd4eead129878a5042d1fcc8 Mon Sep 17 00:00:00 2001 From: Jonathan Summers-Muir Date: Sat, 24 Sep 2022 22:02:43 +0800 Subject: [PATCH 6/8] Update apps/reference/DEVELOPERS.md Co-authored-by: dng --- apps/reference/DEVELOPERS.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/apps/reference/DEVELOPERS.md b/apps/reference/DEVELOPERS.md index 27630b4d569..4e317587cab 100644 --- a/apps/reference/DEVELOPERS.md +++ b/apps/reference/DEVELOPERS.md @@ -4,7 +4,8 @@ - [Install dependencies](#install-dependencies) - [Fork the repository](#fork-the-repository) 2. [Build Supabase](#build-supabase) - - [Running docs](#running-docs) + - [Run the docs locally](#run-the-docs-locally) + - [Editing files](#editing-files) 3. [Create a pull request](#create-a-pull-request) - [Monorepo](#monorepo) From 89cf46aaee978573e0db0904c1158db4d67b8319 Mon Sep 17 00:00:00 2001 From: Jonathan Summers-Muir Date: Thu, 10 Nov 2022 11:22:01 +0800 Subject: [PATCH 7/8] Update DEVELOPERS.md --- DEVELOPERS.md | 22 ++++++++++------------ 1 file changed, 10 insertions(+), 12 deletions(-) diff --git a/DEVELOPERS.md b/DEVELOPERS.md index 13012acb097..e427b76ed6f 100644 --- a/DEVELOPERS.md +++ b/DEVELOPERS.md @@ -71,21 +71,19 @@ To contribute code to [Supabase](https://supabase.com), you must fork the [Supab Then visit, and edit, any of the following sites: -| Site | Directory | Scope name | Description | Local development server | -| -------------------------------------------- | -------------------------------- | ---------- | ------------------------------------------------ | ------------------------ | -| [supabase.com](https://supabase.com) | `/apps/www` | www | The main website | http://localhost:3000 | -| [app.supabase.com](https://app.supabase.com) | `/studio` | studio | Studio dashboard | http://localhost:8082 | -| [POC] Next.js based Docs site | `/apps/temp-docs` | temp-docs | Guides and Reference (Next.js based) | http://localhost:3001 | -| [POC] Community forum | `/apps/temp-community-forum` | forum | GitHub Discussions | http://localhost:3002 | -| [POC] DEV articles site | `/apps/temp-community-tutorials` | tutorials | DEV articles (which community members can write) | http://localhost:3003 | +| Site | Directory | Scope name | Description | Local development server | +| -------------------------------------------- | -------------- | ---------- | ------------------------------------ | ------------------------ | +| [supabase.com](https://supabase.com) | `/apps/www` | www | The main website | http://localhost:3000 | +| [app.supabase.com](https://app.supabase.com) | `/studio` | studio | Studio dashboard | http://localhost:8082 | +| [supabase.com/docs] Next.js based Docs site | `/apps/docs` . | docs | Guides and Reference (Next.js based) | http://localhost:3001 | -The following sites are temporarily not run using turborepo, and must be run independently. +#### Running sites individually -| Site | Directory | Scope name | Description | Local development server | -| ---------------------------------------------- | ----------------- | ---------- | ------------------------------------------------- | -------------------------- | -| [supabase.com/docs](https://supabase.com/docs) | `/apps/reference` | N/A | Guides and Reference (Currently not in Turborepo) | http://localhost:3010/docs | +You can run any of the sites indiviudally by using the scope name. For example: -For the docs website, please refer to this [developers guide](https://github.com/supabase/supabase/tree/master/apps/reference/DEVELOPERS.md). +```sh +npm run dev:www +``` #### Shared components From 0adc3579bcae751b164819855726a4dc226266e5 Mon Sep 17 00:00:00 2001 From: Jonathan Summers-Muir Date: Thu, 10 Nov 2022 11:24:19 +0800 Subject: [PATCH 8/8] Update DEVELOPERS.md --- apps/reference/DEVELOPERS.md | 1 - 1 file changed, 1 deletion(-) diff --git a/apps/reference/DEVELOPERS.md b/apps/reference/DEVELOPERS.md index 4e317587cab..c5fae76474f 100644 --- a/apps/reference/DEVELOPERS.md +++ b/apps/reference/DEVELOPERS.md @@ -45,7 +45,6 @@ To contribute code to Supabase, you must fork the [Supabase Repository](https:// ### Run the docs locally - 1. Build the development server npm