From a0dfff8399b4141213b366ff19441b9f017995cd Mon Sep 17 00:00:00 2001 From: Rob Dominguez Date: Mon, 7 Oct 2024 16:58:21 -0500 Subject: [PATCH] Update contribution guide and README Udpates contribution and README to be public-facing and easier to grok. --- README.md | 175 +++++------------------------------------- wiki/contributing.mdx | 22 +++--- 2 files changed, 31 insertions(+), 166 deletions(-) diff --git a/README.md b/README.md index 68e113f01..6959b585e 100644 --- a/README.md +++ b/README.md @@ -1,179 +1,40 @@ # Hasura DDN Docs -## Installation - -``` -$ yarn -``` - -## Local Development - -``` -$ yarn start -``` - -This command starts a local development server and opens up a browser window. Most changes are reflected live without -having to restart the server. - -## Build - -``` -$ yarn build -``` - -This command generates static content into the `build` directory and can be served using any static contents hosting -service. - -## Contributing - -Check out our contribution guide on the [wiki](https://hasura.io/docs/3.0/wiki/contributing/) 🤙 - -If you have any questions, reach out on Slack: [#team-docs](https://hasurahq.slack.com/archives/C015EA71MU0) 📢 - -## Automations - -### Metadata docs - -The metadata docs can be found under `/docs/supergraph-modeling`. A process can be followed which will replace the -content below `## Metadata structure` for each page within this directory: - -#### Step 1: Update the `schema.json` file: - -In `/utilities/generate-metadata-docs`, replace the contents of `schema.json` with your newest -[resolved schema](https://github.com/hasura/hasura-lsp-server/blob/main/server/src/hasura/opendd/supergraph_resolved.json). - -#### Step 2: Update the mapping of metadata objects (optional) - -If you need to reconfigure which metadata objects are mapped to which pages, check the -`/utilities/generate-metadata-docs/src/entities/objects.ts` file. If there are just semantic updates, this isn't -necessary. - -#### Step 3: Run the script - -From the root of the project, run this command: - -```bash -yarn write-metadata-docs -``` - -**Please do a sanity check before committing these updates! Simply grepping for `undefined` within the -`/docs/supergraph-modeling` directory should suffice.** - -### CLI docs - -CLI command docs can be autogenerated using the `docs` command of the CLI. Follow these steps: - -#### Step 1: Update your CLI to the latest version - -Either create a new local build aliased to `ddn` (if the version is unreleased) or run the following: +Welcome to the Hasura DDN Docs repository! This is the official documentation for Hasura DDN. Below, you'll find +instructions on how to install, run, and contribute to the project. -```bash -ddn update-cli -``` - -#### Step 2: Clean up existing docs - -Navigate to `/docs/cli/commands` and run `rm ddn*` to delete the existing docs. - -#### Step 3: Generate new docs +## Installation -In the `/docs/cli/commands` directory run: +To install the necessary dependencies, simply run: ```bash -ddn docs --directory . -``` - -The CLI commands documentation should now be updated. - -## Nice things - -We have nice things that will hopefully help you. Don't make it so we can't have nice things. - -### Direct links for data sources - -Any connector which is documented in DDN docs can be accessed directly using the following query parameter pattern: - -```text -https://hasura.io/docs/3.0/page-route/?db=DataSourceName +$ yarn ``` -The following options are available: - -| Source | Query string | -| ---------- | ------------ | -| PostgreSQL | `PostgreSQL` | -| MongoDB | `MongoDB` | -| ClickHouse | `ClickHouse` | -| TypeScript | `TypeScript` | - -You can learn more about the `` component which renders these docs -[here](https://github.com/hasura/ddn-docs/blob/main/src/components/databaseDocs/index.tsx). - -## Deployments - -We have two environments: staging and production. We use GitHub Actions to deploy to both. Builds take, on average, 3-5 -minutes. - -Assuming you have the correct permissions, you can monitor builds on GCP -[here](https://console.cloud.google.com/cloud-build/builds;region=us-west2?project=websitecloud-352908). - -### Staging - -Upon a successful merge to `main`, a merge is automatically triggered by -[this GitHub Action](https://github.com/hasura/ddn-docs/actions/workflows/merge-main-to-staging.yml) to `release-stage`. -GCP listens for pushes to this branch and, when one comes through, it builds and deploys the site to -[https://stage.hasura.io/docs/3.0](https://stage.hasura.io/docs/3.0). - -### Production - -We still have final control over when we deploy to production. To do so, we can use -[this GitHub Action](https://github.com/hasura/ddn-docs/actions/workflows/merge-staging-to-prod.yml) to trigger a merge -to `release-prod`. GCP listens for pushes to this branch and, when one comes through, it builds and deploys the site to -[https://hasura.io/docs/3.0](https://hasura.io/docs/3.0). - -To use this Action: - -1. Head to [this Action](https://github.com/hasura/ddn-docs/actions/workflows/merge-staging-to-prod.yml) -2. Click `Run workflow` -3. Choose `release-stage` -4. Click `Run workflow` - -In the event we need to cherry-pick (such as during the lead-up to Beta), follow these steps: - -1. Pull `release-stage` on your machine: - -```bash -git checkout release-stage -``` +## Local Development -2. Run a git log to find the commit hash you want to cherry-pick: +To start a local development server and preview the docs: ```bash -git log +$ yarn start ``` -3. Copy the commit hash and run the following command: +This command will open a browser window, and any changes you make will automatically reflect without needing to restart +the server. Perfect for quick iterations! -```bash -git checkout release-prod -``` +## Build -4. Cherry-pick the commit: +To build the documentation for production: ```bash -git cherry-pick +$ yarn build ``` -5. Push the changes: +This generates static content into the `build` directory, which can be hosted using any static hosting service. -```bash -git push release-prod -``` - -This will trigger a build and deployment to production. +## Contributing -You can quickly see what's come through (open and closed) for Beta using -[this filter](https://github.com/hasura/ddn-docs/issues?q=label%3Ahold-for-beta). +We love contributions! If you'd like to contribute, please review our +[Contribution Guide](https://hasura.io/docs/3.0/wiki/contributing/) for all the details on how to get involved 🤙. -You can use the link above to check the build status. Then, monitor deployments to our clusters -[here](https://console.cloud.google.com/kubernetes/deployment/us-west2/prod-website-cloud-us-we2-gke-01/hasura/v3-docs-hasura/overview?project=websitecloud-352908). +We appreciate all contributions to make our docs better for everyone! 🙌 diff --git a/wiki/contributing.mdx b/wiki/contributing.mdx index 5350c9b8a..64f7c8524 100644 --- a/wiki/contributing.mdx +++ b/wiki/contributing.mdx @@ -15,6 +15,15 @@ Docs contributions take many forms. However, they all follow the same workflow. your local development environment set up and - before you know it - you'll be helping make our product clearer for users. +:::info Are you from outside the Hasura org? + +Thanks for considering an improvement to our docs! Please know that the information below is directed towards employees +at Hasura. But, you can fork the repo and open a PR to help us improve our documentation ❤️ + +If at any point you have questions, create an issue and we'll be happy to help 🙌 + +::: + ## Mise-en-place Like @@ -34,12 +43,12 @@ We use Yarn as our package-manager- / project-manager-of-choice. Please make sur :::info Note Like to automate things? So do we. This snippet runs through the prerequisites for Hasurians and fires up the docs -development server. Simply navigate to the directory you want the `hasura-graphql-engine-mono` repo to live, open your -terminal, copy / paste, hit enter, and save literally seconds: +development server. Simply navigate to the directory you want the `ddn-docs` repo to live, open your terminal, copy / +paste, hit enter, and save literally seconds: ```bash git clone https://github.com/hasura/ddn-docs.git -cd v3-docs +cd ddn-docs yarn install yarn start ``` @@ -57,7 +66,7 @@ git clone https://github.com/hasura/ddn-docs.git ### Step 2: Install docs dependencies ```bash -cd v3-docs && yarn install +cd ddn-docs && yarn install ``` We also highly recommend testing locally at this point. Start the development server by running the following command: @@ -66,11 +75,6 @@ We also highly recommend testing locally at this point. Start the development se yarn start ``` -If the server doesn't start, check the errors logging to the terminal. You can also check the -[common errors section](#common-errors) at the bottom of this page. Hit up -[Sean Park-Ross](https://hasurahq.slack.com/team/U03J31UJ8V7) or -[Rob Dominguez](https://hasurahq.slack.com/team/U03H7ABDMF1) on Slack if you need help troubleshooting. - Otherwise, congrats! You're ready to start slinging docs 🤙 ## Workflow