From e1daad57fffeccd64a8c83c7415c8602ca607ef2 Mon Sep 17 00:00:00 2001 From: Arshadul Monir Date: Fri, 2 Oct 2026 09:39:53 -0400 Subject: [PATCH] Added onboarding documentation for patchats --- docs/local/README.md | 6 - docs/onboarding/README.md | 202 ++++++++++++++++++ .../contribution-workflow.md} | 16 +- .../development-commands.md} | 32 ++- .../local-development-setup.md} | 73 +++---- 5 files changed, 264 insertions(+), 65 deletions(-) delete mode 100644 docs/local/README.md create mode 100644 docs/onboarding/README.md rename docs/{local/WORKFLOW.md => onboarding/contribution-workflow.md} (60%) rename docs/{local/DEV-COMMANDS.md => onboarding/development-commands.md} (62%) rename docs/{local/SETUP.md => onboarding/local-development-setup.md} (54%) diff --git a/docs/local/README.md b/docs/local/README.md deleted file mode 100644 index 7580ad31..00000000 --- a/docs/local/README.md +++ /dev/null @@ -1,6 +0,0 @@ -# Local development - -Please go through the docs in the given order - -1. [Setup](./SETUP.md) -1. [Developer Commands](./DEV-COMMANDS.md) diff --git a/docs/onboarding/README.md b/docs/onboarding/README.md new file mode 100644 index 00000000..391864db --- /dev/null +++ b/docs/onboarding/README.md @@ -0,0 +1,202 @@ +# Developer onboarding + +Welcome to PatChats. This guide is the starting point for getting a local development environment running and making a first contribution. The more detailed guides linked below remain the source of truth for individual tools and workflows. + +The onboarding documentation is organized as follows: + +1. [Local development setup](./local-development-setup.md) +2. [Development commands](./development-commands.md) +3. [Contribution workflow](./contribution-workflow.md) + +## What PatChats does + +PatChats manages monthly one-on-one coffee chat pairings for the Patina Network. Members create profiles, choose matching preferences, and receive a new pairing each month. Administrators manage members, matching cycles, and communications. + +The application has two main parts: + +- A Java 25 and Spring Boot backend in `src/` +- A React, TypeScript, and Vite frontend in `js/` + +PostgreSQL stores application and session data. Database changes are managed with Flyway migrations in `db/`. + +## Before you begin + +Make sure you have access to the team resources used during development: + +- The PatChats GitHub repository +- The team's Notion workspace and task board +- The team's Discord channels +- Graphite, if you will create and submit stacked pull requests +- The appropriate SOPS keys if your work requires editing encrypted secrets + +Ask a maintainer if you are missing access. Never copy plaintext production or staging secrets into the repository or your local `.env` file. + +## 1. Install the development tools + +Install the prerequisites listed in the +[local development setup guide](./local-development-setup.md). At minimum, local development +currently requires: + +- JDK 25 +- Node.js and Corepack +- `just` +- `dotenvx` +- PostgreSQL 16 + +The repository includes the Maven wrapper, so use `./mvnw` instead of relying on a globally +installed Maven version. The frontend's pnpm version is pinned in `js/package.json`; Corepack will +use that version instead of an independently installed global version. + +Confirm the main tools are available: + +```bash +java --version +node --version +corepack --version +just --version +dotenvx --version +psql --version +``` + +## 2. Configure the project + +Run the following commands from the repository root. + +Create your local environment file: + +```bash +cp .example.env .env +``` + +Update the database values in `.env` to match your local PostgreSQL installation. The development profile logs email content to the backend terminal instead of sending it, so working SMTP credentials are not required for normal local development. + +Create the database if it does not already exist: + +```bash +createdb patchats +``` + +Install dependencies and configure the repository's Git hooks: + +```bash +./mvnw install -DskipTests +just frontend-install +just install-pre-scripts +``` + +Apply the database migrations and local seed data: + +```bash +just migrate +``` + +See the [database guide](../../db/README.md) before adding or changing a migration. + +## 3. Run PatChats locally + +Start the backend and frontend together: + +```bash +just dev +``` + +Once both processes are ready: + +- Frontend: +- Backend API: +- OpenAPI document: +- Swagger UI: + +Verify the backend in another terminal: + +```bash +curl http://localhost:8080/api +``` + +For a walkthrough of local passwordless login, including where to find the development magic link, see [Manual test walkthrough](../auth-feature.md#manual-test-walkthrough-dev). + +## 4. Run the checks + +Before opening a pull request, run both test suites: + +```bash +just backend-test +just frontend-test +``` + +Useful focused commands are documented in +[Development commands](./development-commands.md). The installed pre-commit hook formats and +lints staged Java and frontend files, but it does not replace running the complete test suites. + +## 5. Learn where code belongs + +Start with these locations: + +| Area | Location | Notes | +| --- | --- | --- | +| Backend API | `src/main/java/org/patinanetwork/patchats/api/` | REST controllers, services, security, and related domain code | +| Backend tests | `src/test/java/` | Keep tests aligned with the production package structure | +| Frontend features | `js/src/features/` | Domain-owned pages, components, API hooks, and tests | +| Frontend shell | `js/src/app/` | Router, route guards, layouts, and providers | +| Shared frontend code | `js/src/components/` and `js/src/lib/` | Cross-domain UI and infrastructure | +| Database | `db/migration/` and `db/repeated/` | Production migrations and local-only repeatable seed data | +| Project commands | `Justfile` | Common development, test, migration, and secret-management commands | + +Read [Frontend structure and conventions](../../js/docs/frontend-structure.md) before adding frontend pages, hooks, or shared components. Backend API responses use `ApiResponder`, and controllers should keep their OpenAPI annotations current. + +## 6. Make a first contribution + +Use the team's [contribution workflow](./contribution-workflow.md) for the full task-to-merge +process. In brief: + +1. Read the task and clarify its acceptance criteria. +2. Move the task to `In Progress`. +3. Sync from `main` and create a focused branch. +4. Implement the change and add or update tests. +5. Run the backend and frontend checks that apply. +6. Submit the pull request with a clear description and screenshots for visible changes. +7. Address automated checks and reviewer feedback before merging. + +Keep pull requests small enough to review comfortably. Do not include unrelated formatting changes, local environment files, generated build output, or plaintext secrets. + +## Common setup problems + +### The backend cannot connect to PostgreSQL + +Confirm PostgreSQL is running, the `patchats` database exists, and the five `DATABASE_*` values in `.env` match your local server. Then rerun `just migrate`. + +### The frontend cannot reach the API + +Confirm the backend is listening on port `8080`. Vite proxies `/api` requests from port `5173` to the backend, so browser requests should normally use `/api` rather than a hard-coded backend origin. + +### A magic-link email never arrives + +This is expected in development. The backend prints the rendered email and magic-link URL to its terminal instead of connecting to SMTP. + +### A formatting check fails + +For backend files, run: + +```bash +just backend-spotless-fix +``` + +For frontend files, run: + +```bash +cd js +pnpm run fix +``` + +## Onboarding completion checklist + +- [ ] Required team and repository access is working +- [ ] All development tools report the expected versions +- [ ] `.env` is configured without real shared-environment secrets +- [ ] Database migrations complete successfully +- [ ] The frontend and backend run locally +- [ ] The backend smoke test succeeds +- [ ] Passwordless login has been tested locally +- [ ] Backend and frontend checks pass +- [ ] The code structure and contribution workflow guides have been read +- [ ] A first pull request has been opened or assigned diff --git a/docs/local/WORKFLOW.md b/docs/onboarding/contribution-workflow.md similarity index 60% rename from docs/local/WORKFLOW.md rename to docs/onboarding/contribution-workflow.md index d6b3520e..5c731c43 100644 --- a/docs/local/WORKFLOW.md +++ b/docs/onboarding/contribution-workflow.md @@ -1,22 +1,22 @@ -# Feature Workflow +# Contribution workflow Use this flow when handling a feature from assignment through merge and handoff. ## Workflow -1. Read the task description in Notion and understand the requested change/feature. +1. Read the task description in Notion and understand the requested change or feature. 2. Set the Notion ticket status to `In Progress`. -3. Run `gt sync` to pull latest main restacks branches. -4. Checkout main then create a local branch with `gt create branch_name` -5. Submit the pull request when the change/feature is completed with `gt submit` +3. Run `gt sync` to update `main` and restack branches. +4. Check out `main`, then create a local branch with `gt create branch_name`. +5. Submit the pull request when the change is complete with `gt submit`. 6. Set the Notion ticket status to `Pending PR`. 7. Add a clear PR description. 8. Add a screenshot from the development environment (if available). 9. Add a screenshot from the staging environment (if available). 10. Ensure all PR checklist items are completed. -11. Resolve any graphite suggestions. -12. Ping a reviewer on discord. +11. Resolve any Graphite suggestions. +12. Ping a reviewer on Discord. 13. Resolve reviewer comments. -14. Rebase with `gt sync`, `gt restack` and `gt submit`. +14. Rebase with `gt sync`, `gt restack`, and `gt submit`. 15. Merge to main with `gt merge`. 16. Set the Notion ticket status to `Done`. diff --git a/docs/local/DEV-COMMANDS.md b/docs/onboarding/development-commands.md similarity index 62% rename from docs/local/DEV-COMMANDS.md rename to docs/onboarding/development-commands.md index b88d978d..3baf85d2 100644 --- a/docs/local/DEV-COMMANDS.md +++ b/docs/onboarding/development-commands.md @@ -1,32 +1,36 @@ -# Shared +# Development commands + +Run these commands from the repository root. Use `just --list` to see the recipes currently +available in the `Justfile`. + +## Application `just dev` - Will run both the backend and frontend development server at the same time. -`just devd` - Will run both the backend and frontend development server at the same time, but the backend will be in debug mode. See `just backend-dev-debug`. +`just devd` - Will run both development servers, but the backend waits for a JVM debugger on port +`5005`. See `just backend-dev-debug`. -# Database +## Database `just drop` - Will drop your local database's public schema using the credentials provided in `.env` `just migrate` - Will migrate your local database using the credentials provided in `.env` -# Frontend - -`just dev` - Will run both the backend and frontend development server at the same time. +## Frontend `just frontend-install` - Download any missing frontend dependencies. An alias for `cd js && pnpm i`. `just frontend-dev` - Will only start the frontend Vite dev server. -`just frontend-test` - Run the entire frontend test suite - linters, autoformatters, typechecking, etc +`just frontend-test` - Run the frontend test suite. -# Backend +## Backend `just backend-install` - Builds and installs Spring backend. An alias for `./mvnw install -DskipTests=true`. `just backend-dev` - Will only start the backend Spring dev server. -`just backend-dev-debug` - Will only start the backend Spring dev server, but will wait for a JVM debugger to attach to port 5006 first. +`just backend-dev-debug` - Will only start the backend Spring dev server, but will wait for a JVM debugger to attach to port 5005 first. `just backend-test` - Run Checkstyle and then the full test suite. @@ -35,3 +39,13 @@ `just backend-spotless` - Runs the backend formatter (currently Spotless with Palantir Java Formatter) and indicates whether or not you need to run the formatter on any files. `just backend-spotless-fix` - Runs the backend formatter (currently Spotless with Palantir Java Formatter) and will write to any files that have not been formatted yet. + +## Repository setup and secrets + +`just install-pre-scripts` - Configure Git to use the repository's `.githooks` directory. + +`just edit ` - Decrypt an existing SOPS-managed file in an editor and re-encrypt it when the +editor closes. + +`just encrypt ` - Encrypt a new secrets file with SOPS. Use `just edit` for files that are +already encrypted. diff --git a/docs/local/SETUP.md b/docs/onboarding/local-development-setup.md similarity index 54% rename from docs/local/SETUP.md rename to docs/onboarding/local-development-setup.md index 8e94113b..0c0498ce 100644 --- a/docs/local/SETUP.md +++ b/docs/onboarding/local-development-setup.md @@ -1,40 +1,38 @@ -# Prerequisites +# Local development setup + +## Prerequisites The following general software needs to be installed on your local machine: -1. `JDK 25` - We use `openjdk`, but feel free to use `coretto` or any other distribution if you would like. -1. `maven` - Package manager to manage all our Java dependencies +1. JDK 25 - OpenJDK, Corretto, or another compatible distribution. 1. `just` - The runner for `Justfiles`, which we use to consolidate our run commands. 1. `dotenvx` - Used to load environment variables from the root `.env` file. -1. `node` - Javascript runtime to run our frontend TypeScript code. -1. `corepack` - A package manager for package managers (???) to help us set a consistent `pnpm` version across all devs. -1. `pnpm@11` - Package manager that works faster than the default npm package manager. - -## MacOS +1. Node.js - The JavaScript runtime used by the frontend toolchain. +1. Corepack - Activates the version of `pnpm` pinned in `js/package.json`. +1. PostgreSQL 16 - The local application database. -The following instructions are using `homebrew` ([install instructions here](https://brew.sh/)), but it is not a requirement; you can follow along by installing all packages manually (though we would recommend against it). +The repository includes the Maven wrapper (`./mvnw`), so a global Maven installation is not +required. SOPS is only required when you need to edit the encrypted secret files. -1. Install `openjdk@25` (aliased to `openjdk`): +## macOS - ```bash - brew install openjdk - ``` +These instructions use [Homebrew](https://brew.sh/), but you may install the same tools manually. -1. Install `maven`: +1. Install `openjdk@25`: ```bash - brew install maven + brew install openjdk@25 ``` 1. Install `node`: - ``` + ```bash brew install node ``` -1. You must then setup `corepack`. You can follow the instructions [here](https://github.com/nodejs/corepack?tab=readme-ov-file#how-to-install) under `Install Corepack using npm` on how to install and setup `corepack`. Once setup, simply enable `pnpm` on `corepack` like so: +1. Set up `corepack` using its [installation instructions](https://github.com/nodejs/corepack#readme), then enable the repository-pinned version of `pnpm`: - ``` + ```bash corepack enable pnpm ``` @@ -52,49 +50,42 @@ The following instructions are using `homebrew` ([install instructions here](htt ## Windows -Unfortunately, I don't have a Windows machine that I develop on anymore, so I am unable to provide solid instructions for setup. However, you should be able to follow the exact same directions for [MacOS](#macos) but with `WinGet`/`Scoopy` or manually installing each software. +Install the same prerequisites with WinGet, Scoop, or the official installers. The project commands +in this guide should be run from a shell that provides the expected Unix command-line tools. -# IDE Integration +## IDE integration -## VSCode +### VS Code -> **NOTE**: If you open the codebloom repository in VSCode, it will prompt you to install recommended extensions to the workspace, which will include everything below. ->
image +Useful extensions include: -You need to install the following plugins: - -1. **EditorConfig** - Applies consistent spacing width and type across all editors 1. **Checkstyle for Java** - Java static analyzer 1. **Prettier** - Javascript formatter - Helps maintain consistent styling - Configure format on save [following these instructions](https://stackoverflow.com/questions/39494277/how-do-you-format-code-on-save-in-vs-code) 1. **ESLint** - Javascript linter - Integrates with your project's ESLint configuration -1. **Babel JavaScript** - Improves JSX syntax highlighting -1. **Docker** - Provides Dockerfile IntelliSense 1. **DotENV** - `.env` file syntax highlighting 1. **Prettier Typescript Errors**: Simplifies complex TypeScript error messages 1. **Extension Pack for Java** - Includes debuggers, formatters, and managers - Supports format on save 1. **Spring Boot Extension Pack** - Additional Spring Boot-specific tooling -1. **Tailwind CSS IntelliSense** - Provides intelligent suggestions for Tailwind classes 1. **XML by RedHat** - Official XML language support and formatter - Important for editing Java XML files like pom.xml -[.vscode/](https://github.com/tahminator/codebloom/tree/main/.vscode) defines some workspace defaults to help make development consistent. +[.vscode/](../../.vscode/) defines workspace defaults that help keep development consistent. -## IntelliJ +### IntelliJ You need to install the following plugins: -1. **EditorConfig** - Applies consistent spacing width and type across all editors 1. **Checkstyle-IDEA** - Java static analyzer -The Eclipse formatter and everything else should just work out of the box. You may need to install some plugins for TypeScript support, including Prettier, ESLint, Babel, Prettier, Tailwind, and more. +You may also need plugins for TypeScript, Prettier, and ESLint support. -## Neovim +### Neovim > **NOTE**: This may vary greatly by the current configuration of Neovim, but the following setup _should_ work out the box using `LazyVim`. @@ -105,13 +96,10 @@ You need to install the following plugins: 1. **none-ls** - Provide a code bridge to formatting & LSP diagonostics. (Specifically used for Checkstyle formatting) 1. **vtsls** - LSP for TypeScript in Neovim (can install through `Mason`) 1. **eslint-lsp** - LSP Protocol for ESLint (can install through `Mason`) -1. **tailwindcss-language-server** - LSP for Tailwind (can install through `Mason`) 1. **json-lsp** - (Optional) LSP for JSON (can install through `Mason`) 1. **dockerfile-language-server** - (Optional) LSP for Dockerfile (can install through `Mason`) -There is a [.lazy.lua](https://github.com/tahminator/codebloom/tree/main/.lazy.lua) file in the root directory that will apply some default, but only for `LazyVim`. Of course, you can replicate the behavior in your own distribution (and create a pull request with the changes). - -# Database +## Database ## Postgres @@ -144,7 +132,8 @@ You can feel free to download Postgres however you want, but the way we have all #### Other -You may install it with Docker, or directly through [postgresql.com](https://postgresql.com) if you would like. While there are no directions I can directly offer to you, there are some very good tutorials online on how to do so. +You may install it with Docker or directly through the +[PostgreSQL downloads page](https://www.postgresql.org/download/). If you would like to use Docker, I can refer you to Patina's documentation for setting up Docker which you can find [here](https://github.com/arklian/patina/blob/main/docs/postgres-on-docker.md) @@ -153,9 +142,9 @@ If you would like to use Docker, I can refer you to Patina's documentation for s You can feel free to use any viewer you want, but we would recommend [DataGrip](https://www.jetbrains.com/datagrip/) which is free for all non-commercial use. -# Secrets +## Secrets -You can speed up the setup process by making a copy of `.env.example` to `.env`. -You will also find explanations and documentation about how to source the value for each key. +Create a local environment file by copying `.example.env` to `.env`. The example file documents +each value required for local development. If there is a key specific to an environment (such as `CI` or `staging` environment), please consult the tech docs within the `CI` group.