From 86291ce213fd20da276b42b0614c7e9cd578f221 Mon Sep 17 00:00:00 2001 From: Amandus Butzer Date: Fri, 2 Aug 2024 14:55:57 +0200 Subject: [PATCH 01/12] docs(README): fix typos --- README.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index fc28fe0b0..b52b04b24 100755 --- a/README.md +++ b/README.md @@ -6,13 +6,13 @@ This application implements a map client for the [openrouteservice API](https:// Single Page Application (SPA). It is a base application that can be used for multiple purposes, customized via configurations and extended via plug-ins. -The base application is using VueJS, Vuetify and a set of custom components, directives and services. +The base application is using Vue.js, Vuetify and a set of custom components, directives and services. The structure uses a feature-by-folder design, allowing view, code and translation elements to be contained in a folder. This app uses single file components and others non-native javascript code that are transpiled to native javascript during the build process. Therefore, the app needs to be compiled before running it either in dev or production mode. -The VueJS components allow a better code organization, weak and clear coupling between components and an easier +The Vue.js components allow a better code organization, weak and clear coupling between components and an easier code understanding. ![ORS map client](docs/ors-map-client.png?raw=true "ORS map client") @@ -158,7 +158,7 @@ Meaning, that the front-end (this app) is decoupled from the back-ends (ORS API The app load cycle follows these steps: 1. Execute the `main.js` file and add global extensions, mixins components and external libs. The file `main.js` also includes the main files of the router, vuex-store and i18n-translations, which will internally load all `.router.js` ,`.store.js` and `.i18n.js` files from sub-folders. -2. `main.js` will run a request to get necessary data from a service and then create a VueJS app instance and load the `App.vue`. At this point `AppHooks` is set up and attached to the main VueJS instance and then the `appLoaded` hook is called. +2. `main.js` will run a request to get necessary data from a service and then create a Vue.js app instance and load the `App.vue`. At this point `AppHooks` is set up and attached to the main Vue.js instance and then the `appLoaded` hook is called. 3. `App.vue` includes all basic navigation components, like menu, sidebar, footer etc. 4. After loading all routes (including the ones in the `pages` sub folder) the page with the `/` route (`Maps.vue`) will also be rendered in the `` slot in `App.vue` component. @@ -218,7 +218,7 @@ The app will automatically load: ### Reserved methods and accessors -All the VueJS components created (including the fragments) will have, by default, the following methods/accessors +All the Vue.js components created (including the fragments) will have, by default, the following methods/accessors defined in the main vue instance app: - `showMessage (msg, theme, options)` - shows a message using the toaster with specified theme and options @@ -340,7 +340,7 @@ follow the steps below. - the new language placeholder object to the messages object (e.g. `, 'fr-fr': {}`). - the result of the new language building to the previously created message object - (e.g. `i18n.messages['fr-fr'] = frFRTranslations.build()`. + (e.g. `i18n.messages['fr-fr'] = frFRTranslations.build()`). - Save all the files changed and rebuild the application. @@ -364,7 +364,7 @@ _webpack config_ (settings -> Languages & Frameworks -> JavaScript -> Webpack) t `{path to ors-map-client}/build/webpack.base.conf.js` to resolve file paths correctly. To debug the application you must run it in [`dev` mode](#set-up-and-run). -For better debugging in your browser install the [VueJS devtools](https://github.com/vuejs/vue-devtools#installation) +For better debugging in your browser install the [Vue.js devtools](https://github.com/vuejs/vue-devtools#installation) extension. After doing that, open the application in the browser and press F12 and select the tab `Console`, `Vue` or `Sources` (and then expand e.g.: `webpack://src`). From 7e1a05c3ea4db6ecf968a86428a7df12e29c06a4 Mon Sep 17 00:00:00 2001 From: Amandus Butzer Date: Fri, 2 Aug 2024 15:57:56 +0200 Subject: [PATCH 02/12] docs(README): remove Bitly config setup, since it's not working --- README.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/README.md b/README.md index b52b04b24..ca418f8f5 100755 --- a/README.md +++ b/README.md @@ -70,8 +70,6 @@ first. 2. Set the app-config.js values for: - `orsApiKey` - ORS API key to be used when ot running the app from localhost or ors valid domains -- `bitlyApiKey` - the Bitly key (used to shorten the share URL) -- `bitlyLogin` - the Bitly login (used to shorten the share URL) 3. The ORS menu is loaded/used by default. If you want to use a custom menu, have a look in the `hooks-example.js`. From eb5898bf7ea2eb921c5a98e3daeb99a93231a102 Mon Sep 17 00:00:00 2001 From: Amandus Butzer Date: Fri, 2 Aug 2024 18:26:52 +0200 Subject: [PATCH 03/12] docs(README): update and adjust contribution sections --- README.md | 112 +++++++++++++++--------------------------------------- 1 file changed, 31 insertions(+), 81 deletions(-) diff --git a/README.md b/README.md index ca418f8f5..068fc9e57 100755 --- a/README.md +++ b/README.md @@ -421,9 +421,26 @@ clarity be named the same e.g. `../support/__tests__/utils.cy.js` for `../suppor End-to-end tests should be created in `./cypress/e2e/test-name.cy.js` +### Report a bug +If you identified a bug, please [create an issue](https://github.com/GIScience/ors-map-client/issues/new) with thorough description +and steps to reproduce it (e.g. URL, Screenshot or Screen recording). Feel free to [contribute a fix](#contribute) + +### Feature improvements +If you have an idea for a new feature or want to improve an existing one, please also +[create an issue](https://github.com/GIScience/ors-map-client/issues/new) first to discuss the idea. +We are happy if you also want to [contribute](#contribute) a pull request. + ### Contribute -#### pre-commit git hooks +Make sure to [set up](#set-up-and-run) and [configure](#configuration) the project, branch of current `main` and prefix +your branch name with `feat/` for features and `fix/` for bug fixes e.g. +```sh +git switch -c feat/leaflet-control-for-statistics +# or +git switch -c fix/map-moving-all-the-time +``` + +#### set up pre-commit git hooks We use `pre-commit` to make sure contributions have the same basic quality. Before you commit make sure that your commit satisfies all `pre-commit` checks. @@ -436,89 +453,22 @@ pre-commit install --hook-type commit-msg --hook-type pre-push --hook-type pre-c pre-commit run --all ``` -#### Commits and versioning - -- This app uses the `commitizen` plugin to generate standardized commit types/messages. After applying any change in a feature branch, use `git add .` and then `pnpm commit` (instead of `git commit ...`) -- The plugin `standard-version` is used to generate changelog entries, version tag and to bump the app version in package.json. - -Deployment flow: - -1. Apply the changes in a feature branch and test it locally - - _Important_: to run the tests, `src/config/app-config.js` must contain: - -- `orsApiKey`: 'a-valid-ors-api-key-here', -- `useUserKey`: true, - -By default, `src/config/app-config.js` is ignored by git. So, the changes are just local and used to run the tests. - -```sh -# Run automated tests -pnpm test:ci -``` - -_Important:_ Besides the automated tests, some manual/human tests are also recommended - -2. Once the feature is ready, merge it to `master`, and run the tests - - ```sh - git checkout master - git merge feature/ - # Run automated tests after merge - pnpm test - ``` - -3. If the tests pass, create a release - - ```sh - # Create a release. This will : - # - bump the app version, - # - generate a new release commit - # - create a new git tag with the app version - # - Create an entry in CHANGELOG.md - pnpm release - ``` - -4. Push the changes applied to master - - _Important_: the release command will output a command, but We `DON'T USE the whole outputted command`, since there is no npm package to be published. - - ```sh - # The command outputted is expected to be: - # `git push --follow-tags origin master && pnpm publish` - - # We must use/run only - git push --follow-tags origin master - - # Once you push it, the automated tests will be triggered on Github actions - # Check the automated tests results on https://github.com/GIScience/ors-map-client/actions - ``` - -_For more details about `commitizen` and `standard-version` see [this article](https://medium.com/tunaiku-tech/automate-javascript-project-versioning-with-commitizen-and-standard-version-6a967afae7)_ and [standard-version documentation](https://github.com/conventional-changelog/standard-version) - -#### Branch policy - -The `master` branch is used as the stable and most updated branch. Any new feature goes to feature branch, then it is tested, committed and finally merged into `master`. So, master has always the latest version and the production version. -Considering this, any merge request must be done targeting `master`. - -Like almost every team, we have limited workforce, and we have to define priorities. - -`Bugs`: -If you think you have identified any bug and that you can help to fix it, please create an issue first, instead of directly submitting a push request. So the people involved will have the opportunity to discuss it. +#### Commits -`New features`: +- This app uses [conventional commit syntax](https://www.conventionalcommits.org/en/v1.0.0/#summary) to automate + changelog entries. + You can use e.g. [conventional-commits-plugin](https://plugins.jetbrains.com/plugin/13389-conventional-commit) for + JetBrains IDEs or a global installation of the [commitizen npm package](https://github.com/commitizen/cz-cli) to help + you with the syntax. -If you want to contribute by adding a new feature or improve an existing one, please also create an issue. -We do want contributions, and the community effort is very important to us, but features may add complexity and future -maintenance effort. -Because of this, we have also to analyze the trade-off of such contributions. -We just have to decide about them together before the hands on. -This approach is intended to create cohesion and keep the project sustainable. +> Note: +> Don't add `closing` or `fixes` keywords in commits but rather tag the issue in the pull request that solves it. +> This avoids multiple references in the issues after your branch is rebased on newer changes. ### Additional documentation -There are additional documents that are part of the software documentation. they are in the folder `/docs` and are listed below: +There is additional software documentation in the `/docs` folder: -- [docs/dynamic-inputs.md](docs/dynamic-inputs.md) - describe how the inputs are rendered using a custom engine and not hard-coded -- [docs/search-results-criteria.md](docs/search-results-criteria.md) - explains what are the criteria for the search results -- [docs/plugins.md](docs/plugins.md) - explains how the plugins can be added to the maps client +- [docs/dynamic-inputs.md](docs/dynamic-inputs.md) - describes how the inputs are rendered using a custom engine +- [docs/search-results-criteria.md](docs/search-results-criteria.md) - explains the criteria for search results +- [docs/plugins.md](docs/plugins.md) - explains how to add plugins From 9f56fef6fe81633c5d4cf3eb604bfd8c2fd24557 Mon Sep 17 00:00:00 2001 From: Amandus Butzer Date: Fri, 2 Aug 2024 18:30:08 +0200 Subject: [PATCH 04/12] docs(README): add sections for releasing and deployment --- README.md | 38 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/README.md b/README.md index 068fc9e57..54f2f0241 100755 --- a/README.md +++ b/README.md @@ -465,6 +465,44 @@ pre-commit run --all > Don't add `closing` or `fixes` keywords in commits but rather tag the issue in the pull request that solves it. > This avoids multiple references in the issues after your branch is rebased on newer changes. +### Releasing a new Version + +1. Create a `chore/release-v*.*.*` branch with the new version from `main` branch (use [semantic versioning](https://semver.org/)) + ```sh + git checkout main && git switch -c chore/release-v*.*.* + ``` +2. Run the release script to bump version, create changelog entries and release tag + ```sh + pnpm release + ``` +3. Make sure the changelog & version is what you expected and adjust if needed + - adjust branch name: `git branch -m chore/release-` + - adjust changelog or version in files. Then amend commit and re-tag: + ```sh + git commit --amend + git tag -fa v*.*.* -m 'v*.*.*' + ``` +4. Push the release branch to remote + ```sh + git push --set-upstream origin $(git_current_branch) + ``` +5. Click on the link to open a pull request for the release branch, create it and link relevant issues + +> Note: +Pre-commit hooks and test:ci tasks are run for every pull request and any change to it. + +### Deployment + +Deployments happen automatically if the conditions for the [environment](https://github.com/GIScience/ors-map-client/settings/environments) are met: + +| Environment | Condition | Target | Workflow dispatch | +|-------------|---------------------------------------------------------------|-------------------------------------------|--------------------| +| Staging | open pull request for / push to `chore/release-v*.*.*` branch | https://maps-staging.openrouteservice.org | :heavy_check_mark: | +| Production | merge `chore/release-v*.*.*` branch to `main` | https://maps.openrouteservice.org | :heavy_check_mark: | +| HEAL | push to `heal` branch | https://heal.openrouteservice.org | :no_entry_sign: | + +Use the workflow dispatch to deploy e.g. a feature branch to staging or an intermediate state of `main` to production. + ### Additional documentation There is additional software documentation in the `/docs` folder: From 09c41a9f6de53946aab57d55ee0673c36c92f7a4 Mon Sep 17 00:00:00 2001 From: Amandus Butzer Date: Fri, 2 Aug 2024 18:31:48 +0200 Subject: [PATCH 05/12] docs(README): remove section links there is an auto-generated TOC/Outline available for .md files on GitHub --- README.md | 17 ----------------- 1 file changed, 17 deletions(-) diff --git a/README.md b/README.md index 54f2f0241..3dc9c632b 100755 --- a/README.md +++ b/README.md @@ -17,23 +17,6 @@ code understanding. ![ORS map client](docs/ors-map-client.png?raw=true "ORS map client") -## Sections - -- [Set up and run](#set-up-and-run) -- [App folders](#app-folders) -- [App flow overview](#app-flow-overview) -- [Feature-by-folder design](#feature-by-folder-design) -- [Reserved methods and accessors](#reserved-methods-and-accessors) -- [pages](#pages) -- [Configuration, theming, customization and extension](#configuration-theming-customization-and-extension) -- [Add language](#add-language) -- [Menu](#menu) -- [Debug](#debug) -- [Build and deploy](#build-and-deploy) -- [Tests](#tests) -- [Contribute](#contribute) -- [Additional documentation](#additional-documentation) - ### Set up and run The app can be run with `docker`, `docker-compose`, and `natively`. From d6af55c5d2506cf0d18e51623678dfc43fb60a8c Mon Sep 17 00:00:00 2001 From: Amandus Butzer Date: Fri, 2 Aug 2024 18:43:45 +0200 Subject: [PATCH 06/12] docs(README): adjust build and deploy section --- README.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 3dc9c632b..b83ffff63 100755 --- a/README.md +++ b/README.md @@ -363,12 +363,11 @@ cd / pnpm build ``` -_Important:_ to run the built application you have to set up a web server and put this repository (after the build) -there. -The `index.html` at the root of this repository will load the app. - -For a detailed explanation on how webpack works, check out the [guide](http://vuejs-templates.github.io/webpack/) and -[docs for vue-loader](http://vuejs.github.io/vue-loader). +The built files are meant to be served by a web server like nginx or apache. +You can try if everything works locally e.g. with: +```sh +pnpx http-server . +``` ### Tests @@ -493,3 +492,6 @@ There is additional software documentation in the `/docs` folder: - [docs/dynamic-inputs.md](docs/dynamic-inputs.md) - describes how the inputs are rendered using a custom engine - [docs/search-results-criteria.md](docs/search-results-criteria.md) - explains the criteria for search results - [docs/plugins.md](docs/plugins.md) - explains how to add plugins + +For a detailed explanation on how webpack works, check out the [guide](http://vuejs-templates.github.io/webpack/) and +[docs for vue-loader](http://vuejs.github.io/vue-loader). From 97df0477c5c4db2e5e01ab48cf5189d07259f75c Mon Sep 17 00:00:00 2001 From: Amandus Butzer Date: Fri, 2 Aug 2024 18:54:18 +0200 Subject: [PATCH 07/12] docs: extract project structure to additional doc file --- README.md | 124 -------------------------------------- docs/project-structure.md | 123 +++++++++++++++++++++++++++++++++++++ 2 files changed, 123 insertions(+), 124 deletions(-) create mode 100644 docs/project-structure.md diff --git a/README.md b/README.md index b83ffff63..6fdfcd8cf 100755 --- a/README.md +++ b/README.md @@ -110,117 +110,6 @@ pnpm dev # This will start a standalone http node server and the host and port to access it will be displayed ``` -### App folders - -App folder structure under `src`: - -- `assets` - images and icons storage -- `common` - available mixins, http client, main menu, Vue with Vuetify and theme -- `directives` - custom directives -- `filters` - custom filters -- `fragments` - all app fragments used by pages -- `i18n` - internationalization resources -- `models` - models used to deal transport ors response data and deals with app state and transitions -- `pages` - app pages (currently only the `maps` page is available) -- `resources` - support files like the loader lib, definitions and options used to process requests and responses -- `router` - router component based on vue-router components -- `store` - app store definitions -- `support` - support utilities, like geo-utils, ors-api-runner, routes-resolver and app modes - -### App flow overview - -This is a Single Page Application (SPA). This means that the client app is loaded in the browser and defines which -components and pages are processed based on the browser URL. -The app watches every change in the browser URL and updates its state based on that. -These URL changes don't trigger a request to the back-end directly, but the components loaded/updated will decide which -requests must be run to load the required data. -Meaning, that the front-end (this app) is decoupled from the back-ends (ORS API and ORS website) - -The app load cycle follows these steps: - -1. Execute the `main.js` file and add global extensions, mixins components and external libs. The file `main.js` also includes the main files of the router, vuex-store and i18n-translations, which will internally load all `.router.js` ,`.store.js` and `.i18n.js` files from sub-folders. -2. `main.js` will run a request to get necessary data from a service and then create a Vue.js app instance and load the `App.vue`. At this point `AppHooks` is set up and attached to the main Vue.js instance and then the `appLoaded` hook is called. -3. `App.vue` includes all basic navigation components, like menu, sidebar, footer etc. -4. After loading all routes (including the ones in the `pages` sub folder) the page with the `/` route (`Maps.vue`) will - also be rendered in the `` slot in `App.vue` component. - -Data flow, state and requests to services, in a simplified view, happens as follows: - -- The app is loaded - 1. the API data are fetched from ORS website service and if `appConfig.appMenu.useORSMenu` is **true**, the menu items - are loaded in `src/main.js` using `src/app-loader.js`. - 2. the app `mode` is defined based on the matching URL in the `maps.route.js` - 3. the `maps` page, uses the app mode utility to define the app state using the current `mode`. - This utility will also populate the values of the `ors-map-filters` based on the URL and build the `AppRouteData` - (in src/models/app-route-data.js). - 4. based on the app mode/state certain components are activated/displayed - 5. Every component, once activated, may use the data in `src/config/ors-map-filters` to render its elements and may - run requests to the ORS api using the `src/support/ors-api-runner`. - Once the request succeed, the response data will be used to fill the `MapViewData` object. - 6. Once an input is changed the app goes to a new URL and this makes the flow restart at the step 2. - 7. If a component changes the `MapViewData` model, it emits an event to the `maps` page, that passes the current - `MapViewData` object to the `MapView` component. - 8. Interactions via `MapView` may result in events sent back to `maps` page, that may notify other child components, - that in their turn may change the URL and trigger the step 2 again. - 9. Several app hooks are called during the app flow, and it is possible to listen to these hooks and run custom code - to modify some app behavior. - The available hooks are listed in `src/config-examples/hooks-example.js` and must be coded in `src/config/hooks.js`. - -### Feature-by-folder design - -This app uses feature by folder components and predefined folders where the business code should be placed in. -Example of this design usage: - -Page: - -- my-page-name (folder) - - MyPageName.vue (main VueJS component file) - - my-page-name.css (styles for the page, included by the MyPageName.vue component) - - my-page-name`.store.js` (Vuex store module for the page, included by the store/store.js loader) - - my-page-name`.route.js` (route to reach this page, included by the router/index loader) - - i18n (folder) - - my-page-name`.i18n.en.js` (in this example containing the EN resources for the page) - -Component: - -- my-fragment-name (folder under `src/fragments/`) - - - MyFragmentName.vue (main VueJS component file) - - my-fragment-name.css (styles for the page, included by the MyFragmentName.vue component) - - my-fragment-name`.store.js` (Vuex store module for the fragment, included by the store/store.js loader) - - i18n (folder) - - my-fragment-name`.i18n.en.js` (in this example containing the EN resources for the component) - -The app will automatically load: - -- all the locale resources in i18n folder ending with `.i18n.*.js` where `*` is the locale -- the defined routes in files ending with `.routes.js` -- the store definitions in files ending with `.store.js` - -### Reserved methods and accessors - -All the Vue.js components created (including the fragments) will have, by default, the following methods/accessors -defined in the main vue instance app: - -- `showMessage (msg, theme, options)` - shows a message using the toaster with specified theme and options - -- `showError (msg, options)` - shows an error message using the toaster with the specified options - -- `showWarning (msg, options)` - shows a warning message using the toaster with the specified options - -- `showInfo (msg, options)` - shows an info message using the toaster with the specified options - -- `showSuccess (msg, options)` - shows a success message using the toaster with the specified options - -- `confirmDialog (title, text, options)` - shows a confirm-dialog with the specified title, text and options and returns - a promise. If the user clicks `yes`, the promise will be resolved, if s/he clicks on `no`, the promise will be rejected. - -- `$store` - accessor to app vuex-store - -### Pages - -- `maps` - the page where the user can search places, routes and create isochrones. - ### Configuration, theming, customization and extension The map client app can be configured, customized and extended. Several aspects can be defined/changed in order to @@ -325,19 +214,6 @@ follow the steps below. - Save all the files changed and rebuild the application. -### Menu - -The menu displayed in the header and in the sidebar (low resolution and mobile devices) is loaded from the ORS website -back-end and adjusted to be shown according the resolution. - -The menu items are fetched on the app load (`src/app-loader.js`). -It dispatches the store `fetchMainMenu` and `@/common/main-menu.js` retrieves the menu that uses -`@/support/menu-manager.js` and `@/support/model-service.js`. -Once the items from the back-end are loaded, `MenuManager` adds or removes custom items and defines icons for sidebar -items. -The items displayed on the menu can be changed by running custom code on the `loadMenuItems` and/or the -`modifyMenu` hooks. Check the `/src/config-example/hooks-example.js` to see more details. - ### Debug If you are using [WebStorm](https://www.jetbrains.com/webstorm/download) you should set the diff --git a/docs/project-structure.md b/docs/project-structure.md new file mode 100644 index 000000000..def6c19fc --- /dev/null +++ b/docs/project-structure.md @@ -0,0 +1,123 @@ +# Project structure + +App folder structure under `src`: + +- `assets` - images and icons storage +- `common` - available mixins, http client, main menu, Vue with Vuetify and theme +- `directives` - custom directives +- `filters` - custom filters +- `fragments` - all app fragments used by pages +- `i18n` - internationalization resources +- `models` - models used to deal transport ors response data and deals with app state and transitions +- `pages` - app pages (currently only the `maps` page is available) +- `resources` - support files like the loader lib, definitions and options used to process requests and responses +- `router` - router component based on vue-router components +- `store` - app store definitions +- `support` - support utilities, like geo-utils, ors-api-runner, routes-resolver and app modes + +## App flow overview + +This is a Single Page Application (SPA). This means that the client app is loaded in the browser and defines which +components and pages are processed based on the browser URL. +The app watches every change in the browser URL and updates its state based on that. +These URL changes don't trigger a request to the back-end directly, but the components loaded/updated will decide which +requests must be run to load the required data. +Meaning, that the front-end (this app) is decoupled from the back-ends (ORS API and ORS website) + +The app load cycle follows these steps: + +1. Execute the `main.js` file and add global extensions, mixins components and external libs. The file `main.js` also includes the main files of the router, vuex-store and i18n-translations, which will internally load all `.router.js` ,`.store.js` and `.i18n.js` files from sub-folders. +2. `main.js` will run a request to get necessary data from a service and then create a Vue.js app instance and load the `App.vue`. At this point `AppHooks` is set up and attached to the main Vue.js instance and then the `appLoaded` hook is called. +3. `App.vue` includes all basic navigation components, like menu, sidebar, footer etc. +4. After loading all routes (including the ones in the `pages` sub folder) the page with the `/` route (`Maps.vue`) will + also be rendered in the `` slot in `App.vue` component. + +Data flow, state and requests to services, in a simplified view, happens as follows: + +- The app is loaded + 1. the API data are fetched from ORS website service and if `appConfig.appMenu.useORSMenu` is **true**, the menu items + are loaded in `src/main.js` using `src/app-loader.js`. + 2. the app `mode` is defined based on the matching URL in the `maps.route.js` + 3. the `maps` page, uses the app mode utility to define the app state using the current `mode`. + This utility will also populate the values of the `ors-map-filters` based on the URL and build the `AppRouteData` + (in src/models/app-route-data.js). + 4. based on the app mode/state certain components are activated/displayed + 5. Every component, once activated, may use the data in `src/config/ors-map-filters` to render its elements and may + run requests to the ORS api using the `src/support/ors-api-runner`. + Once the request succeed, the response data will be used to fill the `MapViewData` object. + 6. Once an input is changed the app goes to a new URL and this makes the flow restart at the step 2. + 7. If a component changes the `MapViewData` model, it emits an event to the `maps` page, that passes the current + `MapViewData` object to the `MapView` component. + 8. Interactions via `MapView` may result in events sent back to `maps` page, that may notify other child components, + that in their turn may change the URL and trigger the step 2 again. + 9. Several app hooks are called during the app flow, and it is possible to listen to these hooks and run custom code + to modify some app behavior. + The available hooks are listed in `src/config-examples/hooks-example.js` and must be coded in `src/config/hooks.js`. + +## Feature-by-folder design + +This app uses feature by folder components and predefined folders where the business code should be placed in. +Example of this design usage: + +Page: + +- my-page-name (folder) + - MyPageName.vue (main VueJS component file) + - my-page-name.css (styles for the page, included by the MyPageName.vue component) + - my-page-name`.store.js` (Vuex store module for the page, included by the store/store.js loader) + - my-page-name`.route.js` (route to reach this page, included by the router/index loader) + - i18n (folder) + - my-page-name`.i18n.en.js` (in this example containing the EN resources for the page) + +Component: + +- my-fragment-name (folder under `src/fragments/`) + + - MyFragmentName.vue (main VueJS component file) + - my-fragment-name.css (styles for the page, included by the MyFragmentName.vue component) + - my-fragment-name`.store.js` (Vuex store module for the fragment, included by the store/store.js loader) + - i18n (folder) + - my-fragment-name`.i18n.en.js` (in this example containing the EN resources for the component) + +The app will automatically load: + +- all the locale resources in i18n folder ending with `.i18n.*.js` where `*` is the locale +- the defined routes in files ending with `.routes.js` +- the store definitions in files ending with `.store.js` + +## Reserved methods and accessors + +All the Vue.js components created (including the fragments) will have, by default, the following methods/accessors +defined in the main vue instance app: + +- `showMessage (msg, theme, options)` - shows a message using the toaster with specified theme and options + +- `showError (msg, options)` - shows an error message using the toaster with the specified options + +- `showWarning (msg, options)` - shows a warning message using the toaster with the specified options + +- `showInfo (msg, options)` - shows an info message using the toaster with the specified options + +- `showSuccess (msg, options)` - shows a success message using the toaster with the specified options + +- `confirmDialog (title, text, options)` - shows a confirm-dialog with the specified title, text and options and returns + a promise. If the user clicks `yes`, the promise will be resolved, if s/he clicks on `no`, the promise will be rejected. + +- `$store` - accessor to app vuex-store + +## Pages + +- `maps` - the page where the user can search places, routes and create isochrones. + +## Menu + +The menu displayed in the header and in the sidebar (low resolution and mobile devices) is loaded from the ORS website +back-end and adjusted to be shown according the resolution. + +The menu items are fetched on the app load (`src/app-loader.js`). +It dispatches the store `fetchMainMenu` and `@/common/main-menu.js` retrieves the menu that uses +`@/support/menu-manager.js` and `@/support/model-service.js`. +Once the items from the back-end are loaded, `MenuManager` adds or removes custom items and defines icons for sidebar +items. +The items displayed on the menu can be changed by running custom code on the `loadMenuItems` and/or the +`modifyMenu` hooks. Check the `/src/config-example/hooks-example.js` to see more details. From 2aa1e9cd839ff8119c337fd2943a05dddc791eeb Mon Sep 17 00:00:00 2001 From: Amandus Butzer Date: Fri, 2 Aug 2024 19:05:41 +0200 Subject: [PATCH 08/12] docs(README): fix heading levels and syntax --- README.md | 39 +++++++++++++++++++-------------------- 1 file changed, 19 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index 6fdfcd8cf..5552dc0c2 100755 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@ code understanding. ![ORS map client](docs/ors-map-client.png?raw=true "ORS map client") -### Set up and run +## Set up and run The app can be run with `docker`, `docker-compose`, and `natively`. @@ -29,36 +29,35 @@ git clone https://github.com/GIScience/ors-map-client.git cd ors-map-client ``` -##### Configure +### Configure In order to run the app either with `docker`, `docker-compose`, or `native`, you have to configure you application first. 1. Copy the files in the `src/config-example` to `src/config`, without `-example` in their names. The files are: -- app-config-`example`.js => **app-config.js** -- ors-map-filters`-example`.js => **ors-map-filters.js** -- layer-zoom-mapping`-example`.js => **layer-zoom-mapping.js** -- hooks`-example`.js => **hooks.js** -- theme`-example`.js => **theme.js** -- default-map-settings`-example`.js => **default-map-settings.js** -- settings-options`-example`.js => **settings-options.js** + - app-config-`example`.js => **app-config.js** + - ors-map-filters`-example`.js => **ors-map-filters.js** + - layer-zoom-mapping`-example`.js => **layer-zoom-mapping.js** + - hooks`-example`.js => **hooks.js** + - theme`-example`.js => **theme.js** + - default-map-settings`-example`.js => **default-map-settings.js** + - settings-options`-example`.js => **settings-options.js** - If you are using a linux/unix compatible terminal, you can do that by running: + If you are using a linux/unix compatible terminal, you can do that by running: - ```sh - cd src && cp config-examples/* config && for i in config/*-example.js; do mv -- "$i" "${i%-example.js}.js"; done - ``` - -2. Set the app-config.js values for: + ```sh + cd src && cp config-examples/* config && for i in config/*-example.js; do mv -- "$i" "${i%-example.js}.js"; done + ``` -- `orsApiKey` - ORS API key to be used when ot running the app from localhost or ors valid domains +2. Set the app-config.js values for `orsApiKey` to be used when not running the app from valid ors domains 3. The ORS menu is loaded/used by default. If you want to use a custom menu, have a look in the `hooks-example.js`. -The filters, theme and hooks of the map client can be customized if needed. +The filters, theme and hooks of the map client can be [customized](#configuration-theming-customization-and-extension) +if needed. -##### Run with `Docker` +### Run with `Docker` ```shell # Build the image @@ -73,7 +72,7 @@ docker logs --follow ors-map-client The app should now be running at http://127.0.0.1:8080. -##### Run with `docker-compose` +### Run with `docker-compose` ```shell # Build and run the image @@ -85,7 +84,7 @@ docker-compose logs -ft The app should now be running at http://127.0.0.1:8080. -##### Run `natively` +### Run `natively` Run the app locally without docker in three steps: set the environment up, and define a configuration file. From ec472aeda02ac5037576653fc4750bbaede3706b Mon Sep 17 00:00:00 2001 From: Amandus Butzer Date: Fri, 2 Aug 2024 19:09:40 +0200 Subject: [PATCH 09/12] docs(README): reorder sections --- README.md | 241 +++++++++++++++++++++++++++--------------------------- 1 file changed, 121 insertions(+), 120 deletions(-) diff --git a/README.md b/README.md index 5552dc0c2..ef7e6913f 100755 --- a/README.md +++ b/README.md @@ -109,126 +109,6 @@ pnpm dev # This will start a standalone http node server and the host and port to access it will be displayed ``` -### Configuration, theming, customization and extension - -The map client app can be configured, customized and extended. Several aspects can be defined/changed in order to -disable features, customize visual identity and change/extend its features/behaviors. -It is also possible to add custom plug-ins to the app and subscribe to hooks, listen and emit events. -The items of the menu can also be customized via hooks. - -It is possible to define your custom settings and plug-ins and keep getting updates from the ORS repository because -the `src/plugins` and `src/config` folders are not versioned. -To keep the original ors-map-client as a secondary repository, do the following: - -```sh -# Rename the original remote -git remote rename origin ors-map-client-origin - -# Add your remote as the origin one -git remote add origin - -# Set your new origin as the default upstream -git branch --set-upstream-to=origin/master -``` - -After doing this we recommend you to remove from `.gitignore` the lines that tell git to ignore the folders -`/src/config`, `src/plugins` and eventually `/static`. -Then, run the initial push to the just defined new origin repository, with the following command: - -```sh -git push -u origin master -``` - -The ways to change/extend the app are: - -1. Define custom settings (see files in `src/config`) that will change the standard way that the app works. -1. Add hook listeners in `src/config/hooks.js` and run custom code inside those hooks -1. Create a plug-in that has its methods linked to hooks called during the app flow - (see `src/plugins/example-plugin/`) - -#### Configuration - -It is possible to configure/disable some app features and behaviors by changing the values -of the `src/config/app-config.js`. It is also possible to change the app theme/colors by changing the values of -`src/config/theme.js`. -The app logo can also be changed in the `src/config/app-config` file. -The available filters/options to be used in the services are defined in the `src/config/ors-map-filters.js`. -They can be adjusted according the needs. Other files can be used to adjust app configurations are the -`layer-zoom-mapping.js`, `settings-options.js` and the `default-map-settings.js`. - -#### Plug-ins - -It is possible to add plug-ins to the application in order to change its behavior or extend it. -Please check [docs/plugins.md](docs/plugins.md) for more details. - -### Add language - -#### - Generate a translation file - -If you just want to translate the application strings for a certain language, but you don't have the skills to `"code"` -it into the app, just download the [en-translation-source-merged.json](/docs/en-translation-source-merged.json), -translate it, and contact us. - -\*_Check the file [src/i18n/i18n-builder.js](src/i18n/i18n-builder.js) to see how to generate merged translation sources_ - -#### - Add a language to the app - -The app uses a feature-by-folder design, so each component might have its own translation strings. -That is why there is no single translation file. If you want to add a translation and `"implement"` it into the app, -follow the steps below. - -- Create a copy of the /src/i18n/translations/`en-us` folder giving it the identification of the target language. - For example: if you are adding the French from France, then the folder should be called `fr-fr`. - -- Edit the `builder.js` file inside the just created folder in order to replace the language pattern to the one you are - creating. - For example, similar to `/\.i18n\.en-us\.js$` add `/\.i18n\.fr-fr\.js$`. - -- Translate the language strings for each key in the `global.js` file - -- Search for each file inside the `/src` folder that ends with `i18n.en-us.js` and create a copy of it and each one so - that each new created file now ends with `i18n.fr-fr.js`. If you are using a linux/unix compatible terminal, you can do that by running: - - ```sh - find . -name "*i18n.en-us.js" -exec bash -c 'cp "$0" "${0/i18n.en-us.js/i18n.fr-fr.js}"' {} \; - # where the last occurrence of locale id (in this case `fr-fr`) is the one you are creating - ``` - -- Translate the language strings for each key in all the files created in the previous step. - -- Edit `/src/config/settings-options.js` and add the new locale object to the `appLocales` array (e.g. - `{ text: 'Français FR', value: 'fr-fr' }`). - -- Open the src/i18n/`i18n-builder.js` file and apply the following changes: - - - Import the object from the new language builder that you just created - (e.g. `import frFRTranslations from './translations/fr-fr/builder'`) - - - Inside the `build` method, add: - - - the new language placeholder object to the messages object (e.g. `, 'fr-fr': {}`). - - - the result of the new language building to the previously created message object - (e.g. `i18n.messages['fr-fr'] = frFRTranslations.build()`). - - - Save all the files changed and rebuild the application. - -### Debug - -If you are using [WebStorm](https://www.jetbrains.com/webstorm/download) you should set the -_webpack config_ (settings -> Languages & Frameworks -> JavaScript -> Webpack) to -`{path to ors-map-client}/build/webpack.base.conf.js` to resolve file paths correctly. - -To debug the application you must run it in [`dev` mode](#set-up-and-run). -For better debugging in your browser install the [Vue.js devtools](https://github.com/vuejs/vue-devtools#installation) -extension. -After doing that, open the application in the browser and press F12 and select the tab `Console`, `Vue` or `Sources` -(and then expand e.g.: `webpack://src`). - -##### USB debugging - -To debug the client on a mobile phone you can follow e.g. [this guide](https://chenhuijing.com/blog/debugging-firefox-on-android/#%F0%9F%8F%80). - ### Build and deploy The app must be built before it is deployed. To do so, run: @@ -322,6 +202,75 @@ pre-commit run --all > Don't add `closing` or `fixes` keywords in commits but rather tag the issue in the pull request that solves it. > This avoids multiple references in the issues after your branch is rebased on newer changes. + +#### Add language + +##### - Generate a translation file + +If you just want to translate the application strings for a certain language, but you don't have the skills to `"code"` +it into the app, just download the [en-translation-source-merged.json](/docs/en-translation-source-merged.json), +translate it, and contact us. + +\*_Check the file [src/i18n/i18n-builder.js](src/i18n/i18n-builder.js) to see how to generate merged translation sources_ + +##### - Add a language to the app + +The app uses a feature-by-folder design, so each component might have its own translation strings. +That is why there is no single translation file. If you want to add a translation and `"implement"` it into the app, +follow the steps below. + +- Create a copy of the /src/i18n/translations/`en-us` folder giving it the identification of the target language. + For example: if you are adding the French from France, then the folder should be called `fr-fr`. + +- Edit the `builder.js` file inside the just created folder in order to replace the language pattern to the one you are + creating. + For example, similar to `/\.i18n\.en-us\.js$` add `/\.i18n\.fr-fr\.js$`. + +- Translate the language strings for each key in the `global.js` file + +- Search for each file inside the `/src` folder that ends with `i18n.en-us.js` and create a copy of it and each one so + that each new created file now ends with `i18n.fr-fr.js`. If you are using a linux/unix compatible terminal, you can do that by running: + + ```sh + find . -name "*i18n.en-us.js" -exec bash -c 'cp "$0" "${0/i18n.en-us.js/i18n.fr-fr.js}"' {} \; + # where the last occurrence of locale id (in this case `fr-fr`) is the one you are creating + ``` + +- Translate the language strings for each key in all the files created in the previous step. + +- Edit `/src/config/settings-options.js` and add the new locale object to the `appLocales` array (e.g. + `{ text: 'Français FR', value: 'fr-fr' }`). + +- Open the src/i18n/`i18n-builder.js` file and apply the following changes: + + - Import the object from the new language builder that you just created + (e.g. `import frFRTranslations from './translations/fr-fr/builder'`) + + - Inside the `build` method, add: + + - the new language placeholder object to the messages object (e.g. `, 'fr-fr': {}`). + + - the result of the new language building to the previously created message object + (e.g. `i18n.messages['fr-fr'] = frFRTranslations.build()`). + + - Save all the files changed and rebuild the application. + +#### Debug + +If you are using [WebStorm](https://www.jetbrains.com/webstorm/download) you should set the +_webpack config_ (settings -> Languages & Frameworks -> JavaScript -> Webpack) to +`{path to ors-map-client}/build/webpack.base.conf.js` to resolve file paths correctly. + +To debug the application you must run it in [`dev` mode](#set-up-and-run). +For better debugging in your browser install the [Vue.js devtools](https://github.com/vuejs/vue-devtools#installation) +extension. +After doing that, open the application in the browser and press F12 and select the tab `Console`, `Vue` or `Sources` +(and then expand e.g.: `webpack://src`). + +#### USB debugging + +To debug the client on a mobile phone you can follow e.g. [this guide](https://chenhuijing.com/blog/debugging-firefox-on-android/#%F0%9F%8F%80). + ### Releasing a new Version 1. Create a `chore/release-v*.*.*` branch with the new version from `main` branch (use [semantic versioning](https://semver.org/)) @@ -370,3 +319,55 @@ There is additional software documentation in the `/docs` folder: For a detailed explanation on how webpack works, check out the [guide](http://vuejs-templates.github.io/webpack/) and [docs for vue-loader](http://vuejs.github.io/vue-loader). + +### Configuration, theming, customization and extension + +The map client app can be configured, customized and extended. Several aspects can be defined/changed in order to +disable features, customize visual identity and change/extend its features/behaviors. +It is also possible to add custom plug-ins to the app and subscribe to hooks, listen and emit events. +The items of the menu can also be customized via hooks. + +It is possible to define your custom settings and plug-ins and keep getting updates from the ORS repository because +the `src/plugins` and `src/config` folders are not versioned. +To keep the original ors-map-client as a secondary repository, do the following: + +```sh +# Rename the original remote +git remote rename origin ors-map-client-origin + +# Add your remote as the origin one +git remote add origin + +# Set your new origin as the default upstream +git branch --set-upstream-to=origin/master +``` + +After doing this we recommend you to remove from `.gitignore` the lines that tell git to ignore the folders +`/src/config`, `src/plugins` and eventually `/static`. +Then, run the initial push to the just defined new origin repository, with the following command: + +```sh +git push -u origin master +``` + +The ways to change/extend the app are: + +1. Define custom settings (see files in `src/config`) that will change the standard way that the app works. +1. Add hook listeners in `src/config/hooks.js` and run custom code inside those hooks +1. Create a plug-in that has its methods linked to hooks called during the app flow + (see `src/plugins/example-plugin/`) + +#### Configuration + +It is possible to configure/disable some app features and behaviors by changing the values +of the `src/config/app-config.js`. It is also possible to change the app theme/colors by changing the values of +`src/config/theme.js`. +The app logo can also be changed in the `src/config/app-config` file. +The available filters/options to be used in the services are defined in the `src/config/ors-map-filters.js`. +They can be adjusted according the needs. Other files can be used to adjust app configurations are the +`layer-zoom-mapping.js`, `settings-options.js` and the `default-map-settings.js`. + +#### Plug-ins + +It is possible to add plug-ins to the application in order to change its behavior or extend it. +Please check [docs/plugins.md](docs/plugins.md) for more details. From ac1b5a904401689465e164d26184b61a04215f2e Mon Sep 17 00:00:00 2001 From: Amandus Butzer Date: Fri, 2 Aug 2024 19:14:06 +0200 Subject: [PATCH 10/12] docs(README): reformat file --- README.md | 53 ++++++++++++++++++++++++++++++++--------------------- 1 file changed, 32 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index ef7e6913f..36d5ea696 100755 --- a/README.md +++ b/README.md @@ -46,9 +46,9 @@ first. If you are using a linux/unix compatible terminal, you can do that by running: - ```sh - cd src && cp config-examples/* config && for i in config/*-example.js; do mv -- "$i" "${i%-example.js}.js"; done - ``` + ```sh + cd src && cp config-examples/* config && for i in config/*-example.js; do mv -- "$i" "${i%-example.js}.js"; done + ``` 2. Set the app-config.js values for `orsApiKey` to be used when not running the app from valid ors domains @@ -120,6 +120,7 @@ pnpm build The built files are meant to be served by a web server like nginx or apache. You can try if everything works locally e.g. with: + ```sh pnpx http-server . ``` @@ -143,7 +144,8 @@ pnpm test ``` You can run tests in any standard browser that you have installed. -If you are new to cypress check out the "[Getting started](https://docs.cypress.io/guides/getting-started/opening-the-app)" +If you are new to cypress check out +the "[Getting started](https://docs.cypress.io/guides/getting-started/opening-the-app)" documentation, and keep it close. An overview on the usable [assertions](https://docs.cypress.io/guides/references/assertions) will help with simple test cases. @@ -153,16 +155,20 @@ test cases. Component tests should be written in the component itself e.g. `../fragments/MyComponent.cy.js` for `../fragments/MyComponent.vue` -Unit tests for js source files should be created in a separate `./__tests__` folder next to the source file and for the sake of +Unit tests for js source files should be created in a separate `./__tests__` folder next to the source file and for the +sake of clarity be named the same e.g. `../support/__tests__/utils.cy.js` for `../support/utils.js` End-to-end tests should be created in `./cypress/e2e/test-name.cy.js` ### Report a bug -If you identified a bug, please [create an issue](https://github.com/GIScience/ors-map-client/issues/new) with thorough description + +If you identified a bug, please [create an issue](https://github.com/GIScience/ors-map-client/issues/new) with thorough +description and steps to reproduce it (e.g. URL, Screenshot or Screen recording). Feel free to [contribute a fix](#contribute) ### Feature improvements + If you have an idea for a new feature or want to improve an existing one, please also [create an issue](https://github.com/GIScience/ors-map-client/issues/new) first to discuss the idea. We are happy if you also want to [contribute](#contribute) a pull request. @@ -171,6 +177,7 @@ We are happy if you also want to [contribute](#contribute) a pull request. Make sure to [set up](#set-up-and-run) and [configure](#configuration) the project, branch of current `main` and prefix your branch name with `feat/` for features and `fix/` for bug fixes e.g. + ```sh git switch -c feat/leaflet-control-for-statistics # or @@ -202,7 +209,6 @@ pre-commit run --all > Don't add `closing` or `fixes` keywords in commits but rather tag the issue in the pull request that solves it. > This avoids multiple references in the issues after your branch is rebased on newer changes. - #### Add language ##### - Generate a translation file @@ -211,7 +217,8 @@ If you just want to translate the application strings for a certain language, bu it into the app, just download the [en-translation-source-merged.json](/docs/en-translation-source-merged.json), translate it, and contact us. -\*_Check the file [src/i18n/i18n-builder.js](src/i18n/i18n-builder.js) to see how to generate merged translation sources_ +\*_Check the file [src/i18n/i18n-builder.js](src/i18n/i18n-builder.js) to see how to generate merged translation +sources_ ##### - Add a language to the app @@ -229,7 +236,8 @@ follow the steps below. - Translate the language strings for each key in the `global.js` file - Search for each file inside the `/src` folder that ends with `i18n.en-us.js` and create a copy of it and each one so - that each new created file now ends with `i18n.fr-fr.js`. If you are using a linux/unix compatible terminal, you can do that by running: + that each new created file now ends with `i18n.fr-fr.js`. If you are using a linux/unix compatible terminal, you can + do that by running: ```sh find . -name "*i18n.en-us.js" -exec bash -c 'cp "$0" "${0/i18n.en-us.js/i18n.fr-fr.js}"' {} \; @@ -269,18 +277,20 @@ After doing that, open the application in the browser and press F12 and select t #### USB debugging -To debug the client on a mobile phone you can follow e.g. [this guide](https://chenhuijing.com/blog/debugging-firefox-on-android/#%F0%9F%8F%80). +To debug the client on a mobile phone you can follow +e.g. [this guide](https://chenhuijing.com/blog/debugging-firefox-on-android/#%F0%9F%8F%80). ### Releasing a new Version -1. Create a `chore/release-v*.*.*` branch with the new version from `main` branch (use [semantic versioning](https://semver.org/)) - ```sh - git checkout main && git switch -c chore/release-v*.*.* - ``` +1. Create a `chore/release-v*.*.*` branch with the new version from `main` branch ( + use [semantic versioning](https://semver.org/)) + ```sh + git checkout main && git switch -c chore/release-v*.*.* + ``` 2. Run the release script to bump version, create changelog entries and release tag - ```sh + ```sh pnpm release - ``` + ``` 3. Make sure the changelog & version is what you expected and adjust if needed - adjust branch name: `git branch -m chore/release-` - adjust changelog or version in files. Then amend commit and re-tag: @@ -289,20 +299,21 @@ To debug the client on a mobile phone you can follow e.g. [this guide](https://c git tag -fa v*.*.* -m 'v*.*.*' ``` 4. Push the release branch to remote - ```sh - git push --set-upstream origin $(git_current_branch) + ```sh + git push --set-upstream origin $(git_current_branch) ``` 5. Click on the link to open a pull request for the release branch, create it and link relevant issues > Note: -Pre-commit hooks and test:ci tasks are run for every pull request and any change to it. +> Pre-commit hooks and test:ci tasks are run for every pull request and any change to it. ### Deployment -Deployments happen automatically if the conditions for the [environment](https://github.com/GIScience/ors-map-client/settings/environments) are met: +Deployments happen automatically if the conditions for +the [environment](https://github.com/GIScience/ors-map-client/settings/environments) are met: | Environment | Condition | Target | Workflow dispatch | -|-------------|---------------------------------------------------------------|-------------------------------------------|--------------------| +| ----------- | ------------------------------------------------------------- | ----------------------------------------- | ------------------ | | Staging | open pull request for / push to `chore/release-v*.*.*` branch | https://maps-staging.openrouteservice.org | :heavy_check_mark: | | Production | merge `chore/release-v*.*.*` branch to `main` | https://maps.openrouteservice.org | :heavy_check_mark: | | HEAL | push to `heal` branch | https://heal.openrouteservice.org | :no_entry_sign: | From 94e390f1f4fe3d85bbfca807b3796668e2f7030c Mon Sep 17 00:00:00 2001 From: Amandus Butzer Date: Fri, 2 Aug 2024 19:20:12 +0200 Subject: [PATCH 11/12] docs(README): add project structure parts --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index 36d5ea696..1449461ad 100755 --- a/README.md +++ b/README.md @@ -175,6 +175,7 @@ We are happy if you also want to [contribute](#contribute) a pull request. ### Contribute +To better understand and navigate the codebase best get to know the [project structure](docs/project-structure.md) first. Make sure to [set up](#set-up-and-run) and [configure](#configuration) the project, branch of current `main` and prefix your branch name with `feat/` for features and `fix/` for bug fixes e.g. @@ -324,6 +325,7 @@ Use the workflow dispatch to deploy e.g. a feature branch to staging or an inter There is additional software documentation in the `/docs` folder: +- [docs/project-structure.md](docs/project-structure.md) - explains the project & folder structure - [docs/dynamic-inputs.md](docs/dynamic-inputs.md) - describes how the inputs are rendered using a custom engine - [docs/search-results-criteria.md](docs/search-results-criteria.md) - explains the criteria for search results - [docs/plugins.md](docs/plugins.md) - explains how to add plugins From b34080ffa51e20806f12d2a0f14785dc80367f93 Mon Sep 17 00:00:00 2001 From: Amandus Butzer Date: Fri, 2 Aug 2024 19:20:24 +0200 Subject: [PATCH 12/12] docs(README): fix list numbering --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 1449461ad..2ac23da94 100755 --- a/README.md +++ b/README.md @@ -366,8 +366,8 @@ git push -u origin master The ways to change/extend the app are: 1. Define custom settings (see files in `src/config`) that will change the standard way that the app works. -1. Add hook listeners in `src/config/hooks.js` and run custom code inside those hooks -1. Create a plug-in that has its methods linked to hooks called during the app flow +2. Add hook listeners in `src/config/hooks.js` and run custom code inside those hooks +3. Create a plug-in that has its methods linked to hooks called during the app flow (see `src/plugins/example-plugin/`) #### Configuration