Merge latest develop -> main

.husky/pre-commit

@@ -1,4 +1 @@
-#!/usr/bin/env sh
-. "$(dirname "$0")/_/husky.sh"
-
 npx lint-staged

README.md

@@ -2,7 +2,7 @@
 
 Team responsible: Engineering Enablement team
 
-This is [Docusaurus](https://docusaurus.io/) application. The Markdown files in the `docs` directory are imported from the [amsterdam/development-standards project](https://github.com/Amsterdam/development-standards).
+This is a [Docusaurus](https://docusaurus.io/) application. The Markdown files in the `docs` directory are imported from the [amsterdam/development-standards project](https://github.com/Amsterdam/development-standards).
 
 ## Aims of this repo
 
@@ -16,46 +16,21 @@ If a standard is labeled as a recommendation, it indicates that it is not widely
 
 ## How to contribute to this repo?
 
-If you would like to include additional standards, please refer to the manual for instructions on implementing new standards. (TODO: Create a link to the implementation page of standards.) If you have any other matters to bring to our attention, you can contact us via Slack (#engineering-enablement) or Teams (DV - Engineering Enablement).
+If you would like to include additional standards, please refer to the [manual for instructions on implementing new standards](https://developers.amsterdam/docs/general/project-documentation). If you have any other matters to bring to our attention, you can contact us via Slack (#engineering-enablement) or Teams (DV - Engineering Enablement).
 
-## Docusaurus
+## Project documentation
 
-This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
+### Docusaurus basic commands
 
-### Installation
+- [Docusaurus basic commands](./internal-docs/docusaurus.md)
 
-```bash
-npm run
-```
+### Generating a release
 
-### Local Development
+- [Importing documentation](./internal-docs/importing-docs.md)
+- [Local documentation](./internal-docs/local-docs.md)
+- [Deploying](./internal-docs/deploying.md)
 
-```bash
-npm run start
-```
+### Markdown
 
-This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
-
-### Build
-
-```bash
-npm run build
-```
-
-This command generates static content into the `build` directory and can be served using any static contents hosting service.
-
-### Deployment
-
-Using SSH:
-
-```bash
-USE_SSH=true npm run deploy
-```
-
-Not using SSH:
-
-```bash
-GIT_USER=<Your GitHub username> npm run deploy
-```
-
-If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.
+- [Markdown metadata](./internal-docs/markdown-metadata.md)
+- [Markdown rules](./internal-docs/markdown-rules.md)

docs/backend/docker-usage.md

@@ -0,0 +1,67 @@
+# Docker Standard for Internal Application Development and Deployment
+> This page was last reviewed 10th October 2024. It needs to be reviewed again on the 10th April 2025.
+## What is the standard for Docker?
+Use Docker for containerization in the development, testing, and production of applications within the Municipality. Developers must use Dockerfiles that meet the minimum requirements outlined below. Dockerfiles are stored in the application repository in **GitHub**, while the compiled Docker images are stored in **Azure Container Registry (ACR)**.
+
+## When and for whom is this standard applicable?
+This guideline applies to all developers (front-end and back-end), IT administrators, and DevOps teams within the Municipality. It applies to all projects. Projects that started before September 2024 with a different configuration must be adapted to this standard.
+
+## What is required when using Docker?
+
+- **Dockerfile**: A Dockerfile is mandatory and must meet the following minimum requirements:
+    - [ ] **Base Image**: Use well-known and well-maintained base images and make sure that the version number is the latest, otherwise -2/-3 of the latest version. In addition, it is of high importance that the version number should **never** explicitly state `latest`. The most commonly used images are: Alpine, NGINX, Node.js, PHP, Postgres, Python and Ubuntu.
+    - [ ] **Minimal Installations**: Limit the installation of additional packages to what is strictly necessary to keep the image lightweight and secure.
+    - [ ] **Version Control**: Explicitly specify the versions of all dependencies to ensure consistency.
+- **Docker Image Storage**: Dockerfiles must be stored in the application repository in **GitHub**. The compiled Docker images must be stored in **ACR**. Only in cases where an image is shared across multiple teams or other municipalities may **Docker Hub** be used.
+
+## Standard ADO Pipelines
+
+For building and pushing images to **ACR**, you can refer to the standard ADO pipelines available at:
+[ADO Pipelines for building and pushing images to ACR](https://github.com/Amsterdam/common-azure-pipelines)
+
+### Example steps for deploying a Docker image to ACR:
+
+```bash
+az acr login --name <acr_name>
+docker build -t <acr_name>.azurecr.io/<image_name>:<tag> .
+docker push <acr_name>.azurecr.io/<image_name>:<tag>
+```
+
+- **Security**: The use of environment variables is mandatory for safely managing sensitive data. Avoid hard-coded sensitive information in Dockerfiles. If additional security is required, consider using **Docker Secrets** or other tools such as **GitHub Secrets**, **Azure Key Vault**, or **ADO Secrets**, depending on the application and the sensitivity of the data.
+
+### Example of using environment variables:
+
+```dockerfile
+# Set the environment variable for the database password
+ENV DB_PASSWORD=${DB_PASSWORD}
+
+# Run the Python application using the environment variable
+CMD ["python", "app.py"]
+```
+
+### Example of using Docker Secrets (only available with Docker Swarm):
+
+```bash
+# Docker Secrets are only available when using Docker Swarm
+# Create a Docker secret for the database password
+echo "mysecretpassword" | docker secret create db_password -
+
+# Use the secret to create a Docker service (Docker Swarm required)
+docker service create --name myapp --secret db_password myapp:latest
+```
+
+- **Regular Updates**: Docker images must be updated regularly to apply security patches and performance improvements. Establishing a minimum update frequency, such as monthly or quarterly, provides a clear framework for maintaining up-to-date images.
+
+## What to avoid?
+
+- Do not use unofficial or uncertified Docker images.
+- Avoid building different images for DTAP/OTAP-environments.
+
+## Considerations
+
+- **Compatibility with Existing Systems**: Thoroughly test Docker images to ensure compatibility with existing infrastructure before they are deployed to production.
+
+## Further Reading
+
+- [Docker Official Documentation](https://docs.docker.com/)
+- [Azure Container Registry Documentation](https://docs.microsoft.com/en-us/azure/container-registry/)

docs/frontend/languages-and-frameworks.md

@@ -1,6 +1,6 @@
 # Languages and Frameworks
 
-For all frontend projects within de Municipality of Amsterdam we choose to work with React and its ecosystem.
+For all frontend projects within the Municipality of Amsterdam we work with [NPM](https://www.npmjs.com/) for dependency management and the React library.
 
 ## Language
 

docs/frontend/shared-components.md

@@ -2,7 +2,10 @@
 
 Amsterdam has developed a couple of components that are being used
 
-- Maps (currently under revision)
 - [BMI DMS Upload](https://github.com/Amsterdam/bmi-dms-upload)
 - [Design System](https://github.com/Amsterdam/design-system)
 - [Wonen UI (component lib)](https://github.com/Amsterdam/wonen-ui)
+
+## Demos/examples
+
+- For developing with maps, there are demos and examples of common use-cases of maps at [https://maps.developers.amsterdam](https://maps.developers.amsterdam).

docs/frontend/third-party-dependencies.md

@@ -1,86 +1,27 @@
 # Third Party Dependencies
 
-It is common practice utilizing third-party libraries for our projects. Choosing the right one can be a difficult task. Therefore we curated a list of recommended packages and set guidelines for choosing a package which is not on the list.
+> This page was last reviewed on September 19th, 2024. It needs to be reviewed again on June 19th, 2025.
 
-## Guidelines for choosing a third party package.
+Guidelines for choosing a third party package can be found in the [general third party dependencies documentation page](../general/third-party-dependencies.md).
 
-When choosing a NPM package for your project please check the [recommended packages](#list-of-recommended-packages) list first. This is a curated list recommended by the frontend developer community of the Gemeente Amsterdam.
+## How can you secure front-end third-party integrations?
 
-If the packages in the list do not fit your requirements you can pick a non-recommended package. When do so, follow these guidelines.
+* Use modern browser features such as HTTPS, Content Security Policy (CSP), Subresource Integrity (SRI).
+  * use [HTTPS (Hypertext Transfer Protocol Secure)](https://developer.mozilla.org/en-US/docs/Glossary/HTTPS) for all your web traffic, including the requests and responses from third-party services. HTTPS encrypts the data in transit, preventing eavesdropping, tampering, or spoofing.
+  * [CSP (Content Security Policy)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP), a browser security feature that allows you to specify what is allowed on your website, such as scripts, styles, images and fonts. CSP can help prevent cross-site scripting (XSS) attacks, which can inject malicious code into your web pages through third-party integrations.
+  * [Subresource Integrity (SRI)](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity), a browser security feature that enables browsers to verify that the resources they fetch (for example, from a CDN) are delivered without unexpected manipulation.
+* Monitor and audit your integrations.
+  * Monitoring means keeping track of the performance, availability and errors of your integrations, using tools like logs, alerts, dashboards and reports. For example, [Azure Monitor](https://learn.microsoft.com/en-us/azure/azure-monitor/app/app-insights-overview).
+  * Auditing means reviewing the security and compliance of your integrations, using tools like scanners, analyzers and testers. For example, [GitHub Dependabot](https://docs.github.com/en/code-security/getting-started/dependabot-quickstart-guide), [NPM audit](https://docs.npmjs.com/cli/v10/commands/npm-audit) and [Snyk](https://snyk.io/).
+* Update and review your integrations (ideally annually).
+  * Updating means applying the latest patches and fixes.
+  * Reviewing means evaluating the quality, reliability and necessity.
 
-- Does it have the correct license?
-- Is the package health still good?
-  - Who is maintaining it?
-  - Is it actively maintained?
-  - How many downloads per week?
-- Does it have an acceptable bundle size?
-- Comparison of similar packages.s
+## Recommended third-party packages
 
-You could propose a package to the list of Recommonded Packages. Create a PR with a description to motivate your proposal.
+Maintaining a list of third-party frontend packages is too complex, therefore, we have reduced our recommendations to project build tools previously used by Gemeente Amsterdam projects.
 
-## List of recommended packages
-
-A collection of third party (React) libraries we recommend using in your frontend project.
-
-### Developer Environments
-
-- [Vite](https://github.com/vitejs/vite) - Next Generation Frontend Tooling
-  - [Vite community templates](https://github.com/vitejs/awesome-vite#templates) - Vite based project templates
-
-### Libraries
-
-#### Hooks
-
-- [useHooks](https://usehooks-ts.com/) - Set of typed utility hooks
-
-#### State management
-
-- [React Redux](https://github.com/reduxjs/react-redux) - Official React bindings for Redux
-  - [Redux Toolkit](https://github.com/reduxjs/redux-toolkit) - The official, opinionated, batteries-included toolset for efficient Redux development
-  - [Redux DevTools](https://github.com/reduxjs/redux-devtools) - DevTools for Redux with hot reloading, action replay, and customizable UI
-  - [Reselect](https://github.com/reduxjs/reselect) - Selector library for Redux
-  - [Redux Thunk](https://github.com/reduxjs/redux-thunk) - Thunk middleware for redux
-  - [redux-saga](https://github.com/redux-saga/redux-saga) - An alternative side effect model for Redux apps
-- [TanStack Query](https://github.com/TanStack/query) - Powerful asynchronous state management
-- [Jotai](https://github.com/pmndrs/jotai) - Bottom-up approach to React state management with an atomic model
-
-#### Routing
-
-- [React Router](https://github.com/remix-run/react-router) - Declarative routing for React
-
-#### Forms
-
-- [React Hook Form](https://github.com/react-hook-form/react-hook-form) - React Hooks for form state management and validation
-
-#### UI Components
-
-- [React-select](https://github.com/JedWatson/react-select) - The Select Component for React
-- [React DnD](https://github.com/react-dnd/react-dnd) - Drag and Drop for React
-- [react-dropzone](https://github.com/react-dropzone/react-dropzone) - Simple drag-drop zone with React
-
-#### Testing
-
-- [Jest](https://github.com/facebook/jest) - Delightful JavaScript Testing
-- [Enzyme](https://github.com/enzymejs/enzyme) - JavaScript Testing utilities for React
-- [React Testing Library](https://github.com/testing-library/react-testing-library) - Simple and complete React DOM testing utilities
-- [Vitest](https://vitest.dev/) - A Vite-native testing framework.
-
-#### Component Sandbox
-
-- [Storybook](https://github.com/storybookjs/storybook) - Storybook is a frontend workshop for building UI components and pages in isolation
-
-#### Schema validators
-
-- [Zod](https://github.com/colinhacks/zod)
-- [Yup](https://github.com/jquense/yup)
-
-#### Utilities
-
-- [Classnames](https://github.com/JedWatson/classnames)
-- [clsx](https://github.com/lukeed/clsx)
-- [Lodash](https://lodash.com/)
-- [date-fns](https://date-fns.org/)
-
-## Managing dependencies
-
-> _To Be Defined_
+* [Vite](https://github.com/vitejs/vite) - Next Generation Frontend Tooling
+  * [Vite community templates](https://github.com/vitejs/awesome-vite#templates) - Vite based project templates
+* [Webpack](https://github.com/vitejs/vite) - Next Generation Frontend Tooling
+* [esbuild](https://esbuild.github.io/) - Next Generation Frontend Tooling

docs/general/project-documentation.md

@@ -12,7 +12,7 @@ This standard must be applied to all new repositories of the city of Amsterdam (
 Project documentation must include the following:
 - [ ] the main idea of the application
 - [ ] the license [EU-PL v1.2](https://eupl.eu/1.2/en/)
-- [ ] a ReadMe (please follow the guidelines on what to include in a ReadMe [ToDO: reference to where documentation about ReadMes will be])
+- [ ] a ReadMe (please follow [the guidelines](readme-default.md) on what to include in a ReadMe )
 - [ ] all architectural decisions made, use the format Architecture Decision Record (ADR)
 - [ ] a changelog and a future review date
 - [ ] information about what data is processed by the application

docs/general/storing-source-code.md

@@ -1,14 +1,14 @@
 # Store your project in GitHub
-> This page was last reviewed May 7th 2024. It needs to be reviewed again on February 7th, 2025.
+> This page was last reviewed August 6th 2024. It needs to be reviewed again on May 6th, 2025.
 
 ## How to store projects on Github?
-All projects must have their repository on GitHub in the account of the city of Amsterdam and should be public,
+- All projects must have their repository on GitHub in the account of the city of Amsterdam and should be public,
 see the section "Public or private" for allowed exemptions.
-You must use Git to store your code on GitHub.
-Secure your repository by enabling these branch protection rules:
-- Require a pull request before merging
-  - Require approvals
-    - The required number of approvals before merging is at least 1
+- You must use Git to store your code on GitHub. Include a CODEOWNER file with your team name in the source code. See [the EE-docs repository](https://github.com/Amsterdam/ee-docs/blob/develop/CODEOWNERS) for an example.
+- Secure your repository by enabling these branch protection rules:
+  - Require a pull request before merging
+    - Require approvals
+      - The required number of approvals before merging is at least 1
 
 ## When and for whom is this standard?
 This standard applies to all developers.<br/>
@@ -35,6 +35,7 @@ but protects us from exposing sensitive information that could benefit potential
 
 ## Further reading
 - [The GitHub documentation](https://docs.github.com/en/get-started) is a good source of information.
+- [GitHub](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners) also has information about CODEOWNER files. 
 
 ## Acknowledgments
 Many thanks to [Hee Chan van der Haar](https://github.com/hcvdhaar), [Benny van de Hoogen](https://github.com/bennyvdhoogen) and [Sirée Koolen-Wijkstra](https://github.com/SireeKoolenWijkstra)

docs/general/third-party-dependencies.md

@@ -1,10 +1,46 @@
+# Third Party Dependencies
 
-- how to choose?
-  - recommended packages
-  - process on choosing non-recommended packages
-  - hard criteria (license)
-  - LTS versions
-
-- managing dependencies (dependabot, etc)
+> This page was last reviewed on September 19th, 2024. It needs to be reviewed again on June 19th, 2025.
 
+Third party dependencies can be introduced via:
 
+* using a dependency management tool (for example, [Composer for PHP](https://getcomposer.org/), [NPM for JavaScript](https://www.npmjs.com/) and [Poetry for Python](https://python-poetry.org/))
+* copying the code from a library/package
+* forked repositories or internal repositories for third party libraries/packages
+
+It is common to use third-party libraries/packages, however, choosing the right library/package can be a difficult task. To help, we have established guidelines for choosing a package.
+
+## Guidelines for choosing a third party package
+
+When selecting a package that has not been previously used in a Gemeente Amsterdam project, we ask the following questions:
+
+* Documentation
+  * Is there documentation?
+  * Are there tutorials or guides?
+  * How steep is the learning curve?
+* Licensing considerations
+  * Does the license fit with your project's requirements?
+  * Are there any usage restrictions?
+    * *Generally packages with MIT, Apache 2.0, BSD and EUPL are safe to use for commercial purpose. If you choose a package with a license that is not one of those, please read the license carefully. [This page](https://choosealicense.com/licenses/) is helpful in providing a simple overview.*
+* Performance
+  * Does it have an acceptable bundle size?
+    * This is more relevant for frontend projects.
+  * Does it integrate well with other libraries?
+* Security
+  * Does the package have any open security vulnerabilities?
+  * How quickly are security issues patched?
+* Stability
+  * How old is the project?
+  * Is there a roadmap?
+* Support
+  * Who is maintaining it?
+    * A single person / An open-source community / An organisation
+  * Is the project sponsored?
+  * Is it actively maintained?
+    * How many open and closed issues are there in the last several months?
+  * How many downloads are there per month/year?
+    * [npm trends](https://npmtrends.com/) provides useful metrics for NPM package download numbers and similar packages.
+    * [Packagist](https://packagist.org/) provides useful metrics for PHP package download numbers
+    * [PePy](https://www.pepy.tech/) provides useful metrics for Python package download numbers
+
+If the answer to the majority of these questions is negative then the third party code should not be used. If you have mixed answers to these questions and are unsure, post a question in your relevant gilde channel to discuss and hear other possible solutions.