Skip to content

Latest commit

 

History

History
114 lines (77 loc) · 8.55 KB

CONTRIBUTING.md

File metadata and controls

114 lines (77 loc) · 8.55 KB
Raw

Contributor Manual

Welcome! Thank you for your interest in contributing to the Namesake app. We're glad you are here!

Our aim is for contributions to be easy and understandable. If you run into trouble at any step of the process, reach out on Discord.

Getting started

There are many different ways to contribute to Namesake. You can share feedback in the Discord, report a bug or a feature request, or submit your own code to the codebase.

Install pnpm (if needed, first time only)

Namesake uses pnpm for package management. You may need to install pnpm globally if you don't have it already.

Fork the repository (first time only)

Unless you're a member of the namesakefyi org, you won't be able to open a branch directly on the repo. To make changes, you have to fork a copy. Click the "Fork" button on the top right of the main repository page.

Clone the repository (first time only)

Once you've forked the repository, clone it to your computer. Replace USERNAME below with your GitHub username.

git clone https://github.com/USERNAME/namesake.git
cd namesake
pnpm install

Connect to Convex (first time only)

The first time you set up the app, you'll need to connect to our backend service, Convex. Run:

npx convex dev

Convex will prompt you to create an account or a new project as necessary. This will be a personal account you use for development, and the Convex dashboard will allow you to manage your local development database in the browser.

Once your Convex account and project is created, a .env.local file will be generated. This points to a dev database for you to use.

Note

If this is your first time using Convex, follow the tour to understand how the system works and read The Zen of Convex to understand best practices.

Making changes

Start the dev server

To start developing locally, run:

pnpm dev

Note

The dev command will spin up the convex backend and the app's frontend in parallel. To run them individually, run pnpm dev:frontend or pnpm dev:backend.

The app should now be available at http://localhost:5173. You're all set up!

Now that the development app is running, let's get familiar with what's inside.

Project structure

📂 convex          # Backend queries, mutations, and schema definitions
📂 e2e             # End-to-end Playwright tests
📂 public          # Images, favicons, and other unprocessed assets
📂 src             # Frontend application
└── 📂 components  # Shared components
    ├── 📂 app     # App-related global components (logos, sidebar, etc.)
    ├── 📂 common  # Design system components from React Aria
    └── 📂 quests  # Feature-specific quest components
├── 📂 routes      # File-based routing using TanStack Router
├── 📂 styles      # Global CSS (not much here; most of it's in Tailwind!)
└── 📄 main.tsx    # Base of the project including common Providers

Dependencies

Below are Namesake's core dependencies. The links below each lead to docs.

Tech What For
Convex Type-safe database, file storage, realtime updates
Convex Auth User authentication
TanStack Router File-based routing
React Front-end web framework
React Aria Accessible components and design system
Tailwind Utility-first styling
Lucide Icons SVG icons
Radix Colors Accessible color palette
Resend Email sending
Vitest Unit testing
Playwright End-to-end testing
Biome Formatting and linting

View all dependencies in package.json.

Formatting code

Code formatting and linting is handled with Biome. If you use VS Code to make edits, Biome should automatically format your files on save, according to .vscode/settings.json. The first time you open the Namesake repository in VS Code, it may prompt you to install the Biome extension.

In addition, each time you git commit changes to the codebase, a Husky pre-commit hook will run to check and format your code according to our Biome rules. This check helps prevent any poorly-formatted code from entering the codebase. If Biome throws an error when you try to commit your code, fix the error, add your changes, and commit again. You can re-use your original commit message—since the commit failed, the original message was discarded.

Creating pull requests

  1. Keep changes small when possible. If you're tackling multiple issues, split them up into multiple pull requests. Smaller chunks of code are easier to review and test!
  2. Explain what you did, why, and how. Each pull request has a pre-filled template. Use it! "The better we present our code for review, the more likely the reviewer will be engaged with a critical eye." — Writing a Great Pull Request Description
  3. Add a changeset. Namesake uses changesets to version releases. You can add a changeset by running pnpm changeset and selecting the appropriate options. patch is for bug fixes and tiny edits. minor is for small new features or designs. major is for large new features. If your PR changes multiple things (e.g. patches two bugs and adds one small feature), you can add multiple changesets. Changesets should be written from a user perspective—PRs which only affect developers (refactoring some tests, for example) do not need a changeset.
  4. Use conventional commit style titles. This means prefixing your PR title with a word like feat:, fix:, build:, chore:, ci:, docs:, style:, refactor:, perf:, or test:. The title itself should start with a verb, like "add" or "update".
  5. Add or update tests. The goal for Namesake is to have solid test coverage. When you open a PR, you'll see an automated comment that displays how test coverage has increased or decreased with your changes. While Namesake is pre-version 1.0, our test coverage may be spotty and isn't the first priority. If you want to ignore this for now, it won't prevent you from merging.

Releasing

Any PRs containing a changeset, once merged into main will generate or update an automated PR titled ci: Release. This PR contains updates to the changelog using the changesets from all the PRs that have merged since the last release. To release the latest version of Namesake, merge this ci: Release PR into main and a workflow will kickoff to update the release tag on the repo and deploy changes to production.