docs: update contributing docs

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,6 +1,7 @@
 <!-- 
 Thank you for your pull request! Please review the requirements below 
 and ensure your pull request has fulfilled all requirements outlined in the target package.
+Before submitting a PR for review, please make sure that all the CI checks are passing.
 -->
 
 ## PR checklist

CONTRIBUTING.md

@@ -1,27 +1,38 @@
 # Contributing to Round Manager and Grant Explorer
 
-Thank you for your desire to contribute to Gitcoin! Below you will find some ways to help, but please don't feel limited by them, and if you have any other ideas, pop by our [Discord](https://discord.gg/gitcoin)
+Thank you for your desire to contribute to Gitcoin! Below you will find some ways to help, but please don't feel limited
+by them, and if you have any other ideas, pop by our [Discord](https://discord.com/channels/562828676480237578/1149808279871049880)
 
 ## Reporting issues
 
 Before reporting an issue, please make sure to verify the following:
+
 - You're running the latest version, including other components and systems the project might interact with
 - Your dependencies are up-to-date
 
-If the issue still persists, search the issue tracker. If there is an open ticket, please don't comment '+1' or similar - use the '👍' emoji. Only comment if you have additional context, reproduction instructions or anything that might help resolve the issue.
+If the issue still persists, search the issue tracker. If there is an open ticket, please don't comment '+1' or
+similar - use the '👍' emoji. Only comment if you have additional context, reproduction instructions or anything that
+might help resolve the issue.
 
 When opening a new issue, make sure it contains the following:
+
 - Step-by-step reproduction instructions
 - Screenshots or videos of the issue, if applicable
 - Version information of the project
 - Any other context that you feel would help resolve the issue
 
 ## Contributing code
 
-We welcome all code contributions, large or small. Please see [DEV.md](packages/round-manager/docs/DEV.md) for instructions on how to set up the project for development.
+We welcome all code contributions, large or small. Please see [DEV.md](docs/DEV.md) for
+instructions on how to set up the project for development.
 
-Before submitting a PR, please make sure that all tests, linting and formatting rules are passing.
+Before submitting a PR for review, please make sure that all the CI checks are passing.
+We also utilize git hooks for pre-commit
+formatting and pre-push checks, which should help you catch issues early, before they fail the CI.
 
-We squash all PRs by default. You can request your PR commits to not be squashed if they're well named and organized, and it would make sense to preserve their context.
+We squash all PRs by default. When updating your PR branch, use merge if it's in review, or rebase otherwise, at your
+own discretion.
 
-_To keep the repository clean, we may mark PRs as stale if there has been no activity for more than a week, which are then subject to closure and deletion. If you are stuck, feel free to reach out for help in [Discord](https://discord.gg/gitcoin)._ 
+_To keep the repository clean, we may mark PRs as stale if there has been no activity for more than a week, which are
+then subject to closure and deletion. If you are stuck, feel free to reach out for help
+in [Discord](https://discord.com/channels/562828676480237578/1149808279871049880)._ 

README.md

@@ -8,91 +8,31 @@ This repository contains packages needed for a user to
 Project Maintained via  : `turborepo`
 Package manager         : `pnpm`
 
-## Directory Structure
+## Packages
+
+- round-manager: React application for managing rounds
+- grant-explorer: React application for exploring the grants ecosystem
+- builder: React application for managing projects
+- common: components and functionality that is shared between projects
+- eslint-config-gitcoin: common eslint config for all grants stack projects
+- verify-env: a utility package and a webpack plugin for verifying the environment of an app during build
+
 
 ```
 .
 ├── .github                     # github specific configuration
-├── packages
-│   ├── round-manager           # react-frontend for round-manager
-│   ├── grant-explorer          # react-frontend for grant-explorer
-│   ├── builder                 # react-frontend for builder
-│   ├── common                  # components and functionality that is shared between projects
-│   ├── eslint-config-gitcoin   # common eslint config for all grants stack projects
+├── packages                    # individual frontends and related packages
 ├── package.json                # root package configuration
+├── docs                        # documentation
 └── README.md
 ```
 
-## Git Hooks
-You can optionally enable pre-commit git hooks that autoformat your changed code using prettier.
-
-```bash
-brew install lefthook
-lefthook install
-```
-
-inspect the current hook configuration in [lefthook.yml](lefthook.yml)
-
-## contracts
-
-The contracts needed for running a round can be found within the [Allo contracts repository](https://github.com/Allo-Protocol/contracts)
-
-### graph
-
-The subgraph which indexs data with regard the
-- ProgramFactory
-- ProgramImplementation
-- RoundFactory
-- RoundImplementation
-
-More information can be found within the [Allo graph repository](https://github.com/Allo-Protocol/graph)
-
-## Packages
-
-### round-manager
-
-This package serves the app which holds all the features w.r.t to
-
-- creating a program
-- maintaining a program
-- creating a round
-- maintaining a program
-
-More information can be found within the [round-manager package](packages/round-manager)
-
 ##### Development
 
-We welcome external contributions. Please make sure to familiarize yourself with the [Contribution Guide](CONTRIBUTING.md).
-
-To contribute to this project, fork the project and follow the instructions at [DEV.md](packages/round-manager/docs/DEV.md)
-
-### grant-explorer
+We welcome external contributions. Please make sure to familiarize yourself with the [Contribution Guidelines](CONTRIBUTING.md).
 
-This package serves the app which holds all the features w.r.t to
-
-- exploring a round
-- voting for a project
-
-
-More information can be found within the [grant-explorer package](packages/grant-explorer)
-
-##### Development
-
-We welcome external contributions. Please make sure to familiarize yourself with the [Contribution Guide](CONTRIBUTING.md).
-
-To contribute to this project, fork the project and follow the instructions at [DEV.md](packages/grant-explorer/docs/DEV.md)
+To contribute to this project, fork the repo and follow the instructions at [DEV.md](docs/DEV.md)
 
 ##### Hosting
 
-All the frontend dApps are hosted via [fleek.co](https://fleek.co/).
-
-Documented below are the environments along with the URL.
-
-Note: Live Deployment should always happen by raising a PR from `main` to `release`
-
-**round-manager**
-
-| Env     | Git Branch | URL                               |
-|---------|------------|-----------------------------------|
-| STAGING | main       | https://rmgitcoin.on.fleek.co/    |
-| LIVE    | release    | https://manager.gitcoin.co/ |
+All the apps are hosted on Vercel. Preview links get created automatically for PRs. Commits to main get deployed to production automatically.

docs/DEV.md

@@ -0,0 +1,84 @@
+## Development
+
+This section documents the basic instructions on running / developing the frontend apps - round-manager, builder and grant-explorer.
+
+### Pre Requisites
+
+Before running any command, make sure to install dependencies. This installs dependencies for the whole monorepo.
+
+```sh
+$ pnpm install
+```
+
+```sh
+cp .env.example .env
+```
+
+The .env file will be prefilled with some static and public variables. For the ones that are empty, please create accounts and fill in your personal API keys for the respective services.
+
+### Run in Development
+
+Runs the app in the development mode.\
+Open [http://localhost:3000](http://localhost:3000) to view it in the browser.
+
+The page will reload if you make edits.\
+You will also see any lint errors in the console.
+
+```sh
+$ pnpm start
+```
+
+### Linting and formatting
+
+We use Prettier for formatting and ESLint for linting. Prettier will auto-format your code before you commit, and linting will run before you push back to remote. The git hook config lies in the `lefthook.yml` file in the root of the repo.
+
+### Testing
+
+`pnpm test` will always run tests in whatever package you're in. We are migrating from Jest to Vitest on all the packages. If you encounter any issues with Jest, consult the [Knowledge base file](KB.md).
+
+### Run in Production
+
+Builds the app for production to the `build` folder.
+
+```sh
+$ pnpm build
+```
+
+Serve on port 3000
+
+```sh
+$ pnpm install -g serve
+$ serve -s build -l 3000
+```
+
+### Adding a new route
+
+Global routing configuration is held in `src/index.tsx`. Below is an example of a route definition
+
+```jsx=
+<Route path="/program/create" element={<CreateProgram />} />
+<Route path="/program/:id" element={<ViewProgram />} />
+```
+
+A protected route i.e a routed which requires a user's wallet connection should be within the parent `ProtectedRoute`
+component route
+
+```jsx=
+<Route element={<ProtectedRoute />}>
+    <Route path="/program/create" element={<CreateProgram />} />
+    <Route path="/program/:id" element={<ViewProgram />} />
+</Route>
+```
+
+Find more information about routing [here](https://reactrouter.com/docs/en/v6).
+
+## Submitting a PR
+
+Please always submit draft PRs at first, and make sure they pass the following conditions before you mark them as Ready for review.
+
+We utilize git hooks for pre-commit
+formatting and pre-push checks, which should help you catch issues early, before they fail the CI.
+
+Before submitting a PR for review, ensure that it passes all the checks of the PR checklist. Also consider doing a self-review of the changes to reduce back-and-forth. 
+
+When the CI is green, PR checklist is ticked off and the PR is in good shape, submit it for review by clicking the "Ready for review" button.

packages/builder/README.md

@@ -1,47 +1,7 @@
 # Builder UI
 
-This serves as the UI for publishing products to the project registry contracts
+This serves as the UI for publishing projects to the project registry contracts, applying to rounds and other actions related to projects.
 
-## Usage
-Usage instructions
+# Development
 
-### Pre Requisites
-
-Before running any command, make sure to install dependencies:
-
-```sh
-yarn install
-```
-
-Copy `.env-example` to `.env` and write your [https://www.pinata.cloud/](pinata.clod) JWT and GATEWAY environment variable.
-
-### Start
-
-Runs the app in the development mode.\
-Open [http://localhost:3000](http://localhost:3000) to view it in the browser.
-
-The page will reload if you make edits.\
-You will also see any lint errors in the console.
-
-```sh
-yarn start
-```
-
-### Test
-
-Launches the test runner.
-
-```sh
-yarn test
-```
-
-### Build
-
-Builds the app for production to the `build` folder.\
-It correctly bundles React in production mode and optimizes the build for the best performance.
-
-```sh
-yarn build
-```
-
-This project was bootstrapped with [Create React App](https://github.com/facebook/create-react-app), using the [Redux](https://redux.js.org/) and [Redux Toolkit](https://redux-toolkit.js.org/) TS template.
+For development instructions, refer to the root [Development guide](../../docs/DEV.md)