Skip to content

Commit

Permalink
Update contribution guide and README
Browse files Browse the repository at this point in the history 
Udpates contribution and README to be public-facing and easier to grok.
  • Loading branch information
@robertjdominguez
robertjdominguez committed Oct 7, 2024
1 parent 0452fad commit a0dfff8
Show file tree
Hide file tree
Showing 2 changed files with 31 additions and 166 deletions.
175 changes: 18 additions & 157 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -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 `<DatabaseContentLoader />` 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 <commit-hash>
$ 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! 🙌
22 changes: 13 additions & 9 deletions wiki/contributing.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
```
Expand All @@ -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:
Expand All @@ -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
Expand Down

0 comments on commit a0dfff8

Please sign in to comment.