docs: update readme and contribution guide

CONTRIBUTING.md

@@ -0,0 +1,80 @@
+# Contributing to ACF SVG Icon Picker
+
+We welcome contributions to the ACF SVG Icon Picker plugin. This document outlines the process for contributing to the plugin.
+
+## Pull Requests
+
+Pull requests are highly appreciated. To contribute to the plugin, you can fork the repository and create a new branch for your changes. When you’re done, you can create a pull request to merge your changes into the main branch.
+
+1. **Solve a problem** – Features are great, but even better is cleaning-up and fixing issues in the code that you discover.
+2. **Write tests** – This helps preserve functionality as the codebase grows and demonstrates how your change affects the code.
+3. **Write documentation** – Timber is only useful if its features are documented. This covers inline documentation of the code as well as documenting functionality and use cases in the Guides section of the documentation.
+4. **Small > big** – Better to have a few small pull requests that address specific parts of the code, than one big pull request that jumps all over.
+5. **Comply with Coding Standards** – See next section.
+
+## Preparations
+
+After you’ve forked the ACF SVG Icon Picker repository, you should install all Composer dependencies.
+
+```
+composer install
+```
+
+## Coding Standards
+
+We use [EasyCodingStandard](https://github.com/symplify/easy-coding-standard) for Timber’s code and code examples in the documentation, which follows the [PSR-12: Extended Coding Styles](https://www.php-fig.org/psr/psr-12/).
+
+We use tools to automatically check and apply the coding standards to our codebase (including the documentation), reducing the manual work to a minimum.
+
+To run all checks, you can run the `qa` script.
+
+```bash
+composer qa
+```
+
+### Check and apply coding standards
+
+We use EasyCodingStandard to automatically check and apply the coding standards.
+
+```bash
+composer cs
+```
+
+And to automatically fix issues:
+```bash
+composer cs:fix
+```
+
+We also use PHPStan to check for errors in the codebase.
+
+```bash
+composer analyse
+```
+
+## Unit tests
+
+### Install WordPress test suite
+
+Run the following command to install the test suite on your local environment:
+
+```bash
+bash bin/install-wp-tests.sh {db_name} {db_user} {db_password} {db_host} {wp_version}
+```
+
+Replace variables with appropriate values. for example:
+
+```bash
+bash bin/install-wp-tests.sh acf_icon_test root root localhost 6.6
+```
+
+### Run unit tests
+
+Run PHPUnit test suite with the default settings and ensure your code does not break existing features.
+
+```bash
+composer test
+```
+
+## Process
+
+All PRs receive a review from at least one maintainer. We’ll do our best to do that review as soon as possible, but we’d rather go slow and get it right than merge in code with issues that just lead to trouble.

README.md

@@ -3,7 +3,7 @@
 
 # ACF SVG Icon Picker Field
 
-Add an ACF field to your theme that lets users easily select SVG icons from a specified folder. The field returns the SVG's name.
+Add a field type to ACF for selecting SVG icons from a popup modal. Theme developers can provide a set of SVG icons to choose from.
 
 ## Compatibility
 
@@ -35,59 +35,51 @@ If you're coming from the original ACF Icon Picker plugin, you can switch to thi
 4. Go over your field configurations and change the field type from `icon-picker` to `svg_icon_picker` in the field settings. Be aware of the underscores in the field type name.
 5. Check if the field type is now available in your ACF field settings
 
-## Filters
+## Usage of this plugin
+We recommend storing your SVG icons in a folder within your theme. This plugin defaults to looking for icons inside the `icons/` folder of your theme. You can change this path by using the provided filters.
 
-Use the below filters to override the default icon folder, path, and / or URL:
+When using this plugin in conjunction with a parent/child theme, you can store your icons in the parent theme and use the child theme to override the path to the icons. This way, you can provide a set of icons in the parent theme and still allow the child theme to override them.
+
+### Helper functions
+We provide helper functions to fetch icons from the theme folder, without it matering if the icon is stored in the parent or child theme.
 
 ```php
-// modify the path to the icons directory
-add_filter('acf_icon_path_suffix', 'acf_icon_path_suffix');
+$my_icon_field = get_field('my_icon_field');
+
+// Get the icon URL
+$icon_url = get_svg_icon_uri($my_icon_field);
 
-function acf_icon_path_suffix($path_suffix) {
-    return 'assets/img/icons/';
-}
+// Get the icon file system path
+$icon_path = get_svg_icon_path($my_icon_field);
 
-// modify the path to the above prefix
-add_filter('acf_icon_path', 'acf_icon_path');
+// Get the icon contents
+$icon_svg = get_svg_icon($my_icon_field);
+```
 
-function acf_icon_path($path_suffix) {
-    return plugin_dir_path(__FILE__);
-}
+### Filters
 
-// modify the URL to the icons directory to display on the page
-add_filter('acf_icon_url', 'acf_icon_url');
+Use the below filters to override the default icon folder inside your theme.
 
-function acf_icon_url($path_suffix) {
-    return plugin_dir_url( __FILE__ );
-}
+```php
+// modify the path to the icons directory in your theme.
+add_filter('acf_icon_path_suffix', function () {
+  return 'resources/icons/';
+});
 ```
 
-### For Sage/Bedrock edit filters.php:
+In case you do not want to store the icons in the theme folder, you can use the below filter to change the path to the icons directory to a custom location.
+In this example, the icons are stored in the `WP_CONTENT_DIR . '/icons/'` folder.
 
 ```php
-/// modify the path to the icons directory
-add_filter('acf_icon_path_suffix',
-  function ( $path_suffix ) {
-    return '/assets/images/icons/'; // After assets folder you can define folder structure
-  }
-);
-
-// modify the path to the above prefix
-add_filter('acf_icon_path',
-  function ( $path_suffix ) {
-    return '/app/public/web/themes/THEME_NAME/resources';
-  }
-);
-
-// modify the URL to the icons directory to display on the page
-add_filter('acf_icon_url',
-  function ( $path_suffix ) {
-    return get_stylesheet_directory_uri();
-  }
-);
+add_filter('acf_svg_icon_picker_custom_location', function () {
+  return [
+    'path' => WP_CONTENT_DIR . '/icons/',
+    'url' =>  content_url() . '/icons/',
+  ];
+});
 ```
 
-## Using with [ACF Builder](https://github.com/StoutLogic/acf-builder) / [ACF Composer](https://github.com/Log1x/acf-composer)
+### Using with [ACF Builder](https://github.com/StoutLogic/acf-builder) / [ACF Composer](https://github.com/Log1x/acf-composer)
 
 ```php
 $fields->addField('my_icon', 'svg_icon_picker', [