docs: update readme and add contribution guide (#22)

* docs: update readme and add contributing

* feat(ui): update ui about

.github/workflows/ci.yml

@@ -4,9 +4,13 @@ on:
   push:
     branches:
       - 'main'
+    paths-ignore:
+      - '**.md'
   pull_request:
     branches:
       - 'main'
+    paths-ignore:
+      - '**.md'
 
 jobs:
   build:

CONTRIBUTING.md

@@ -0,0 +1,201 @@
+# Contributing to Library App
+
+As the application is just a prove-of-concept (POC), there are many rooms of improvement. We would love for you to contribute to the application and help make it even better than it is
+today! As a contributor, here are the guidelines we would like you to follow:
+
+- [Submission Guidelines](#submission-guidelines)
+- [Development Setup](#development-setup)
+- [Coding Rules](#coding-rules)
+- [Commit Message Guidelines](#commit-message-guidelines)
+
+## Submission Guidelines
+
+### Submitting a Pull Request (PR)
+
+Before you submit your Pull Request (PR) consider the following guidelines:
+
+1. Search [GitHub Pull Requests][gh_prs] for an open or closed PR
+   that relates to your submission. You don't want to duplicate effort.
+1. Fork this repository.
+1. Make your changes in a new git branch:
+
+   ```shell
+   git checkout -b my-fix-branch main
+   ```
+
+1. Create your patch, **including appropriate test cases**.
+1. Follow our [Coding Rules](#coding-rules).
+1. Run the full test suite (see [common scripts](#commonly-used-npm-scripts)),
+   and ensure that all tests pass.
+1. Commit your changes using a descriptive commit message that follows our
+   [commit message conventions](#commit). Adherence to these conventions
+   is necessary because release notes are automatically generated from these messages.
+
+   ```shell
+   git commit -a
+   ```
+
+   Note: the optional commit `-a` command line option will automatically "add" and "rm" edited files.
+
+1. Push your branch to GitHub:
+
+   ```shell
+   git push origin my-fix-branch
+   ```
+
+1. In GitHub, send a pull request to `library-app:main`.
+
+- If we suggest changes then:
+
+  - Make the required updates.
+  - Re-run all test suites to ensure tests are still passing.
+  - Rebase your branch and force push to your GitHub repository (this will update your Pull Request):
+
+    ```shell
+    git rebase main -i
+    git push -f
+    ```
+
+That's it! Thank you for your contribution!
+
+#### After your pull request is merged
+
+After your pull request is merged, you can safely delete your branch and pull the changes
+from the main (upstream) repository:
+
+- Delete the remote branch on GitHub either through the GitHub web UI or your local shell as follows:
+
+  ```shell
+  git push origin --delete my-fix-branch
+  ```
+
+- Check out the main branch:
+
+  ```shell
+  git checkout main -f
+  ```
+
+- Delete the local branch:
+
+  ```shell
+  git branch -D my-fix-branch
+  ```
+
+- Update your main with the latest upstream version:
+
+  ```shell
+  git pull --ff upstream main
+  ```
+
+## Development Setup
+
+You will need [Node.js](https://nodejs.org) version >= 10.13.0 (except for v13), [RabbitMQ](https://www.rabbitmq.com/), [MongoDB](https://www.mongodb.com/) to run all the services locally.
+
+Alternatively, you could run in Docker without intalling the dependencies explicitly.
+
+1. After cloning the repo, run:
+
+```bash
+$ npm ci
+```
+
+### Commonly used NPM scripts
+
+```bash
+# build all services
+$ npm run build:all
+
+# run the full unit tests suite
+$ npm run test
+$ npm run test:e2e
+
+# run linter
+$ npm run lint
+```
+
+## Coding Rules
+
+To ensure consistency throughout the source code, keep these rules in mind as you are working:
+
+<!--
+// We're working on auto-documentation.
+* All public API methods **must be documented**. (Details TBC). -->
+
+- All features or bug fixes **must be tested** by one or more specs (unit-tests).
+- We follow [Google's JavaScript Style Guide][js-style-guide], but wrap all code at
+  **100 characters**. An automated formatter is available (`npm run format`).
+
+## Commit Message Guidelines
+
+We have very precise rules over how our git commit messages can be formatted. This leads to **more
+readable messages** that are easy to follow when looking through the **project history**.
+
+### Commit Message Format
+
+Each commit message consists of a **header**, a **body** and a **footer**. The header has a special
+format that includes a **type**, and a **subject**:
+
+```
+<type>: <subject>
+<BLANK LINE>
+<body>
+<BLANK LINE>
+<footer>
+```
+
+The **header** is mandatory and the **scope** of the header is optional.
+
+Any line of the commit message cannot be longer than 100 characters! This allows the message to be easier
+to read on GitHub as well as in various git tools.
+
+Footer should contain a [closing reference to an issue](https://help.github.com/articles/closing-issues-via-commit-messages/) if any.
+
+```
+docs: update change log to beta.5
+fix: need to depend on latest rxjs and zone.js
+```
+
+### Revert
+
+If the commit reverts a previous commit, it should begin with `revert:`, followed by the header of the reverted commit. In the body it should say: `This reverts commit <hash>.`, where the hash is the SHA of the commit being reverted.
+
+### Type
+
+Must be one of the following:
+
+- **build**: Changes that affect the build system or external dependencies (example scopes: npm, turborepo)
+- **ci**: Changes to CI configuration files and scripts (example scopes: GitHub Action)
+- **docs**: Documentation only changes
+- **feat**: A new feature
+- **fix**: A bug fix
+- **perf**: A code change that improves performance
+- **refactor**: A code change that neither fixes a bug nor adds a feature
+- **style**: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
+- **test**: Adding missing tests or correcting existing tests
+
+### Subject
+
+The subject contains succinct description of the change:
+
+- use the imperative, present tense: "change" not "changed" nor "changes"
+- don't capitalize first letter
+- no dot (.) at the end
+
+### Body
+
+Just as in the **subject**, use the imperative, present tense: "change" not "changed" nor "changes".
+The body should include the motivation for the change and contrast this with previous behavior.
+
+### Footer
+
+The footer should contain any information about **Breaking Changes** and is also the place to
+reference GitHub issues that this commit **Closes**.
+
+**Breaking Changes** should start with the word `BREAKING CHANGE:` with a space or two newlines. The rest of the commit message is then used for this.
+
+---
+
+The contribution guide is inspired by [NestJS](https://github.com/nestjs/nest) contribution guide.
+
+[js-style-guide]: https://google.github.io/styleguide/jsguide.html
+[gh_prs]: https://github.com/ckng0221/library-app/pulls

README.md

@@ -1,47 +1,89 @@
+# Library App
+
 [![CI](https://github.com/ckng0221/library-app/actions/workflows/ci.yml/badge.svg)](https://github.com/ckng0221/library-app/actions/workflows/ci.yml)
 [![Book-CI](https://github.com/ckng0221/library-app/actions/workflows/book-ci.yml/badge.svg)](https://github.com/ckng0221/library-app/actions/workflows/book-ci.yml)
 [![Customer-CI](https://github.com/ckng0221/library-app/actions/workflows/customer-ci.yml/badge.svg)](https://github.com/ckng0221/library-app/actions/workflows/customer-ci.yml)
 [![Borrowing-CI](https://github.com/ckng0221/library-app/actions/workflows/borrowing-ci.yml/badge.svg)](https://github.com/ckng0221/library-app/actions/workflows/borrowing-ci.yml)
 [![Payment-CI](https://github.com/ckng0221/library-app/actions/workflows/payment-ci.yml/badge.svg)](https://github.com/ckng0221/library-app/actions/workflows/payment-ci.yml)
 [![UI-CI](https://github.com/ckng0221/library-app/actions/workflows/ui-ci.yml/badge.svg)](https://github.com/ckng0221/library-app/actions/workflows/ui-ci.yml)
 
-# Library App
+## Description
 
-A library app microservice in a monorepo setup, created using [NestJS](https://nestjs.com/).
+A prove-of-concept (POC) library application designed in a [microservice](https://microservices.io/) architecture. The application is built with [Typescript](https://www.typescriptlang.org/) in a [monorepo](https://monorepo.tools/) project setup.
 
-There are several main services, including:
+The microservice app consists of the following services:
 
 - book
 - borrowing
 - customer
 - payment
 - view
 
-To run each of the services, could run using by:
+## Tech stacks
 
-```bash
-# Use nest cli directly
-# Eg. next start <service_name>
-nest start book
+Backend:
+
+- Server Framework: [NestJS](https://nestjs.com/)
+- Database: [MongoDB](https://www.mongodb.com/)
+- Message broker: [RabbitMQ](https://www.rabbitmq.com/)
+
+Frontend:
+
+- Framework: [React](https://react.dev/)
+- Bundler: [Vite](https://vitejs.dev/)
+- UI library: [Material UI](https://mui.com/)
+
+Build:
+
+- CI platform: [GitHub Actions](https://react.dev/)
+- Build system: [Turborepo](https://turbo.build/)
+- Multi-container tool: [Docker compose](https://docs.docker.com/compose/)
+
+## Getting started
+
+To run the application locally, it would require RabbitMQ and MongoDB to be installed on the client's machine.
+Alternatively, you could [run all the services in docker](#run-with-docker-and-docker-compose) without install RabbitMQ and MongoDB locally.
 
-# Use npm scripts
+### Run without docker
+
+To test/build/run individual service:
+
+```bash
 # Eg. npm run <script> --  <service_name>
-npm run start book
-npm run start:dev book
-npm run build book
+npm run test book # unit test
+npm run test:e2e book # end-to-end test
+npm run build book # build
+npm run start:dev book # dev mode
+npm run start book # prod mode
+```
+
+To test/build/run all services all at once:
+
+```bash
+npm run test # ran all unit tests
+npm run test:e2e # ran all end-to-end tests
+npm run build:all # build all
+npm run start:dev:all # start all services in dev mode
+npm run start:all # start all services in production mode
 ```
 
-For view service, would need to build the React application first, to produce the static files before serving.
-Could run the following to build and serve in 1 command: 
+To run UI for React in dev mode only:
+
 ```bash
-npm run start:dev:view
+npm run dev:ui
 ```
 
-The microservice requires MongoDB and RabbitMQ.
-Could run on docker images for these services, if do not have them installed.
-To run all the services in docker, could run:
+### Run with Docker and Docker Compose
 
 ```bash
 # At project root
-docker-compose up -d
+npm run start:dev:docker # run via npm scripts
+# Run directly via docker compose
+docker compose up -d # start all containers in detached mode
+docker compose up -d --build # forced build all containers
+docker compose down # shut down all containers
 ```
+
+## Contribution
+
+For contribution, please refer the [contribution guide](CONTRIBUTING.md).