From 2437fb34978e1f0e93425d2f025c4b60ceb276dc Mon Sep 17 00:00:00 2001 From: Sarah Funkhouser <147884153+golanglemonade@users.noreply.github.com> Date: Fri, 15 Nov 2024 16:58:21 -0700 Subject: [PATCH] Adds README + Contributing Guides (#84) * update the READMEs Signed-off-by: Sarah Funkhouser <147884153+golanglemonade@users.noreply.github.com> * update Signed-off-by: Sarah Funkhouser <147884153+golanglemonade@users.noreply.github.com> * contributing Signed-off-by: Sarah Funkhouser <147884153+golanglemonade@users.noreply.github.com> --------- Signed-off-by: Sarah Funkhouser <147884153+golanglemonade@users.noreply.github.com> --- .github/CONTRIBUTING.md | 47 ++++++++++++++ .gitignore | 5 ++ .pre-commit-config.yaml | 4 +- README.md | 95 +++++++++++++++++++++++++++- Taskfile.yaml | 17 +++++ packages/codegen/README.md | 56 +++++++++++++++- packages/codegen/graphql-codegen.yml | 2 +- 7 files changed, 218 insertions(+), 8 deletions(-) create mode 100644 .github/CONTRIBUTING.md diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md new file mode 100644 index 0000000..66d09c6 --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,47 @@ +# Contributing + +Please read the [contributing](.github/CONTRIBUTING.md) guide as well as the +[Developer Certificate of Origin](https://developercertificate.org/). You will +be required to sign all commits to the Openlane project, so if you're unfamiliar +with how to set that up, see +[github's documentation](https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification). + +Given external users will not have write to the branches in this repository, +you'll need to follow the forking process to open a PR - +[here](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork) +is a guide from github on how to do so. + +## Licensing + +This repository contains open source software that comprises the Openlane stack +which is open source software under [Apache 2.0](LICENSE). Openlane's SaaS / +Cloud Services are products produced from this open source software exclusively +by theopenlane, Inc. This product is produced under our published commercial +terms (which are subject to change). Any logos or trademarks in our repositories +in [theopenlane](https://github.com/theopenlane) organization are not covered +under the Apache License and are trademarks of theopenlane, Inc. + +Others are allowed to make their own distribution of this software or include +this software in other commercial offerings, but cannot use any of the Openlane +logos, trademarks, cloud services, etc. + +## Security + +We take the security of our software products and services seriously, including +our commercial services and all of the open source code repositories managed +through our Github Organizations, such as +[theopenlane](https://github.com/theopenlane). If you believe you have found a +security vulnerability in any of our repositories or in our SaaS offering(s), +please report it to us through coordinated disclosure. + +**Please do NOT report security vulnerabilities through public github issues, +discussions, or pull requests!** + +Instead, please send an email to `security@theopenlane.io` with as much +information as possible to best help us understand and resolve the issues. See +the security policy attached to this repository for more details. + +## Questions? + +You can email us at `info@theopenlane.io`, open a github issue in this +repository, or reach out to [matoszz](https://github.com/matoszz) directly. diff --git a/.gitignore b/.gitignore index e7138a9..fdb3a28 100644 --- a/.gitignore +++ b/.gitignore @@ -24,6 +24,11 @@ yarn-debug.log* yarn-error.log* # local env files +./config/.env +./config/.env.local +./config/.env.development.local +./config/.env.test.local +./config/.env.production.local .env .env.local .env.development.local diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 58d6355..701f8d4 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -2,13 +2,13 @@ default_stages: [pre-commit] fail_fast: true repos: - repo: https://github.com/pre-commit/pre-commit-hooks - rev: v4.6.0 + rev: v5.0.0 hooks: - id: trailing-whitespace exclude: jsonschema/api-docs.md - id: detect-private-key - repo: https://github.com/google/yamlfmt - rev: v0.13.0 + rev: v0.14.0 hooks: - id: yamlfmt - repo: https://github.com/crate-ci/typos diff --git a/README.md b/README.md index 2e16b38..377ab07 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,94 @@ -# openlane-ui +# Openlane UI -Where the openlane UI will be housed - stay tuned! +Openlane UI monorepo which holds all the frontend assets for Openlane + +## What's inside? + +This monorepo is run on [Bun](https://bun.sh/) and built using +[Turborepo](https://turbo.build/repo/). It includes the following packages/apps: + +### Apps and Packages + +#### Applications + +- `console`: [Openlane Console](https://console.theopenlane.io/) +- `storybook`: [Storybook Components](https://storybook.theopenlane.io/) + +#### Packages + +- `@repo/codegen`: Generated graphQL functions using `urql` to make requests to + the Openlane graphql api. See the [README](packages/codegen/README.md) for + details. +- `@repo/ui`: UI component library shared by our applications +- `@repo/dally`: DAL library for sharing common patterns and functionality in + our other apps +- `@repo/eslint-config`: `eslint` configurations (includes `eslint-config-next` + and `eslint-config-prettier`) +- `@repo/config-typescript`: `tsconfig.json`s used throughout the monorepo +- `@repo/tailwind-config`: the `tailwind.config.ts` used throughout the monorepo + +## Stack + +- [TypeScript](https://www.typescriptlang.org/) for static type-checking +- [Bun](https://bun.sh/) to bundle, dev, test, deploy and run apps +- [ESLint](https://eslint.org/) for code linting +- [Prettier](https://prettier.io) for code formatting +- [Next.js](https://nextjs.org/) a framework to help with building web + applications using React +- [React](https://react.dev/) for creating user interfaces +- [SWR](https://swr.vercel.app/) for client-side data fetching, caching, and + de-deduping API requests +- [Tailwindcss](https://tailwindcss.com/) for styles without leaving TSX syntax + +## Prerequisites + +1. Install Bun and other dependencies: + ```bash + task local-setup + ``` + +The above should work on macOS environments. If you are using Linux/Windows you +may need to look at the [Taskfile](Taskfile.yaml) and find the equivalent +commands. + +## Build + +To build all apps and packages, run the following commands: + +```bash +task install +task build +``` + +## Develop + +1. Copy the .env, this is in .gitignore so you do not have to worry about + accidentally committing it. This hold example of environment configurations + which you should review and potentially override depending on your needs. + ```bash + cp ./config/.env-example ./config/.env + ``` + +1. To develop all apps and packages, run the following command: + + ```bash + task dev + ``` + +1. Alternatively, you can run a single app instead of all the apps with the + specific task commands. For example to develop on the console app run: + + ``` + task dev:console + ``` + +### API Backend + +The backend used by the console UI is located in the Open +[core repo](https://github.com/theopenlane/core). Please refer to the +[README](https://github.com/theopenlane/core?tab=readme-ov-file#development) in +that repository for details on standing up the api locally. + +## Contributing + +See the [contributing](.github/CONTRIBUTING.md) guide for more information. diff --git a/Taskfile.yaml b/Taskfile.yaml index 2a01c2f..6aee9f4 100644 --- a/Taskfile.yaml +++ b/Taskfile.yaml @@ -11,6 +11,23 @@ includes: dir: ./packages/codegen tasks: + local-setup: + desc: Setup the project dependencies + cmds: + - task: install-bun + - task: install-precommit + - pre-commit install && pre-commit install-hooks + - pre-commit autoupdate + - pre-commit run --show-diff-on-failure --color=always --all-files + + install-bun: + desc: install bun package manager + cmd: curl -fsSL https://bun.sh/install | bash + + install-precommit: + desc: install pre-commit + cmd: brew install pre-commit + build: desc: build all apps and package cmd: bun run build diff --git a/packages/codegen/README.md b/packages/codegen/README.md index 7866afc..e7e7aee 100644 --- a/packages/codegen/README.md +++ b/packages/codegen/README.md @@ -1,7 +1,57 @@ # GraphQL code generator -[@graphql-codegen](https://the-guild.dev/graphql/codegen) is what generated everything in this directory, using the configuration `graphql-codegen.yml`. Comments were placed in the file during evaluation of the tool but you may want to lookup the respective definitions so you understand what controls what. +[@graphql-codegen](https://the-guild.dev/graphql/codegen) is what generated +everything in this directory, using the configuration `graphql-codegen.yml`. -To get up and running you should be able to do a `npm install` in this directory which will setup all the necessary dependencies related to the plugins via the `package.json`, and running the generator can be completed via `npm run codegen` in this directory. If there are any errors with the configuration or your output it will update you within the terminal. +## Generating -More to come! \ No newline at end of file +When interacting with the Openlane `core` api, most of the requests will +interact with the [GraphQL API](https://api.theopenlane.io/query). In order to +make this process easier, we use codegen to create the `urql` functions to be +used within the components. + +1. Add a new query or mutation to `/query`. Queries should be added to a file + relevant to the the object(s) being used. For example, a new organization + query should be added to a file called `organization.graphql` +1. For help creating the correct graphql query, we recommend using the + [Apollo Graphql Explorer](https://studio.apollographql.com/sandbox/explorer) +1. Run the task command to generate. This will run the `generate` command as + well as a `clean` command which does some necessary cleanup on the generated + files. + ``` + task codegen:codegen + ``` + +## Usage + +1. Include import: + ```tsx + import { useUpdateUserNameMutation } from "@repo/codegen/src/schema"; + ``` +1. Call function from generated file, using the `useUpdateUserNameMutation` for + this example: + ```tsx + // setup mutation function + const [{ fetching: isSubmitting }, updateUserName] = + useUpdateUserNameMutation(); + + // add form to collect input + + // call update with data from form + const updateName = async ({ + firstName, + lastName, + }: { + firstName: string; + lastName: string; + }) => { + await updateUserName({ + updateUserId: userId, + input: { + firstName: firstName, + lastName: lastName, + }, + }); + setIsSuccess(true); + }; + ``` diff --git a/packages/codegen/graphql-codegen.yml b/packages/codegen/graphql-codegen.yml index 3ee13b7..5f0c042 100644 --- a/packages/codegen/graphql-codegen.yml +++ b/packages/codegen/graphql-codegen.yml @@ -36,11 +36,11 @@ generates: plugins: - typescript # This plugin generates the base TypeScript types, based on your GraphQL schema - typescript-operations # This plugin generates TypeScript types based on your GraphQLSchema and your GraphQL operations and fragments. It generates types for your GraphQL documents: Query, Mutation, Subscription and Fragment + - typescript-urql # This plugin generates urql (https://github.com/FormidableLabs/urql) components and HOC with TypeScript typings # - typescript-resolvers # This plugin generates TypeScript signature for resolve functions of your GraphQL API. You can use this plugin to generate simple resolvers signature based on your GraphQL types, or you can change its behavior be providing custom model types (mappers) # - typescript-graphql-request # - plugin-typescript-swr # - typescript-react-query # This plugin generates React-Query Hooks with TypeScript typings - - typescript-urql # This plugin generates urql (https://github.com/FormidableLabs/urql) components and HOC with TypeScript typings # - typescript-react-apollo # - typed-document-node # These plugins generate a ready-to-use TypedDocumentNode (a combination of pre-compiled DocumentNode and the TypeScript signature it represents) # - typescript-mock-data