diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..ece5da1 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,84 @@ +# Contributing + +Welcome! We're glad you're interested in contributing to the project. + +We welcome contributions of any kind; however, for **feature changes or additions**, please open an issue first for discussion. + +## Getting Started + +To get started, [fork this repository](https://github.com/nizewn/chessu/fork) to your GitHub account. You can then clone the repository to your local machine and create a new branch for your changes. + +```sh +git clone https://github.com/[your-username]/chessu.git +cd chessu +git checkout -b my-feature-branch +``` + +## Development + +> Node.js 18 or newer is recommended. + +This project is structured as a monorepo using npm workspaces, separated into three packages: + +- `client` - Next.js application for the front-end, deployed to [ches.su](https://ches.su) via Vercel. +- `server` - Node/Express.js application for the back-end, deployed to [server.ches.su](https://server.ches.su) via Railway. +- `types` - Shared type definitions required by the client and server. + +### Running the project + +1. Install the necessary dependencies by running `npm install` in the root directory of the project. +2. In the `server` directory, create a `.env` file for your PostgreSQL database. You can try [ElephantSQL](https://www.elephantsql.com/) or [Aiven](https://aiven.io/postgresql) for a free hosted database. + ```env + PGHOST=db.example.com + PGUSER=exampleuser + PGPASSWORD=examplepassword + PGDATABASE=chessu + ``` +3. Run the development servers with `npm run dev`. + - To run the frontend and backend servers separately, use `npm run dev -w client` and `npm run dev -w server`, respectively. +4. You can access the frontend at http://localhost:3000 and the backend at http://localhost:3001. +5. You may now make your changes and commit them to your branch. + +When adding new dependencies or running other commands from the root directory, you can specify the workspace with the `-w` flag. For example, `npm run build -w client` or `npm install express -w server`. + +### Formatting and linting + +We use ESLint and Prettier to enforce code style and formatting. Please make sure to run `npm run lint-fix` and `npm run format` before committing your changes. + +### Environment variables + +You may create a `.env` file in each package directory to set their environment variables. + +
+client + +```env +NEXT_PUBLIC_API_URL=http://localhost:3001 # replace with backend URL +``` + +
+ +
+server + +```env +CORS_ORIGIN=http://localhost:3000 # replace with frontend URL +PORT=3001 +SESSION_SECRET=randomstring # replace for security + +# PostgreSQL connection info (required) +PGHOST=db.example.com +PGUSER=exampleuser +PGPASSWORD=examplepassword +PGDATABASE=chessu +``` + +
+ +## Guidelines + +- Follow the [Code of Conduct](CODE_OF_CONDUCT.md). +- Make sure your changes are thoroughly tested. +- Keep your commits atomic and descriptive. +- Ensure that your code is formatted and linted using `npm run lint-fix` and `npm run format`. +- Make your pull requests as descriptive as possible. diff --git a/README.md b/README.md index 2065d8f..3517a2b 100644 --- a/README.md +++ b/README.md @@ -22,72 +22,6 @@ Yet another Chess web app. Live demo at [ches.su](https://ches.su). Built with Next.js 13, Tailwind CSS + daisyUI, react-chessboard, chess.js, Express.js, socket.io and PostgreSQL. -## Configuration - -> Node.js 18 or newer is recommended. - -This project is structured as a monorepo using npm workspaces, separated into three packages: - -- `client` - Next.js application for the front-end, deployed to [ches.su](https://ches.su) via Vercel. -- `server` - Node/Express.js application for the back-end, deployed to [server.ches.su](https://server.ches.su) via Railway. -- `types` - Shared type definitions for the client and server. - -For separate deployments, you may exclude the `client` or `server` directory. However, you should include the `types` folder as it contains shared type definitions that are required by both packages. - -### Environment variables - -client: - -```env -NEXT_PUBLIC_API_URL=http://localhost:3001 # replace with backend URL -``` - -server: - -```env -CORS_ORIGIN=http://localhost:3000 # replace with frontend URL -PORT=3001 -SESSION_SECRET=randomstring # replace for security - -# PostgreSQL connection info (required) -PGHOST=db.example.com -PGUSER=exampleuser -PGPASSWORD=examplepassword -PGDATABASE=chessu -``` - -You may also create a `.env` file in each package directory to set their environment variables. - -### Scripts - -For development: - -```sh -# install all dependencies, including eslint and prettier -npm install - -# concurrently run frontend and backend development servers -npm run dev - -# or run them separately -npm run dev -w client -npm run dev -w server -``` - -For production: - -```sh -# for separate deployments -npm install -w client -npm install -w server - -npm run build -w client -npm run build -w server - -npm start -w client -npm start -w server -``` - ## Contributing -Pull requests are welcome. For feature changes or suggestions, please open an issue first for discussion. +Please read our [Code of Conduct](./CODE_OF_CONDUCT.md) and [Contributing Guidelines](./CONTRIBUTING.md) before starting a pull request.