docs: update contributing.md

docs/contributing.md

@@ -4,11 +4,51 @@
 
 PRs and bug reports are welcome, and we are actively looking for new maintainers.
 
+Please [open a discussion][discussions] or [feature request][feat-req] before starting to work on a new feature. That way we can make sure it fits well with the overall architecture and plans of the library.
+
+[discussions]: https://github.com/visgl/react-google-maps/discussions
+[feat-req]: https://github.com/visgl/react-google-maps/issues/new?assignees=&labels=feature&projects=&template=feature-request.yml&title=%5BFeat%5D
+
+## Goals and Philosophy
+
+It would be great to have some level of support for most, if not all
+features of the Google Maps JavaScript API.
+_"Some level of support"_ is intentionally a bit vague here: Balancing the
+amount of features included in this library with the effort needed to
+maintain it (and thus prevent it from decaying) is going to be an ongoing
+discussion.
+**Features added to the library are permanent**, and need a commitment to
+keep maintaining them, which is why adding features has to be considered
+carefully.
+
+The focus will be on providing an extensible library of **"low-level"
+abstractions** that can be used to implement known and unknown use-cases of
+the Google Maps API in a React application.
+
+In a lot of cases – especially when a solution needs to have a lot of
+flexibility (implementing an Autocomplete component for example) and room
+for opinion (generally everything with a UI) – it is preferrable to provide
+a "reference implementation" with our examples that users can then copy and
+adjust to their needs.
+
+## Development Process
+
+The default procedure for adding functionality to the library is as follows:
+
+- new features always start as a "reference implementation" in an example
+  (see also the ["Writing Examples" guide](./guides/writing-examples.md)).
+- when implementing the desired feature is challenging or impossible with the
+  library, that would be an excellent indicator that some abstraction is
+  missing at a lower level and should be added to the library.
+- If a new feature proves to be useful and univeral (i.e. it can be used
+  without needing much per-user customization), we will
+  consider adding it to the library or providing it as a separate library.
+
 ## Setting Up Dev Environment
 
 The **main** branch is the active development branch.
 
-Building react-google-maps locally from the source requires node.js `>=8`.
+Building `@vis.gl/react-google-maps` locally from the source requires a current version of node.js.
 We use npm to manage the dependencies.
 
 ```bash
@@ -17,39 +57,46 @@ npm install
 npm run test
 ```
 
-Test:
+Running the full test suite:
 
 ```bash
 npm run test
 ```
 
+Or just the unit-tests:
+
+```bash
+npm run test:unit
+```
+
 ## Pull Requests
 
-Any intended change to the code base must open a [pull request](https://help.github.com/articles/creating-a-pull-request/) and be approved. 
+Any intended change to the code base must open a [pull request](https://help.github.com/articles/creating-a-pull-request/) and be approved by the maintainers.
 
 Generally speaking, all PRs are open against the `main` branch, unless the feature being affected no longer exists on main.
 
 ### PR Checklist
 
 - [ ] Tests
-  + `npm run test` must be successful.
-  + New code should be covered by unit tests whenever possible.
+
+  - `npm run test` must be successful.
+  - New code should be covered by unit tests whenever possible.
 
 - [ ] Documentation
-  + If public APIs are added/modified, update component documentation in `docs/api-reference`.
-  + Breaking changes and deprecations must be added to `docs/upgrade-guide.md`.
-  + Noteworthy new features should be added to `docs/whats-new.md`.
+
+  - If public APIs are added/modified, update component documentation in `docs/api-reference`.
+  - Breaking changes and deprecations must be added to `docs/upgrade-guide.md`.
+  - Noteworthy new features should be added to `docs/whats-new.md`.
 
 - [ ] Description on GitHub
-  + Link to relevant issue.
-  + Label with a milestone (latest release or vNext).
-  + If public APIs are added/modified, describe the intended behavior.
-  + If visual/interaction is affected, consider attaching a screenshot/GIF.
+  - Link to relevant issue.
+  - Label with a milestone (latest release or vNext).
+  - If public APIs are added/modified, describe the intended behavior.
+  - If visual/interaction is affected, consider attaching a screenshot/GIF.
 
 ## Release
 
-react-google-maps follows the [Semantic Versioning](https://semver.org/) guidelines. Steps for publishing releases can be found [here](https://www.github.com/visgl/tsc/tree/master/developer-process).
-
+`@vis.gl/react-google-maps` follows the [Semantic Versioning](https://semver.org/) guidelines. Steps for publishing releases can be found [here](https://www.github.com/visgl/tsc/tree/master/developer-process).
 
 ## Community Governance
 

docs/guides/writing-examples.md

@@ -0,0 +1,68 @@
+# Writing Examples
+
+The examples for this library serve multiple purposes. First, they should
+demonstrate the abilities and common patterns for how to achieve things for
+users of the library and serve as a source of inspiration.
+
+At the same time, they should also act as some sort of end-to-end
+testing stage during development of new features. Validating that all
+examples are still working should be part of the development process
+(automated (visual) testing for the examples would be an excellent addition to
+our workflows).
+
+And finally, the examples act as "incubator" for new features. Proposed
+features should be implemented using examples first. That way, the
+functionality is available to everyone by copying and adjusting the code
+from the example. If these features prove to be useful and universal enough,
+they will be considered to be added to the library.
+
+## Scope of an Example
+
+Examples should typically focus on demonstrating a single feature or a
+set of features in a comprehensive way, and they should reflect what we
+think are "ideal ways" to solve a specific problem.
+
+The code should try to avoid or hide clutter and unrelated concepts.
+For example, if you want to show how different types of marker could be
+created, functions used to prepare data to show should be hidden away.
+
+Examples will typically be read from top to bottom, so consider organizing
+the code in a way that puts the "gist" of the example at the very top of the
+main source-file.
+
+When writing an example for a proposed feature, try to write the code for
+that feature in a reusable way, such that the relevant components or hooks can
+easily be copied into another project. This typically means to have
+components or hooks in their own files with as few dependencies as possible
+and avoid using bundler-specific features (for example, importing of css
+files or using environment variables).
+
+### Create the example
+
+- Start off by copying the `./examples/_template` folder for
+  your example. This will contain the config-files needed and some
+  basic setup that is the same for all examples. The new directory-name will be
+  the "example id" and should be in 'kebap-case' (we'll need that id later).
+- Develop the example independently of the library as a standalone
+  mini-application (using `npm install` and `npm start` to start the vite 
+  dev-server).
+- If you install additional dependencies, the "Examples" section of [the website](https://visgl.github.io/react-google-maps/examples/) will not be able to host your example, but you can still [link to a CodeSandbox](https://codesandbox.io/docs/learn/devboxes/synced-templates#creating-a-synced-template) for the example.
+- Edit the title, description and sourcecode links in the
+  `README.md`, `index.html`, and `./src/control-panel.tsx` files.
+
+### Adding examples to the website
+
+If you are adding an example with **no additional dependencies**:
+
+1. Create the example page in `./website/src/examples/your-example-id.mdx`
+2. Add the example to `./website/src/examples-sidebar.js`
+3. Create a 400x400 px image for the overview page and place it in
+   `./website/static/images/examples/your-example-id.jpg`
+4. The whole website can be started in dev-mode by running `npm i` and 
+   `npm start` in the `./website` directory. The website build can be tested 
+   by running `npm run build`.
+
+If you are adding an example **with additional dependencies**:
+
+1. Create a 400x400 px image for the overview page and place it in `./website/static/images/examples/your-example-id.jpg`
+2. Add the example to `./website/src/examples-sidebar.js` as an [external link](https://docusaurus.io/docs/sidebar/items#sidebar-item-link) to [a CodeSandbox](https://codesandbox.io/docs/learn/devboxes/synced-templates#creating-a-synced-template) based on the title of your new example folder in the `./examples` folder.

docs/table-of-contents.json

@@ -15,7 +15,8 @@
     "label": "Guides",
     "items": [
       "guides/interacting-with-google-maps-api",
-      "guides/deckgl-integration"
+      "guides/deckgl-integration",
+      "guides/writing-examples"
     ]
   },
   {

examples/README.md

@@ -1,62 +1,21 @@
 # Examples for @vis.gl/react-google-maps
 
-The examples here serve multiple purposes. First, they should demonstrate
-the abilities and common patterns for how to achieve things for users of
-the library and serve as a source of inspiration.
+All of our examples are fully self-contained and can be run as independent
+applications, even when the entire directory is copied elsewhere. Just run
+`npm install` and `npm start` in any example directory to start it.
 
-At the same time, they should also act as some sort of end-to-end
-testing stage during development of new features. Validating that all
-examples are still working should be part of the development process
-(automated if possible).
+During development of the library, the examples can also be started using
+`npm run start-local`, which will run the example with the checked-out
+source of the library instead of the package installed via npm.
 
-All examples are fully self-contained and can be run as independent
-applications, even when the entire directory is copied elsewhere.
-Users should be able to just run `npm i` and `npm start` to start any
-example.
-
-To run the examples during development of the library, we have
-additional scripts to start the example in the context of the library,
-using the library itself and its dependencies instead of those locally
-installed in the example folder.
-
-All examples should contain a link to a CodeSandbox environment where the
+All examples also contain a link to a CodeSandbox environment where the
 example can be played with right away.
 
-## Writing examples
-
-Examples should typically focus on demonstrating a single feature or a
-set of features in a comprehensive way, and they should reflect what we
-think are "ideal ways" to solve a specific problem.
-
-The code should try to avoid or hide clutter and unrelated concepts.
-For example, if you want to show how different types of marker could be
-created, functions used to prepare data to show should be hidden away.
-
-### Create the example
-
-- Start off by copying the `./examples/_template` folder for
-  your example. This will contain the config-files needed and some
-  basic setup that is the same for all examples. The new directory-name will be
-  the "example id" and should be in 'kebap-case' (we'll need that id later).
-- Develop the example independently of the library as a standalone
-  mini-application (using `npm i` and `npm start` to start the vite dev-server).
-- If you install additional dependencies, the "Examples" section of [the website](https://visgl.github.io/react-google-maps/examples/) will not be able to host your example, but you can still [link to a CodeSandbox](https://codesandbox.io/docs/learn/devboxes/synced-templates#creating-a-synced-template) for the example.
-- Edit the title, description and sourcecode links in the
-  `README.md`, `index.html`, and `./src/control-panel.tsx` files.
-
-### Adding examples to the website
-
-If you are adding an example with **no additional dependencies**:
-
-1. Create the example page in `./website/src/examples/your-example-id.mdx`
-1. Add the example to `./website/src/examples-sidebar.js`
-1. Create a 400x400 px image for the overview page and place it in
-   `./website/static/images/examples/your-example-id.jpg`
-1. The whole website can be started in dev-mode by running `npm i` and `npm start`
-   in the `./website` directory. The website build can be tested by running
-   `npm run build`.
+When browsing the examples on GitHub, you can also just replace `github.com`
+with `githubbox.com` in your url while you're in an example directory to
+open it in a codesandbox environment.
 
-If you are adding an example **with additional dependencies**:
+More information about how to write examples [can be found in our
+documentation][writing-examples].
 
-1. Create a 400x400 px image for the overview page and place it in `./website/static/images/examples/your-example-id.jpg`
-1. Add the example to `./website/src/examples-sidebar.js` as an [external link](https://docusaurus.io/docs/sidebar/items#sidebar-item-link) to [a CodeSandbox](https://codesandbox.io/docs/learn/devboxes/synced-templates#creating-a-synced-template) based on the title of your new example folder in the `./examples` folder.
+[writing-examples]: https://visgl.github.io/react-google-maps/docs/guides/writing-examples