From 491b41f11153ceb08f0438b7270c5a44bf402779 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marko=20Vukosavljevi=C4=87?= Date: Wed, 13 Dec 2023 11:46:15 +0100 Subject: [PATCH 1/3] Add readme template --- README.template.md | 139 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 139 insertions(+) create mode 100644 README.template.md diff --git a/README.template.md b/README.template.md new file mode 100644 index 0000000..233158a --- /dev/null +++ b/README.template.md @@ -0,0 +1,139 @@ +# [TODO:PROJECT_NAME] + +[TODO:PROJECT_DESCRIPTION] + +- [Setup](#setup) + - [Prerequisites / Dependencies](#prerequisites--dependencies) + - [Installation](#installation) + - [Post-install](#post-install) +- [Usage](#usage) + - [Running the app](#running-the-app) + - [Building the app](#building-the-app) +- [Testing](#testing) + - [Unit testing](#unit-testing) + - [End to end tests](#end-to-end-tests) + - [Code quality](#code-quality) +- [Environments](#environments) +- [Environment variables](#environment-variables) + - [List of environment variables](#list-of-environment-variables) +- [Deployment](#deployment) +- [Releases](#releases) +- [Translations](#translations) +- [Licencing](#licencing) + +## Setup + +### Prerequisites / Dependencies + +You will need to have NodeJS and NPM installed to run this application. It's recommended to use a NodeJS version manager to manage your versions. Required NodeJS versions will typically match LTS (long-term support) versions and you can check which exact version to install by checking `.node-version` file in the repository root. + +### Installation + +1. clone this repository: `git clone [TODO:GIT_LINK]` +2. install all the dependencies: `npm ci` + +### Post-install + +1. set up the [environment variables](#environment-variables) + +## Usage + +### Running the app + +To run the app, you can simply run `npm start`. This starts the application in the environment dependent on your environment setup. + +### Building the app + +To build the app you can use some of the following commands: + +``` +npm run build +npm run build:dev +npm run build:prod # builds the app for production + +``` + +## Testing + +### Unit testing + +To start the unit tests you can use one of the following commands: + +``` +npm run test +npm run test:watch # runs all tests in watch mode and without code coverage report +npm run test:watch:coverage # runs all tests in watch mode with code coverage report + +``` + +### End to end tests + +[TODO:DESCRIBE_E2E] + +### Code quality + +The following tools are used in the project to ensure code quality: + +Prettier: for consistent code formatting. +ESLint: for identifying and fixing code quality issues. +Stylelint: for identifying and fixing CSS code quality issues. +Husky: Git hooks to automate code quality checks with ESLint and Prettier + +Local code quality checks (Prettier, ESLint, and Stylelint) are run before a user can commit their code through Husky's _pre-commit_ hook, which ensures that the code pushed to Git is consistent and doesn't include any obvious issues that can be detected with static analysis. + +## Environments + +There are currently two application environments: + +1. DEV - development instance, used for testing developed features + - API: [TODO:DEV_BACKEND_API_URL] + - Frontend: [TODO:DEV_APP_URL] +2. PRODUCTION - production environment + - API: [TODO:PROD_BACKEND_API_URL] + - Frontend: [TODO:PROD_APP_URL] + +## Environment variables + +You can specify environment variables as per the guide in the [Nuts & Bolts](https://infinum.github.io/ngx-nuts-and-bolts/docs/environment-variables). + +### List of environment variables + +| Variable | Requirement | Description | +| ---------------- | ----------- | ---------------------------------------------------------- | +| API_HOST | required | API endpoint URL | +| ENV | required | Available options: development, production | +| ASSETS_BASE_HREF | optional | Specifies the base path for the static assets (default: /) | + +## Deployment + +The application deployment is managed with GitHub Actions. + +More information on the deployment process can be found in [Deployment process wiki page](TODO:GITHUB_WIKI_PAGE). + +## Releases + +Releases are handled through GitHub Releases feature and documentation for it can be found on [Release process wiki page](TODO:GITHUB_WIKI_PAGE). + +## Translations + +The application uses [Polyglot](TODO:PROJECT_POLYGLOT_LINK) for handling translations. More information can be found on the [Translations handling wiki page](TODO:GITHUB_WIKI_PAGE). + +## Licencing + +The application uses a licence header for all TypeScript files. To help out with setting this up for new files, you can install `licenser` extension. + +``` +# CMD + P +ext install licenser + +``` + +This extension will add proper license headers to each new file. + +You can also add license headers manually: + +``` +# CMD + SHIFT + P +licenser: Insert license header + +``` From d75bf378eab474a50bb28c46252c502102e386ec Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marko=20Vukosavljevi=C4=87?= Date: Tue, 27 Feb 2024 13:24:54 +0100 Subject: [PATCH 2/3] Update based on PR comments --- README.template.md | 26 +++++++++++++++++--------- 1 file changed, 17 insertions(+), 9 deletions(-) diff --git a/README.template.md b/README.template.md index 233158a..d87091e 100644 --- a/README.template.md +++ b/README.template.md @@ -14,7 +14,9 @@ - [End to end tests](#end-to-end-tests) - [Code quality](#code-quality) - [Environments](#environments) -- [Environment variables](#environment-variables) +- [Environment variables \[TODO: Remove non-applicable\]](#environment-variables-todo-remove-non-applicable) + - [React](#react) + - [Angular](#angular) - [List of environment variables](#list-of-environment-variables) - [Deployment](#deployment) - [Releases](#releases) @@ -48,8 +50,10 @@ To build the app you can use some of the following commands: ``` npm run build -npm run build:dev -npm run build:prod # builds the app for production + +# TODO: development and production builds if applicable +# npm run build:dev +# npm run build:prod ``` @@ -61,8 +65,8 @@ To start the unit tests you can use one of the following commands: ``` npm run test -npm run test:watch # runs all tests in watch mode and without code coverage report -npm run test:watch:coverage # runs all tests in watch mode with code coverage report +npm run test:watch +npm run test:coverage ``` @@ -76,10 +80,9 @@ The following tools are used in the project to ensure code quality: Prettier: for consistent code formatting. ESLint: for identifying and fixing code quality issues. -Stylelint: for identifying and fixing CSS code quality issues. Husky: Git hooks to automate code quality checks with ESLint and Prettier -Local code quality checks (Prettier, ESLint, and Stylelint) are run before a user can commit their code through Husky's _pre-commit_ hook, which ensures that the code pushed to Git is consistent and doesn't include any obvious issues that can be detected with static analysis. +Local code quality checks (Prettier, ESLint) are run before a user can commit their code through Husky's _pre-commit_ hook, which ensures that the code pushed to Git is consistent and doesn't include any obvious issues that can be detected with static analysis. ## Environments @@ -92,7 +95,13 @@ There are currently two application environments: - API: [TODO:PROD_BACKEND_API_URL] - Frontend: [TODO:PROD_APP_URL] -## Environment variables +## Environment variables [TODO: Remove non-applicable] + +### React + +You can specify your environment variables in the `.env` file based on `.env.example`. + +### Angular You can specify environment variables as per the guide in the [Nuts & Bolts](https://infinum.github.io/ngx-nuts-and-bolts/docs/environment-variables). @@ -102,7 +111,6 @@ You can specify environment variables as per the guide in the [Nuts & Bolts](htt | ---------------- | ----------- | ---------------------------------------------------------- | | API_HOST | required | API endpoint URL | | ENV | required | Available options: development, production | -| ASSETS_BASE_HREF | optional | Specifies the base path for the static assets (default: /) | ## Deployment From c35fd799178c79e14d40d3bf25008c991a958ca6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marko=20Vukosavljevi=C4=87?= Date: Mon, 4 Mar 2024 12:47:54 +0100 Subject: [PATCH 3/3] Resolve PR comments 1. link NodeJS setup to handbook guide 2. add TODO for the app start command 3. remove Licencing section --- README.template.md | 25 ++----------------------- 1 file changed, 2 insertions(+), 23 deletions(-) diff --git a/README.template.md b/README.template.md index d87091e..45a1403 100644 --- a/README.template.md +++ b/README.template.md @@ -21,13 +21,12 @@ - [Deployment](#deployment) - [Releases](#releases) - [Translations](#translations) -- [Licencing](#licencing) ## Setup ### Prerequisites / Dependencies -You will need to have NodeJS and NPM installed to run this application. It's recommended to use a NodeJS version manager to manage your versions. Required NodeJS versions will typically match LTS (long-term support) versions and you can check which exact version to install by checking `.node-version` file in the repository root. +You will need to have NodeJS and NPM installed to run this application. Use the [handbook guide](https://infinum.com/handbook/frontend/node/managing-node-npm-versions) to set up the correct NodeJS version. ### Installation @@ -42,7 +41,7 @@ You will need to have NodeJS and NPM installed to run this application. It's rec ### Running the app -To run the app, you can simply run `npm start`. This starts the application in the environment dependent on your environment setup. +To run the app, you can simply run `[TODO:NPM_START_COMMAND]`. This starts the application in the environment dependent on your environment setup. ### Building the app @@ -125,23 +124,3 @@ Releases are handled through GitHub Releases feature and documentation for it ca ## Translations The application uses [Polyglot](TODO:PROJECT_POLYGLOT_LINK) for handling translations. More information can be found on the [Translations handling wiki page](TODO:GITHUB_WIKI_PAGE). - -## Licencing - -The application uses a licence header for all TypeScript files. To help out with setting this up for new files, you can install `licenser` extension. - -``` -# CMD + P -ext install licenser - -``` - -This extension will add proper license headers to each new file. - -You can also add license headers manually: - -``` -# CMD + SHIFT + P -licenser: Insert license header - -```