Merge branch 'develop' into fix/google-maps-error

Author: BiniCodes

.github/workflows/publish.yml

@@ -28,15 +28,15 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository from GitHub
-        uses: actions/checkout@v2.3.1
+        uses: actions/checkout@v3
       - name: Setup npm
-        uses: actions/setup-node@v2
+        uses: actions/setup-node@v3
         with:
           node-version: '16'
           registry-url: 'https://registry.npmjs.org'
       # npm cache folder is in ~/, not within the working directory
       - name: Cache npm directory
-        uses: actions/cache@v2
+        uses: actions/cache@v3
         with:
           path: ~/.npm
           key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}

.github/workflows/test.yml

@@ -9,14 +9,14 @@ jobs:
     timeout-minutes: 8
     steps:
       - name: Checkout repository from GitHub
-        uses: actions/checkout@v2.3.1
+        uses: actions/checkout@v3
       - name: Setup npm
-        uses: actions/setup-node@v2
+        uses: actions/setup-node@v3
         with:
           node-version: '16'
       # npm cache folder is in ~/, not within the working directory
       - name: Cache npm directory
-        uses: actions/cache@v2
+        uses: actions/cache@v3
         with:
           path: ~/.npm
           key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}

CONTRIBUTING.md

@@ -1,15 +1,28 @@
 # Contributing to Ubilabs Google Maps React Hooks
 
-We are happy you came here and thank you for contributing! 🎉 
+We are happy you came here and thank you for contributing! 🎉
 
 To get started there are some things that need to be set up.
 
-----
+---
 
-## Setting Up Dev Environment
+#### Table of contents
+
+- [Setting Up Dev Environment](#setting-up-dev-environment)
+  - [Fork the repo and start building](#fork-the-repo-and-start-building)
+- [Issue Tracker](#issue-tracker)
+- [Pull Requests / Merge Requests](#pull-requests--merge-requests)
+  - [Code Style and Code Quality](#code-style-and-code-quality)
+- [Adding An Example](#adding-an-example)
+  - [Run examples](#run-examples)
+  - [Develop examples](#develop-examples)
+- [Publish library on npm](#publish-library-on-npm)
 
-We will work on the `develop` branch. 
+---
+
+## Setting Up Dev Environment
 
+We will work on the `develop` branch.
 
 We use [npm](https://www.npmjs.com/) to manage the dependencies.
 
@@ -35,8 +48,9 @@ git checkout develop
 ```
 
 3. At the root directory of the project on the develop branch, install all dependencies and build.
+
 ```bash
-# Install dependencies 
+# Install dependencies
 npm install
 
 # Start the project locally before changing code
@@ -54,6 +68,7 @@ git checkout -b feat/my-new-feature-branch
 ```
 
 5. To see example cases of the Google Maps react hooks, checkout the [Examples Folder](./examples). To start an example:
+
 ```bash
 # If not done already: Go to 'google-maps-react-hooks' directory and run:
 npm install
@@ -64,65 +79,101 @@ npm run start:sample-map
 
 Then open [`localhost:1234`](http://localhost:1234) in a browser.
 
-----
+---
 
 ## Issue Tracker
 
 - before submitting a new issue, please:
 
-    - check for existing related issues
+  - check for existing related issues
 
-    - check the issue tracker for a specific upstream project that may be more appropriate
+  - check the issue tracker for a specific upstream project that may be more appropriate
 
-    - check against supported versions of this project (i.e. the latest)
+  - check against supported versions of this project (i.e. the latest)
 
 - please keep discussions on-topic, and respect the opinions of others
 
 - please contact us privately to discuss security vulnerabilities
 
-----
+---
 
 ## Pull Requests / Merge Requests
 
 - **IMPORTANT**: by submitting a patch, you agree to allow the project owners to license your work under this [LICENSE.md](LICENSE.md)
 
-- please provide test cases for all features and bug fixes
+  - please provide test cases for all features and bug fixes
 
-- provide documentation for all public API methods
+  - provide documentation for all public API methods
 
-- commit messages should follow the format outlined in [CONVENTIONS.md](CONVENTIONS.md)
+  - commit messages should follow the format outlined in [CONVENTIONS.md](CONVENTIONS.md)
 
 ### Code Style and Code Quality
 
-- Testing
+- **Testing**
 
-   - [ESLint](https://eslint.org/) configuration files are provided
-   - [TypeScript](https://www.typescriptlang.org/) check for types and TypeScript setup
-   - [Prettier](https://prettier.io/) code formatter
+  - [ESLint](https://eslint.org/) configuration files are provided
+  - [TypeScript](https://www.typescriptlang.org/) check for types and TypeScript setup
+  - [Prettier](https://prettier.io/) code formatter
 
-- run `npm run test` before submitting a PR to ensure that your code uses correct style and passes all tests
+Run `npm run test` before submitting a PR to ensure that your code uses correct style and passes all tests
 
-----
+---
 
 ## Adding An Example
-Each hook should have an example in the examples folder. If you want to provide an example for a hook, please follow these steps:
+
+Each hook should have an example in the examples folder.
+
+### Run examples
+
+To develop one of the examples, you have to create a `.env` file in the `/examples` directory first and add your [Google Maps API key](https://developers.google.com/maps/documentation/embed/get-api-key#:~:text=Go%20to%20the%20Google%20Maps%20Platform%20%3E%20Credentials%20page.&text=On%20the%20Credentials%20page%2C%20click,Click%20Close.) to it in the following format:
+
+```
+GOOGLE_MAPS_API_KEY="<YOUR API KEY HERE>"
+```
+
+An example can be found in `/examples/.env.example`.
+
+Start the example locally with the appropriate task, e.g. `npm run start:map-example`. You can find the right task in the README of the example you want to start.
+
+The example runs on [localhost:1234](http://localhost:1234).
+
+### Develop examples
+
+If you want to provide an example for a hook, please follow these steps:
 
 1. Create a new folder in the [examples folder](./examples) with the new example's name.
 
 2. In the folder, create a runnable React App showing the usage of the new hook in a common use case. Checkout the current examples in the [examples folder](./examples) to see how the setup should looks like. The [basic google map example](./examples/basic-google-map/) is always a good starting point.
 
 3. Add a npm task in the [examples workspace package.json](./examples/package.json) with a naming convention like this:
+
 ```json
 "start:example-folder-name": "EXAMPLE_ENTRY=./example-folder-name/index.html npm run start:example"
 ```
+
 Please compare to the other example start tasks.
 
 4. Add another npm task in the root [package.json](./package.json) to start the example, with a naming convention like this:
+
 ```json
 "start:example-folder-name-example": "EXAMPLE=example-folder-name run-p start:library start:example"
-````
-Please compare to the other example start tasks. 
+```
+
+Please compare to the other example start tasks.
 
 5. Add a README to each example with an explanation of what the example does, a code snippet and an image of the example app in a ratio of 2:1.
 
-6. Link the example in the [root README](./README.md) and the [README of the library workspace](./library/README.md) in the **Examples** overview of the **Table of contents** section.
+6. Link the example in the [root README](./README.md) and the [README of the library workspace](./library/README.md) in the **Examples** overview of the **Table of contents** section.
+
+---
+
+## Publish library on npm
+
+A new library version is automatically published by Github Actions as soon as a new version tag is available.
+To trigger a new release, run:
+
+```sh
+npm version [<newversion> | major | minor | patch | premajor | preminor | prepatch | prerelease | from-git] -w library
+```
+
+**NOTE**: Make sure to not forget setting the context to the library workspace with `-w library` when running the command from project root.

CONVENTIONS.md

@@ -20,19 +20,23 @@ Below that, the commit message has a **body**.
 ```
 
 Examples:
+
 ```
 feat(ruler): add inches as well as centimeters
 ```
+
 ```
 fix(protractor): fix 90 degrees counting as 91 degrees
 ```
+
 ```
 refactor(pencil): use graphite instead of lead
 
 Closes #640.
 
 Graphite is a much more available resource than lead, so we use it to lower the price.
 ```
+
 ```
 fix(pen): use blue ink instead of red ink
 
@@ -51,33 +55,37 @@ Any line of the commit message should not be longer 100 characters. This allows
 to read on github as well as in various git tools.
 
 ### Type
+
 Is recommended to be one of the below items. Only **feat** and **fix** show up in the changelog, in addition to breaking changes (see breaking changes section at bottom).
 
-* **feat**: A new feature
-* **fix**: A bug fix
-* **docs**: Documentation only changes
-* **style**: Changes that do not affect the meaning of the code (white-space, formatting, missing
+- **feat**: A new feature
+- **fix**: A bug fix
+- **docs**: Documentation only changes
+- **style**: Changes that do not affect the meaning of the code (white-space, formatting, missing
   semi-colons, etc)
-* **refactor**: A code change that neither fixes a bug or adds a feature
-* **test**: Adding missing tests
-* **chore**: Changes to the build process or auxiliary tools and libraries such as documentation
+- **refactor**: A code change that neither fixes a bug or adds a feature
+- **test**: Adding missing tests
+- **chore**: Changes to the build process or auxiliary tools and libraries such as documentation
   generation
-* **build**: Changes that affect the build system or external dependencies
-* **ci**: Changes to our CI configuration files and scripts
-* **perf**: A code change that improves performance
+- **build**: Changes that affect the build system or external dependencies
+- **ci**: Changes to our CI configuration files and scripts
+- **perf**: A code change that improves performance
 
 ### Scope
+
 The scope could be anything specifying place of the commit change. For example `$location`,
 `$browser`, `$compile`, `$rootScope`, `ngHref`, `ngClick`, `ngView`, etc...
 
 ### 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
+- use the imperative, present tense: "change" not "changed" nor "changes"
+- don't capitalize first letter
+- no dot (.) at the end
 
 ### Breaking Changes
+
 Put any breaking changes with migration instructions in the commit body.
 
 If there is a breaking change, put **BREAKING CHANGE:** in your commit body, and it will show up in the changelog.