Contributor setup on a new machine

This guide assumes you are a contributor to sameeryadav05/MessageX.

1. Confirm GitHub accessCopy Anchor Link

Sign in to the GitHub account that has been granted repository access. A contributor with Write permission can push a feature branch to the upstream repository. If you only have read access, fork the repository and push your work to your fork instead.

2. Clone and installCopy Anchor Link

git clone https://github.com/sameeryadav05/MessageX.git
cd MessageX
npm ci

Use npm ci to install the exact dependency tree recorded in the root package-lock.json. Do not run npm update just to set up the repository.

3. Configure local environmentCopy Anchor Link

Review .env.compose.example, copy it to .env, and replace the example values.

Windows PowerShell:

Copy-Item .env.compose.example .env

macOS / Linux:

cp .env.compose.example .env

Keep secrets in .env. Do not commit them or paste them into issues, logs, or documentation.

4. Create a feature branchCopy Anchor Link

Check your working tree first:

git status
git branch --show-current

Then create a branch from the latest upstream main:

git switch main
git pull --ff-only origin main
git switch -c feat/your-change

Never commit directly to main. Do not discard uncommitted work to switch branches; save or commit it first.

5. Run the servicesCopy Anchor Link

Start PostgreSQL and the full containerized stack:

docker compose up -d --build

For source development, the root scripts include:

npm run dev:broker
npm run dev:dashboard

The broker's development command is provided by the @messagex/broker workspace. The dashboard runs through its Vite development server. Ensure PostgreSQL and required environment variables are available before starting the broker.

6. Build and testCopy Anchor Link

npm run build:broker
npm run test:broker
npm run build:sdk
npm run test:sdk
npm run build:dashboard

Run the relevant tests for the code you changed. Check the root README and package scripts for additional project-specific instructions.

7. Push your branchCopy Anchor Link

git add <files-you-changed>
git commit -m "feat: describe your change"
git push -u origin feat/your-change

Open a Pull Request targeting main. Keep changes focused and avoid including generated files, local databases, build output, or environment secrets.