Adds README + Contributing Guides (#84)

* update the READMEs

Signed-off-by: Sarah Funkhouser <[email protected]>

* update

Signed-off-by: Sarah Funkhouser <[email protected]>

* contributing

Signed-off-by: Sarah Funkhouser <[email protected]>

---------

Signed-off-by: Sarah Funkhouser <[email protected]>

.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 `[email protected]` 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 `[email protected]`, open a github issue in this
+repository, or reach out to [matoszz](https://github.com/matoszz) directly.

.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

.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

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.

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

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!
+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);
+   };
+   ```

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