diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile index 0444b5cc50..4b96b6b22b 100644 --- a/.devcontainer/Dockerfile +++ b/.devcontainer/Dockerfile @@ -1,8 +1,11 @@ -# See here for image contents: https://github.com/microsoft/vscode-dev-containers/blob/v0.202.3/containers/python-3/.devcontainer/base.Dockerfile -# [Choice] Python version (use -bullseye variants on local arm64/Apple Silicon): 3, 3.9, 3.8, 3.7, 3.6, 3-bullseye, 3.9-bullseye, 3.8-bullseye, 3.7-bullseye, 3.6-bullseye, 3-buster, 3.9-buster, 3.8-buster, 3.7-buster, 3.6-buster +# See here for image contents: https://github.com/devcontainers/images/tree/main/src/python +# [Choice] Python version (use -bullseye variants on local arm64/Apple Silicon): 3, 3.9, 3.8, 3.7, 3.6, 3-bullseye, 3.9-bullseye, 3.8-bullseye, 3.7-bullseye, 3.6-bullseye ARG VARIANT=3-bullseye -FROM mcr.microsoft.com/vscode/devcontainers/python:0-${VARIANT} +FROM mcr.microsoft.com/devcontainers/python:1-${VARIANT} + +# Remove stale Yarn apt repository that has an expired GPG key and causes apt-get update failures +RUN rm -f /etc/apt/sources.list.d/yarn.list /etc/apt/sources.list.d/yarn.list.save # [Optional] Allow the vscode user to pip install globally w/o sudo ENV PIP_TARGET=/usr/local/pip-global diff --git a/.devcontainer/devcontainer-lock.json b/.devcontainer/devcontainer-lock.json new file mode 100644 index 0000000000..5c9909954c --- /dev/null +++ b/.devcontainer/devcontainer-lock.json @@ -0,0 +1,9 @@ +{ + "features": { + "ghcr.io/devcontainers/features/docker-in-docker:2": { + "version": "2.17.0", + "resolved": "ghcr.io/devcontainers/features/docker-in-docker@sha256:25b9f05705ffba7dbe503230ac76081419306f8c8bc88e0ce78c4ecd99a0c78c", + "integrity": "sha256:25b9f05705ffba7dbe503230ac76081419306f8c8bc88e0ce78c4ecd99a0c78c" + } + } +} diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index 1fc2fde6e9..d77676af8e 100644 --- a/.devcontainer/devcontainer.json +++ b/.devcontainer/devcontainer.json @@ -15,33 +15,41 @@ } }, - // Set *default* container specific settings.json values on container create. - "settings": { - "terminal.integrated.profiles.linux": { - "bash": { - "path": "/bin/bash" - } - }, - "python.defaultInterpreterPath": "/usr/local/bin/python", - "python.languageServer": "Default", - "python.linting.enabled": true, - "python.linting.pylintEnabled": true, - "python.formatting.autopep8Path": "/usr/local/py-utils/bin/autopep8", - "python.formatting.blackPath": "/usr/local/py-utils/bin/black", - "python.formatting.yapfPath": "/usr/local/py-utils/bin/yapf", - "python.linting.banditPath": "/usr/local/py-utils/bin/bandit", - "python.linting.flake8Path": "/usr/local/py-utils/bin/flake8", - "python.linting.mypyPath": "/usr/local/py-utils/bin/mypy", - "python.linting.pycodestylePath": "/usr/local/py-utils/bin/pycodestyle", - "python.linting.pydocstylePath": "/usr/local/py-utils/bin/pydocstyle", - "python.linting.pylintPath": "/usr/local/py-utils/bin/pylint" + // Features to add to the dev container. + "features": { + "ghcr.io/devcontainers/features/docker-in-docker:2": {} }, - // Add the IDs of extensions you want installed when the container is created. - "extensions": [ - "ms-python.python", - "ms-python.vscode-pylance" - ], + "customizations": { + "vscode": { + // Set *default* container specific settings.json values on container create. + "settings": { + "terminal.integrated.profiles.linux": { + "bash": { + "path": "/bin/bash" + } + }, + "python.defaultInterpreterPath": "/usr/local/bin/python", + "python.languageServer": "Default", + "python.linting.enabled": true, + "python.linting.pylintEnabled": true, + "python.formatting.autopep8Path": "/usr/local/py-utils/bin/autopep8", + "python.formatting.blackPath": "/usr/local/py-utils/bin/black", + "python.formatting.yapfPath": "/usr/local/py-utils/bin/yapf", + "python.linting.banditPath": "/usr/local/py-utils/bin/bandit", + "python.linting.flake8Path": "/usr/local/py-utils/bin/flake8", + "python.linting.mypyPath": "/usr/local/py-utils/bin/mypy", + "python.linting.pycodestylePath": "/usr/local/py-utils/bin/pycodestyle", + "python.linting.pydocstylePath": "/usr/local/py-utils/bin/pydocstyle", + "python.linting.pylintPath": "/usr/local/py-utils/bin/pylint" + }, + "extensions": [ + "ms-python.python", + "ms-python.vscode-pylance", + "ms-azuretools.vscode-docker" + ] + } + }, // Use 'forwardPorts' to make a list of ports inside the container available locally. "forwardPorts": [8000], @@ -60,12 +68,12 @@ // }, // Use 'postCreateCommand' to run commands after the container is created. - "postCreateCommand": "pip3 install -r requirements-docs.txt", + "postCreateCommand": "pip3 install -r requirements-docs.txt && chmod +x .devcontainer/run-megalinter.sh", // Comment out to connect as root instead. More info: https://aka.ms/vscode-remote/containers/non-root. "remoteUser": "vscode", "mounts": [ "source=${localEnv:HOME}${localEnv:USERPROFILE}/.ssh,target=/home/vscode/.ssh,type=bind" - ], + ] } \ No newline at end of file diff --git a/.devcontainer/run-megalinter.sh b/.devcontainer/run-megalinter.sh new file mode 100755 index 0000000000..9694f1b827 --- /dev/null +++ b/.devcontainer/run-megalinter.sh @@ -0,0 +1,21 @@ +#!/usr/bin/env bash +# Run MegaLinter locally from the devcontainer — mirrors the CI setup in +# .github/workflows/mega-linter.yml and config in .mega-linter.yml. +# +# Usage: +# .devcontainer/run-megalinter.sh # lint only changed files +# VALIDATE_ALL_CODEBASE=true .devcontainer/run-megalinter.sh # lint everything +# +# Reports are written to ./megalinter-reports/ in the repo root. +set -euo pipefail + +REPO_ROOT="$(git rev-parse --show-toplevel)" +VALIDATE_ALL="${VALIDATE_ALL_CODEBASE:-false}" + +echo "Running MegaLinter (VALIDATE_ALL_CODEBASE=${VALIDATE_ALL})..." +docker run --rm \ + -v "${REPO_ROOT}:/tmp/lint" \ + -w /tmp/lint \ + -e VALIDATE_ALL_CODEBASE="${VALIDATE_ALL}" \ + -e DEFAULT_BRANCH=main \ + oxsecurity/megalinter:v8.1.0 diff --git a/.gitignore b/.gitignore index 8b0acb5a80..39bb17b28c 100644 --- a/.gitignore +++ b/.gitignore @@ -345,3 +345,6 @@ _site site/ mkdocs/ megalinter-reports/ + +# Copilot project tracking +.copilot-tracking/ diff --git a/.projector/workItemTemplates/engineering-fundamentals.yml b/.projector/workItemTemplates/engineering-fundamentals.yml index f0822a936f..79d8a0418d 100644 --- a/.projector/workItemTemplates/engineering-fundamentals.yml +++ b/.projector/workItemTemplates/engineering-fundamentals.yml @@ -53,7 +53,7 @@ items: The process for design reviews should be documented and available to the whole team from the outset of the project. This story is to explicitly document that process in the team's [working - agreement](https://microsoft.github.io/code-with-engineering-playbook/agile-development/team-agreements/working-agreements/readme/) + agreement](https://microsoft.github.io/code-with-engineering-playbook/agile-development/team-agreements/working-agreements/) acceptanceCriteria: - Design review process is well-documented within the working agreement diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e9a6b395c0..80c0c36445 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -18,7 +18,7 @@ If you are unsure if your content will match this playbook, you are welcome to c ## General guidance - Quality is more important than quantity -- Write in a way that you would want someone else to explain something to you. Use [`plain english`](http://www.plainenglish.co.uk/how-to-write-in-plain-english.html) +- Write in a way that you would want someone else to explain something to you. Use [`plain english`](https://www.plainenglish.co.uk/) - Be friendly, technical, professional and concise - Communicate as engineers, not marketing; we want to share what we learned, not "sell" our ideas - Don't recreate introductory content, link to it diff --git a/docs/CI-CD/continuous-integration.md b/docs/CI-CD/continuous-integration.md index 6d80d491a8..f7a6571aae 100644 --- a/docs/CI-CD/continuous-integration.md +++ b/docs/CI-CD/continuous-integration.md @@ -233,7 +233,7 @@ In the spirit of transparency and embracing frequent communication across a dev ### Everyone Commits to the Git Repository Each Day - End of day checked-in code should contain unit tests at the minimum. -- Run the build locally before checking in to avoid CI pipeline failure saturation. You should verify what caused the error, and try to solve it as soon as possible instead of committing your code. We encourage developers to follow a [lean SDLC principles](https://leankit.com/learn/lean/principles-of-lean-development/). +- Run the build locally before checking in to avoid CI pipeline failure saturation. You should verify what caused the error, and try to solve it as soon as possible instead of committing your code. We encourage developers to follow a [lean SDLC principles](https://en.wikipedia.org/wiki/Lean_software_development). - Isolate work into small chunks which ties directly to business value and refactor incrementally. ## Isolated Environments diff --git a/docs/UI-UX/README.md b/docs/UI-UX/README.md index 26eb0cb0c4..c5562e1ca1 100644 --- a/docs/UI-UX/README.md +++ b/docs/UI-UX/README.md @@ -63,7 +63,7 @@ Design Ops, short for Design Operations, is a practice that focuses on optimizin - Creating and maintaining a design system that includes reusable components, style guides, and design tokens. - Promoting consistency and efficiency by using shared design assets. - For most projects within ISE we use [Fluent UI](https://developer.microsoft.com/en-us/fluentui#/controls/webcomponents) to handle most projects, this enables rapid development that allow for web application re-use on non-customer engagements or _white label_ applications. - - Other Design Systems used by customers include: [Google's Material Design](https://mui.com/material-ui/), + - Other Design Systems used by customers include: [Google's Material Design](https://mui.com/material-ui/), 4. **Documentation**: - Documenting design decisions, guidelines, and best practices. @@ -77,7 +77,7 @@ Design Ops, short for Design Operations, is a practice that focuses on optimizin 6. **Metrics and KPIs**: - Defining key performance indicators (KPIs) to measure the effectiveness of design processes. - Using metrics to identify areas for improvement and track progress over time. - - __For long-term projects:__ Incorporate _A/B testing_ for better user experiences, and enhancements to the solution. + - **For long-term projects:** Incorporate _A/B testing_ for better user experiences, and enhancements to the solution. ### Benefits of Design Ops for Software Engineers and Product Owners @@ -90,19 +90,19 @@ By integrating Design Ops into the development process, software engineers can w ## Establishing a web application's architecture -The benefit of building software applications is that there are truly infinite ways to build something. A team can use the latest shiny tools, or they can utilize the tried-and-tested ones. It is for this reason that focussing completely on the user until a solution is defined is better than obsessing over technology choices. +The benefit of building software applications is that there are truly infinite ways to build something. A team can use the latest shiny tools, or they can utilize the tried-and-tested ones. It is for this reason that focussing completely on the user until a solution is defined is better than obsessing over technology choices. When choosing a front-end framework or library, consider the project's complexity, performance, and scalability needs. Evaluate the team's expertise with potential options to ensure efficient development. Assess long-term maintainability and community support. Conduct [Trade Studies](./../design/design-reviews/trade-studies/README.md) to weigh pros and cons, focusing on alignment with project goals and user experience. This thorough analysis helps balance innovation with practicality. -### Some platforms/frameworks to consider when planning a project: +### Some platforms/frameworks to consider when planning a project 1. HTML/CSS/JavaScript - Back to the basics! Start with a single **index.html**, include a popular CSS framework such as [Bootstrap](https://getbootstrap.com/) using their CDN link, and start prototyping! - Rarely will you have to support legacy browsers; thus, you can rely on modern JavaScript language features! No need for build tools or even TypeScript (did you know you can [type check JavaScript](https://www.typescriptlang.org/docs/handbook/intro-to-js-ts.html)). - - For static _vanilla_ websites like this; we still recommend a build system like [Vite](https://vitejs.dev/) to build and manage assets for deployment. + - For static _vanilla_ websites like this; we still recommend a build system like [Vite](https://vite.dev/) to build and manage assets for deployment. 1. React - - [React](https://reactjs.org/) allows for the creation of reusable UI components, and is used for most projects in ISE. + - [React](https://react.dev/) allows for the creation of reusable UI components, and is used for most projects in ISE. - Ideal for projects that require a dynamic and responsive user interface. - Works well with a variety of state management libraries like Redux or Context API. - Has a massive 3rd party library support. @@ -112,7 +112,7 @@ When choosing a front-end framework or library, consider the project's complexit - A robust framework for building client-side applications. [Angular](https://angular.dev/) provides a comprehensive solution with built-in features like dependency injection, routing, and state management. - Ideal for large-scale applications where maintainability and scalability are crucial. - Better Unit Testing support out of the box than React. - - __Angular has no support for Fluent UI, and has tight integration with Google Cloud Platform.__ + - **Angular has no support for Fluent UI, and has tight integration with Google Cloud Platform.** 1. Blazor - A framework for building interactive web UIs using C# instead of JavaScript. [Blazor](https://dotnet.microsoft.com/en-us/apps/aspnet/web-apps/blazor) allows you to share code between the client and server. - Great for teams already familiar with the .NET ecosystem. @@ -125,7 +125,7 @@ When choosing a front-end framework or library, consider the project's complexit - A React-based framework that enables server-side rendering and static site generation. [Next.js](https://nextjs.org/) improves performance and SEO. - Great for building fast, scalable web applications with a focus on developer experience. - Provides built-in support for API routes, making it easier to build full-stack applications. - - __Recommended by Meta going forward rather than use create-react-app.__ + - **Recommended by Meta going forward rather than use create-react-app.** - Next.js is very heavy in terms of features, and it doesn't allow for re-use in non-Next.js applications like create-react-app, React-Native, or Electron based apps. 1. Svelte - [Svelte](https://svelte.dev/) is a modern framework that shifts much of the work to compile time, resulting in highly optimized and performant applications. @@ -146,5 +146,5 @@ When choosing a front-end framework or library, consider the project's complexit ### Further information > For more information of utilizing any of these frameworks/platforms, read the [Recommended Technologies](./recommended-technologies.md) document. -> +> > Continue reading the [Trade Study](./../design/design-reviews/trade-studies/README.md) section of this site for more information on completing this step in the design process. diff --git a/docs/UI-UX/recommended-technologies.md b/docs/UI-UX/recommended-technologies.md index b537c116be..61cd5b4b91 100644 --- a/docs/UI-UX/recommended-technologies.md +++ b/docs/UI-UX/recommended-technologies.md @@ -3,32 +3,32 @@ ## Table of Contents - [TypeScript](#typescript) - - [Guidance on types and interfaces](#guidance-on-types-and-interfaces) - - [Example](#example) + - [Guidance on types and interfaces](#guidance-on-types-and-interfaces) + - [Example](#example) - [Bootstrapping Web Projects](#bootstrapping-web-projects) - - [Vite](#vite) - - [Documentation & Recommended Resources](#documentation--recommended-resources) - - [Installing Vite](#installing-vite) - - [Bootstrapping a project](#bootstrapping-a-project) + - [Vite](#vite) + - [Documentation & Recommended Resources](#documentation--recommended-resources) + - [Installing Vite](#installing-vite) + - [Bootstrapping a project](#bootstrapping-a-project) - [React](#react) - - [Quick note on create-react-app](#quick-note-on-create-react-app) - - [Documentation & Using older React coding patterns](#documentation--using-older-react-coding-patterns) - - [Best Practices to Organize Your React Codebase](#best-practices-to-organize-your-react-codebase) - - [Project Structure](#project-structure) - - [Key Directories and Files](#key-directories-and-files) - - [Directory Best Practices](#directory-best-practices) - - [Using React with Entra ID](#using-react-with-entra-id) - - [Resources](#resources) + - [Quick note on create-react-app](#quick-note-on-create-react-app) + - [Documentation & Using older React coding patterns](#documentation--using-older-react-coding-patterns) + - [Best Practices to Organize Your React Codebase](#best-practices-to-organize-your-react-codebase) + - [Project Structure](#project-structure) + - [Key Directories and Files](#key-directories-and-files) + - [Directory Best Practices](#directory-best-practices) + - [Using React with Entra ID](#using-react-with-entra-id) + - [Resources](#resources) - [Managing Secrets with Environmental Variables in React Projects Using Vite](#managing-secrets-with-environmental-variables-in-react-projects-using-vite) - - [Setting Up Environmental Variables](#setting-up-environmental-variables) - - [Best Security Practices](#best-security-practices) - - [Resources](#resources-1) + - [Setting Up Environmental Variables](#setting-up-environmental-variables) + - [Best Security Practices](#best-security-practices) + - [Resources](#resources-1) - [Common Security Pitfalls in React Applications](#common-security-pitfalls-in-react-applications) - - [Resources](#resources-2) + - [Resources](#resources-2) - [Incorporating Axios for REST API Calls in React with Bearer Tokens and MSAL](#incorporating-axios-for-rest-api-calls-in-react-with-bearer-tokens-and-msal) - - [Setting Up Axios](#setting-up-axios) - - [Making API Calls](#making-api-calls) - - [Resources](#resources-3) + - [Setting Up Axios](#setting-up-axios) + - [Making API Calls](#making-api-calls) + - [Resources](#resources-3) --- @@ -37,7 +37,7 @@ The purpose of this page is to review the commonly selected technology options w > Keep in mind that like all software, there is no "right way" to build a user interface application. Leverage and trust your team's or your customer's experience and expertise for the best development experience. -Additionally, while some of these technologies are presented as alternate options, many can be combined together. For example, you can use React in a basic HTML/CSS/JS workflow by inline-importing React along with Babel. See the [Add React to a Website](https://reactjs.org/docs/add-react-to-a-website.html) for more details. Similarly, any [Fast](https://www.fast.design/) web component can be [integrated into any existing React application](https://fast.design/docs/integrations#react). And of course, every JavaScript technology can also be used with TypeScript! +Additionally, while some of these technologies are presented as alternate options, many can be combined together. For example, you can use React in a basic HTML/CSS/JS workflow by inline-importing React along with Babel. See the [Add React to a Website](https://react.dev/learn/add-react-to-an-existing-project) for more details. Similarly, any [Fast](https://www.fast.design/) web component can be [integrated into any existing React application](https://fast.design/docs/3.x/introduction/). And of course, every JavaScript technology can also be used with TypeScript! ## TypeScript @@ -79,23 +79,23 @@ For more details, refer to the [TypeScript Handbook](https://www.typescriptlang. ## Bootstrapping Web Projects -There are many different ways to bootstrap web applications. Two great tool sets to use are [create-react-app](https://create-react-app.dev/) and [vite](https://vitejs.dev/guide). +There are many different ways to bootstrap web applications. Two great tool sets to use are [create-react-app](https://create-react-app.dev/) and [vite](https://vite.dev/guide). ### Vite -[Vite](https://vitejs.dev/) is a modern build tool that provides a fast and optimized development experience for engineers. It leverages native ES modules in the browser to deliver lightning-fast hot module replacement (HMR) and instant server start. [Vite](https://vitejs.dev/) also offers a highly optimized build process using [Rollup](https://rollupjs.org/introduction/), ensuring efficient and performant production builds. By simplifying the setup and configuration, [Vite](https://vitejs.dev/) allows developers to focus more on writing code and less on tooling, making it an excellent choice for modern web development. For more details, visit the [Vite project](https://vitejs.dev/) and [Vite GitHub repository](https://github.com/vitejs/vite). +[Vite](https://vite.dev/) is a modern build tool that provides a fast and optimized development experience for engineers. It leverages native ES modules in the browser to deliver lightning-fast hot module replacement (HMR) and instant server start. [Vite](https://vite.dev/) also offers a highly optimized build process using [Rollup](https://rollupjs.org/introduction/), ensuring efficient and performant production builds. By simplifying the setup and configuration, [Vite](https://vite.dev/) allows developers to focus more on writing code and less on tooling, making it an excellent choice for modern web development. For more details, visit the [Vite project](https://vite.dev/) and [Vite GitHub repository](https://github.com/vitejs/vite). #### Documentation & Recommended Resources -- [Vite Documentation](https://vitejs.dev/guide/) +- [Vite Documentation](https://vite.dev/guide/) - [Vite GitHub Repository](https://github.com/vitejs/vite) -- [Vite Rollup Plugin](https://vitejs.dev/guide/api-plugin.html) -- [Vite HMR](https://vitejs.dev/guide/features.html#hot-module-replacement) -- [Vite Configuration](https://vitejs.dev/config/) -- [Vite Plugins](https://vitejs.dev/plugins/) -- [Vite Troubleshooting](https://vitejs.dev/guide/troubleshooting.html) +- [Vite Rollup Plugin](https://vite.dev/guide/api-plugin.html) +- [Vite HMR](https://vite.dev/guide/features.html#hot-module-replacement) +- [Vite Configuration](https://vite.dev/config/) +- [Vite Plugins](https://vite.dev/plugins/) +- [Vite Troubleshooting](https://vite.dev/guide/troubleshooting.html) -From [Scaffolding your First Vite Project](https://vitejs.dev/guide/#scaffolding-your-first-vite-project) +From [Scaffolding your First Vite Project](https://vite.dev/guide/#scaffolding-your-first-vite-project) ##### Installing Vite @@ -118,7 +118,7 @@ React is a framework developed and maintained by Meta (Formerly Facebook). React ### Quick note on create-react-app -> __create-react-app is deprecated as of January 2023 and should be avoided for new projects.__ It is recommended to use more modern tools like [Vite](#vite) for better performance and flexibility. For more details, refer to the [official React blog](https://react.dev/blog) and [Vite documentation](https://vitejs.dev/guide/why.html). +> __create-react-app is deprecated as of January 2023 and should be avoided for new projects.__ It is recommended to use more modern tools like [Vite](#vite) for better performance and flexibility. For more details, refer to the [official React blog](https://react.dev/blog) and [Vite documentation](https://vite.dev/guide/why.html). From [Adding TypeScript](https://create-react-app.dev/docs/adding-typescript/) @@ -129,9 +129,9 @@ npx create-react-app my-app --template typescript ### Documentation & Using older React coding patterns -One can expect to find a multitude of guides, answers, and posts on how to work with React; don't take everything at face value. The best place to review React concepts is the React documentation. From there, you can review articles from various sources such as [React Community Articles](https://reactjs.org/community/articles.html), [Kent C Dodd's Blog](https://kentcdodds.com/blog?q=react), [CSS Tricks Articles](https://css-tricks.com/?s=react), and [Awesome React](https://github.com/enaqx/awesome-react). +One can expect to find a multitude of guides, answers, and posts on how to work with React; don't take everything at face value. The best place to review React concepts is the React documentation. From there, you can review articles from various sources such as [React Community Articles](https://legacy.reactjs.org/community/articles.html), [Kent C Dodd's Blog](https://kentcdodds.com/blog?q=react), [CSS Tricks Articles](https://css-tricks.com/?s=react), and [Awesome React](https://github.com/enaqx/awesome-react). -The React API has changed dramatically over time. Older resources may contain solutions or patterns that have since been changed and improved upon. Modern React development uses the [React Hooks](https://reactjs.org/docs/hooks-intro.html) pattern. Rarely will you have to implement something using [React Class](https://reactjs.org/docs/react-component.html) pattern. If you're reading an article/answer/docs that instruct you to use the class pattern you may be looking at an out-of-date resource. +The React API has changed dramatically over time. Older resources may contain solutions or patterns that have since been changed and improved upon. Modern React development uses the [React Hooks](https://legacy.reactjs.org/docs/hooks-intro.html) pattern. Rarely will you have to implement something using [React Class](https://legacy.reactjs.org/docs/react-component.html) pattern. If you're reading an article/answer/docs that instruct you to use the class pattern you may be looking at an out-of-date resource. ## Best Practices to Organize Your React Codebase @@ -187,42 +187,42 @@ my-react-app/ #### Key Directories and Files -- **public/**: Contains static assets like HTML and images. -- **src/**: Contains the source code of your application. - - **assets/**: Contains global assets like styles and images. - - **components/**: Contains reusable UI components, each in its own folder. - - **hooks/**: Contains custom React hooks. - - **pages/**: Contains page components, each in its own folder. - - **services/**: Contains service modules for API calls and other business logic. - - **types/**: Contains TypeScript type definitions. - - **utils/**: Contains utility functions. - - **App.tsx**: The root component of your application. - - **index.tsx**: The entry point of your application. - - **vite-env.d.ts**: TypeScript definitions for Vite-specific features. +- __public/__: Contains static assets like HTML and images. +- __src/__: Contains the source code of your application. + - __assets/__: Contains global assets like styles and images. + - __components/__: Contains reusable UI components, each in its own folder. + - __hooks/__: Contains custom React hooks. + - __pages/__: Contains page components, each in its own folder. + - __services/__: Contains service modules for API calls and other business logic. + - __types/__: Contains TypeScript type definitions. + - __utils/__: Contains utility functions. + - __App.tsx__: The root component of your application. + - __index.tsx__: The entry point of your application. + - __vite-env.d.ts__: TypeScript definitions for Vite-specific features. #### Directory Best Practices -1. **Component-Based Structure**: Organize your code into small, reusable components. -2. **Type Safety**: Use TypeScript to define types and interfaces for your components and data structures. -3. **Custom Hooks**: Encapsulate reusable logic in custom hooks. -4. **Service Layer**: Abstract API calls and business logic into service modules. -5. **Consistent Naming**: Follow a consistent naming convention for files and directories. -6. **Environment Variables**: Use environment variables to manage configuration settings. -7. **Testing**: Write unit tests for your components, hooks, and services. +1. __Component-Based Structure__: Organize your code into small, reusable components. +2. __Type Safety__: Use TypeScript to define types and interfaces for your components and data structures. +3. __Custom Hooks__: Encapsulate reusable logic in custom hooks. +4. __Service Layer__: Abstract API calls and business logic into service modules. +5. __Consistent Naming__: Follow a consistent naming convention for files and directories. +6. __Environment Variables__: Use environment variables to manage configuration settings. +7. __Testing__: Write unit tests for your components, hooks, and services. ### Using React with Entra ID -Integrating [React](https://reactjs.org/) applications with __Entra ID__ (formerly Azure Active Directory) allows you to secure your web applications with enterprise-grade authentication and authorization. This can be achieved using the [Microsoft Authentication Library (MSAL)](https://learn.microsoft.com/azure/active-directory/develop/msal-overview). +Integrating [React](https://react.dev/) applications with __Entra ID__ (formerly Azure Active Directory) allows you to secure your web applications with enterprise-grade authentication and authorization. This can be achieved using the [Microsoft Authentication Library (MSAL)](https://learn.microsoft.com/azure/active-directory/develop/msal-overview). To get started with Entra ID in your React application, follow these steps: -1. **Install MSAL**: +1. __Install MSAL__: ```sh npm install @azure/msal-browser @azure/msal-react ``` -2. **Configure MSAL**: +2. __Configure MSAL__: Create a configuration file to set up your MSAL instance with your Entra ID credentials. ```typescript @@ -240,7 +240,7 @@ To get started with Entra ID in your React application, follow these steps: ``` -3. **Wrap Your Application**: +3. __Wrap Your Application__: Use the `MsalProvider` to wrap your React application. ```typescript @@ -264,7 +264,7 @@ When developing React applications, it's crucial to manage sensitive information ### Setting Up Environmental Variables -1. **Create an `.env` File**: +1. __Create an `.env` File__: In the root of your project, create a file named `.env`. This file will store your environmental variables. ```plaintext @@ -272,7 +272,7 @@ When developing React applications, it's crucial to manage sensitive information VITE_API_URL=[sample URL] ``` -2. **Access Environmental Variables in Your Code**: +2. __Access Environmental Variables in Your Code__: Vite prefixes all environmental variables with `VITE_` to ensure they are exposed to your client-side code. You can access these variables using `import.meta.env`. ```typescript @@ -291,7 +291,7 @@ When developing React applications, it's crucial to manage sensitive information ### Best Security Practices -- **Do Not Commit `.env` Files**: +- __Do Not Commit `.env` Files__: Ensure your `.env` file is added to `.gitignore` to prevent it from being committed to your version control system. ```plaintext @@ -299,7 +299,7 @@ When developing React applications, it's crucial to manage sensitive information .env ``` -- **Use Environment-Specific Files**: +- __Use Environment-Specific Files__: Vite supports multiple environment files for different stages of development. For example, you can create `.env.development` and `.env.production` files to manage variables for development and production environments, respectively. ```plaintext @@ -310,21 +310,21 @@ When developing React applications, it's crucial to manage sensitive information VITE_API_URL=[example value] ``` -- **Validate Environmental Variables**: - Consider using a validation library like `zod` ( https://github.com/colinhacks/zod ) or `joi` ( joi.dev ) to validate your environmental variables at runtime, ensuring they meet the required format and constraints. +- __Validate Environmental Variables__: + Consider using a validation library like `zod` ( ) or `joi` ( joi.dev ) to validate your environmental variables at runtime, ensuring they meet the required format and constraints. ## Common Security Pitfalls in React Applications When developing React applications, it's crucial to follow best practices to safeguard your application from common security vulnerabilities. Here are some key things to avoid: -### 1. **Do Not Store Sensitive Data in Local Storage** +### 1. __Do Not Store Sensitive Data in Local Storage__ Local storage is accessible from any JavaScript code running on the same domain, making it a potential target for attackers. Avoid storing sensitive information like tokens or user data in local storage. -**Bearer Tokens in sessionStorage and localStorage should be strictly avoided!** +__Bearer Tokens in sessionStorage and localStorage should be strictly avoided!__ -### 2. **Avoid Using `dangerouslySetInnerHTML`** +### 2. __Avoid Using `dangerouslySetInnerHTML`__ Using `dangerouslySetInnerHTML` can expose your application to XSS attacks. Always sanitize any HTML content before rendering it. @@ -339,15 +339,15 @@ Using `dangerouslySetInnerHTML` can expose your application to XSS attacks. Alwa
``` -### 3. **Do Not Expose API Keys in the Frontend** +### 3. __Do Not Expose API Keys in the Frontend__ Exposing API keys in your frontend code can lead to unauthorized access to your backend services. Use environment variables and server-side code to keep your API keys secure. -### 4. **Do Not Ignore Security Updates** +### 4. __Do Not Ignore Security Updates__ Regularly update your dependencies to include the latest security patches. Use tools like `npm audit` to identify and fix vulnerabilities in your project. -### 5. **Avoid Using Untrusted Third-Party Libraries** +### 5. __Avoid Using Untrusted Third-Party Libraries__ Only use third-party libraries from trusted sources. Review the library's code and check for any known vulnerabilities before including it in your project. @@ -357,12 +357,12 @@ When building React applications that interact with REST APIs, [Axios](https://a ### Setting Up Axios -1. **Install Axios**: +1. __Install Axios__: ```sh npm install axios ``` -2. **Create an Axios Instance**: +2. __Create an Axios Instance__: Configure an Axios instance to include the Bearer token in the Authorization header for all requests. ```typescript diff --git a/docs/agile-development/advanced-topics/collaboration/pair-programming-tools.md b/docs/agile-development/advanced-topics/collaboration/pair-programming-tools.md index 80540a83d6..aef74e1f4b 100644 --- a/docs/agile-development/advanced-topics/collaboration/pair-programming-tools.md +++ b/docs/agile-development/advanced-topics/collaboration/pair-programming-tools.md @@ -20,7 +20,7 @@ With its cloud-based infrastructure, GitHub Codespaces presents a highly efficie ### Visual Studio Live Share -[Visual Studio Live Share](https://code.visualstudio.com/learn/collaboration/live-share) is specifically designed for pair programming and enables you to work on the same codebase, in real-time, with your team members. The arduous process of configuring complex setups, grappling with confusing configurations, straining one's eyes to work on small screens, or physically switching keyboards is not a problem with LiveShare. This solution enables seamless sharing of your development environment with your team members, facilitating smooth collaborative coding experiences. +[Visual Studio Live Share](https://visualstudio.microsoft.com/services/live-share/) is specifically designed for pair programming and enables you to work on the same codebase, in real-time, with your team members. The arduous process of configuring complex setups, grappling with confusing configurations, straining one's eyes to work on small screens, or physically switching keyboards is not a problem with LiveShare. This solution enables seamless sharing of your development environment with your team members, facilitating smooth collaborative coding experiences. Fully integrated into Visual Studio Code and Visual Studio, LiveShare offers the added benefit of terminal sharing, debug session collaboration, and host machine control. When paired with GitHub Codespaces, it presents a potent tool set for effective pair programming. @@ -29,6 +29,6 @@ Fully integrated into Visual Studio Code and Visual Studio, LiveShare offers the ## Resources * [GitHub Codespaces](https://code.visualstudio.com/docs/remote/codespaces). -* [VSCode Live Share](https://code.visualstudio.com/learn/collaboration/live-share). +* [VSCode Live Share](https://visualstudio.microsoft.com/services/live-share/). * [Create a Dev Container](https://code.visualstudio.com/docs/devcontainers/create-dev-container). * [How companies have optimized the humble office water cooler](https://www.inverse.com/innovation/how-companies-have-optimized-the-humble-office-water-cooler). diff --git a/docs/automated-testing/cdc-testing/README.md b/docs/automated-testing/cdc-testing/README.md index 3fc7a56009..821ddea278 100644 --- a/docs/automated-testing/cdc-testing/README.md +++ b/docs/automated-testing/cdc-testing/README.md @@ -52,7 +52,7 @@ Either way, thanks to CDC it is easy to pinpoint integration issues down to the [Pact](https://docs.pact.io/) is an implementation of CDC testing that allows mocking of responses in the consumer codebase, and verification of the interactions in the provider codebase, while defining a [specification for contracts](https://github.com/pact-foundation/pact-specification). It was originally written in Ruby but has available wrappers for multiple languages. Pact is the de-facto standard to use when working with CDC. -[Spring Cloud Contract](https://cloud.spring.io/spring-cloud-contract/reference/html) is an implementation of CDC testing from Spring, and offers easy integration in the Spring ecosystem. Support for non-Spring and non-JVM providers and consumers also exists. +[Spring Cloud Contract](https://docs.spring.io/spring-cloud-contract/docs/current/reference/html/) is an implementation of CDC testing from Spring, and offers easy integration in the Spring ecosystem. Support for non-Spring and non-JVM providers and consumers also exists. ## Conclusion diff --git a/docs/automated-testing/e2e-testing/README.md b/docs/automated-testing/e2e-testing/README.md index 3dde56102c..ccb1c900c8 100644 --- a/docs/automated-testing/e2e-testing/README.md +++ b/docs/automated-testing/e2e-testing/README.md @@ -137,7 +137,7 @@ Run tests in parallel or on a Selenium Grid with built-in Selenium WebDriver. Ra **Ranorex Studio** tests also integrate with Azure DevOps (AzDO), which can be run as part of a build pipeline in AzDO. -[Ranorex Studio Website](https://www.ranorex.com/free-trial) +[Ranorex Studio Website](https://www.ranorex.com/) ### 5. Katalon Studio diff --git a/docs/automated-testing/synthetic-monitoring-tests/README.md b/docs/automated-testing/synthetic-monitoring-tests/README.md index f07f29282e..06ecaaa008 100644 --- a/docs/automated-testing/synthetic-monitoring-tests/README.md +++ b/docs/automated-testing/synthetic-monitoring-tests/README.md @@ -84,7 +84,7 @@ Some organizations prefer running probes on existing infrastructure using known - [Application Insights availability](https://learn.microsoft.com/en-us/azure/azure-monitor/app/monitor-web-app-availability) - Simple availability tests that allow some customization using [Multi-step web test](https://learn.microsoft.com/en-us/azure/azure-monitor/app/availability-multistep) - [DataDog Synthetics](https://www.datadoghq.com/dg/apm/synthetics/api-test/) - [Dynatrace Synthetic Monitoring](https://www.dynatrace.com/platform/synthetic-monitoring/) -- [New Relic Synthetics](https://newrelic.com/products/synthetics) +- [New Relic Synthetics](https://newrelic.com/platform/synthetics) - [Checkly](https://checklyhq.com) ## Conclusion diff --git a/docs/automated-testing/unit-testing/README.md b/docs/automated-testing/unit-testing/README.md index c615ffd8e5..482791de9c 100644 --- a/docs/automated-testing/unit-testing/README.md +++ b/docs/automated-testing/unit-testing/README.md @@ -97,11 +97,11 @@ An example of using dependency injection can be found [here](./authoring-example #### Test-Driven Development -Test-Driven Development (TDD) is a technique for writing your code that will lead you to a testable design from the start. +Test-Driven Development (TDD) is a technique for writing your code that will lead you to a testable design from the start. The basic premise of test-driven development is that you come up with a list behaviors you want your system to have. You then take one behavior from the list, write the test, and then modify the system to make the test pass. Then you move on to the next behavior on your list and repeat this process. -Once you've exhausted your list, you're done! This approach has the benefit of guaranteeing a testable design is built into +Once you've exhausted your list, you're done! This approach has the benefit of guaranteeing a testable design is built into the system since the test was written first. For more information on TDD and an example, see the page on [Test-Driven Development](./tdd-example.md) diff --git a/docs/code-reviews/recipes/java.md b/docs/code-reviews/recipes/java.md index 8bcaf56ad3..1ae6c5cb21 100644 --- a/docs/code-reviews/recipes/java.md +++ b/docs/code-reviews/recipes/java.md @@ -8,7 +8,7 @@ Developers should follow the [Google Java Style Guide](https://google.github.io/ We strongly believe that consistent style increases readability and maintainability of a code base. Hence, we are recommending analyzers to enforce consistency and style rules. -We make use of [Checkstyle](https://github.com/checkstyle/checkstyle) using the [same configuration used in the Azure Java SDK](https://github.com/Azure/azure-sdk-for-java/blob/master/eng/code-quality-reports/src/main/resources/checkstyle/checkstyle.xml). +We make use of [Checkstyle](https://github.com/checkstyle/checkstyle) with rules similar to those used in the [Azure Java SDK](https://github.com/Azure/azure-sdk-for-java). [FindBugs](http://findbugs.sourceforge.net/) and [PMD](https://pmd.github.io/) are also commonly used. diff --git a/docs/code-reviews/recipes/markdown.md b/docs/code-reviews/recipes/markdown.md index 6af308426d..94aef0efc5 100644 --- a/docs/code-reviews/recipes/markdown.md +++ b/docs/code-reviews/recipes/markdown.md @@ -152,7 +152,7 @@ Save your guidelines together with your documentation, so they are easy to refer - Use active voice - Spell check and grammar check the text - Always follow chronological order -- Visit [Plain English](https://plainenglish.co.uk/how-to-write-in-plain-english.html) for tips on how to write documentation that is easy to understand. +- Visit [Plain English](https://www.plainenglish.co.uk/) for tips on how to write documentation that is easy to understand. ### Document Organization diff --git a/docs/design/design-patterns/non-functional-requirements-capture-guide.md b/docs/design/design-patterns/non-functional-requirements-capture-guide.md index 55949f5403..3361225aac 100644 --- a/docs/design/design-patterns/non-functional-requirements-capture-guide.md +++ b/docs/design/design-patterns/non-functional-requirements-capture-guide.md @@ -51,7 +51,7 @@ To support the process of capturing a project's _comprehensive_ non-functional r | Quality Attribute | Description | Common Metrics | | -- |-- |-- | | [Compliance](../../non-functional-requirements/compliance.md) | Adherence to legal, regulatory, and industry standards and requirements. | See [Microsoft Purview Compliance Manager](https://aka.ms/ComplianceManager) | -| [Privacy](../../privacy/README.md) | Protection of sensitive information and compliance with privacy regulations. | - Compliance with Privacy Regulations: Achieve full compliance with GDPR, CCPA and HIPAA.
- Data Anonymization: Implement anonymization techniques in protecting individual privacy while still allowing for data analysis.
- Data Encryption: Ensure that sensitive data is encrypted according to encryption standards and best practices.
- User Privacy Preferences: The ability to respect and accommodate user privacy preferences regarding data collection, processing, and sharing. | +| [Privacy](../../non-functional-requirements/privacy/README.md) | Protection of sensitive information and compliance with privacy regulations. | - Compliance with Privacy Regulations: Achieve full compliance with GDPR, CCPA and HIPAA.
- Data Anonymization: Implement anonymization techniques in protecting individual privacy while still allowing for data analysis.
- Data Encryption: Ensure that sensitive data is encrypted according to encryption standards and best practices.
- User Privacy Preferences: The ability to respect and accommodate user privacy preferences regarding data collection, processing, and sharing. | | [Security](../../security/README.md) | Establish the security requirements of the system, such as authentication, authorization, encryption, and compliance with industry or legal regulations. | See [Threat Modeling Tool](https://aka.ms/tmt) | | [Sustainability](../sustainability/README.md) | Ability to operate over an extended period while minimizing environmental impact and resource consumption. | - Energy Efficiency: Kilowatt-hours/Transaction.
- Carbon Footprint: Tons of CO2 emissions per year. | diff --git a/docs/design/diagram-types/README.md b/docs/design/diagram-types/README.md index 1055575012..5f29f81db4 100644 --- a/docs/design/diagram-types/README.md +++ b/docs/design/diagram-types/README.md @@ -32,4 +32,4 @@ Each of the above types of diagrams will provide specific resources related to i - [Visual Paradigm UML Structural vs Behavior Diagrams](https://www.visual-paradigm.com/cn/guide/uml-unified-modeling-language/uml-) - [PlantUML](https://marketplace.visualstudio.com/items?itemName=jebbs.plantuml) - requires a generator from code to PlantUML syntax to generate diagrams - [C# to PlantUML](https://marketplace.visualstudio.com/items?itemName=pierre3.csharp-to-plantuml) - - [Drawing manually](https://towardsdatascience.com/drawing-a-uml-diagram-in-the-vs-code-53c2e67deffe) + - Drawing manually diff --git a/docs/design/diagram-types/class-diagrams.md b/docs/design/diagram-types/class-diagrams.md index 2edca9090b..ba2d0ac8d7 100644 --- a/docs/design/diagram-types/class-diagrams.md +++ b/docs/design/diagram-types/class-diagrams.md @@ -69,4 +69,4 @@ the customer hand-off approaches. - [PlantUML](https://marketplace.visualstudio.com/items?itemName=jebbs.plantuml) - requires a generator from code to PlantUML syntax to generate diagrams - [PlantUML Syntax](https://plantuml.com/class-diagram) - [C# to PlantUML](https://marketplace.visualstudio.com/items?itemName=pierre3.csharp-to-plantuml) - - [Drawing manually](https://towardsdatascience.com/drawing-a-uml-diagram-in-the-vs-code-53c2e67deffe) + - Drawing manually diff --git a/docs/design/diagram-types/component-diagrams.md b/docs/design/diagram-types/component-diagrams.md index 09fe33c385..0a2b29f08b 100644 --- a/docs/design/diagram-types/component-diagrams.md +++ b/docs/design/diagram-types/component-diagrams.md @@ -73,4 +73,4 @@ Depending on the tool being used, automatic versioning might be performed whenev - VS Code Plugins: - [PlantUML](https://marketplace.visualstudio.com/items?itemName=jebbs.plantuml) - requires a generator from code to PlantUML syntax to generate diagrams - [PlantUML Syntax](https://plantuml.com/component-diagram) - - [Drawing manually](https://towardsdatascience.com/drawing-a-uml-diagram-in-the-vs-code-53c2e67deffe) + - Drawing manually diff --git a/docs/design/diagram-types/deployment-diagrams.md b/docs/design/diagram-types/deployment-diagrams.md index 162b01e90e..dfa6ae94d4 100644 --- a/docs/design/diagram-types/deployment-diagrams.md +++ b/docs/design/diagram-types/deployment-diagrams.md @@ -64,4 +64,4 @@ The below approach can be used to assist the team on how often to update the pub - [Visual Paradigm](https://www.visual-paradigm.com/guide/uml-unified-modeling-language/what-is-deployment-diagram/) - [PlantUML](https://marketplace.visualstudio.com/items?itemName=jebbs.plantuml) - requires a generator from code to PlantUML syntax to generate diagrams - [PlantUML Syntax](https://plantuml.com/deployment-diagram) - - [Drawing manually](https://towardsdatascience.com/drawing-a-uml-diagram-in-the-vs-code-53c2e67deffe) + - Drawing manually diff --git a/docs/design/diagram-types/sequence-diagrams.md b/docs/design/diagram-types/sequence-diagrams.md index 2cd46e9abd..a236fdfff6 100644 --- a/docs/design/diagram-types/sequence-diagrams.md +++ b/docs/design/diagram-types/sequence-diagrams.md @@ -121,4 +121,4 @@ the customer hand-off approaches. - VS Code Plugins: - [PlantUML](https://marketplace.visualstudio.com/items?itemName=jebbs.plantuml) - requires a generator from code to PlantUML syntax to generate diagrams - [PlantUML Syntax](https://plantuml.com/sequence-diagram) - - [Drawing manually](https://towardsdatascience.com/drawing-a-uml-diagram-in-the-vs-code-53c2e67deffe) + - Drawing manually diff --git a/docs/design/sustainability/README.md b/docs/design/sustainability/README.md index 93f6f23d46..d0f9a89539 100644 --- a/docs/design/sustainability/README.md +++ b/docs/design/sustainability/README.md @@ -36,13 +36,13 @@ If there are important nuances to consider, they will be linked in the `Disclaim | | | Consider caching data close to end users with a [CDN](https://en.wikipedia.org/wiki/Content_delivery_network) | [Networking](./sustainable-engineering-principles.md#networking) | [Benefits of a CDN](https://docs.microsoft.com/en-us/azure/frontdoor/front-door-overview#key-benefits) | [Understanding CDN tradeoffs](./sustainable-action-disclaimers.md#action-consider-caching-data-close-to-end-users-with-a-CDN) | | | | Send only the data that will be used | [Networking](./sustainable-engineering-principles.md#networking) | | | | | | Compress data to reduce the size | [Networking](./sustainable-engineering-principles.md#networking) | [Compressing and extracting files in .NET](https://docs.microsoft.com/en-us/dotnet/standard/io/how-to-compress-and-extract-files) | | -| | When designing for the end user | Consider giving users visibility and control over their energy usage | [Electricity Consumption](./sustainable-engineering-principles.md#electricity-consumption) [Demand Shaping](./sustainable-engineering-principles.md#demand-shaping) | [Designing for eco-mode](https://principles.green/principles/demand-shaping/#heading-eco-modes) | | +| | When designing for the end user | Consider giving users visibility and control over their energy usage | [Electricity Consumption](./sustainable-engineering-principles.md#electricity-consumption) [Demand Shaping](./sustainable-engineering-principles.md#demand-shaping) | [Designing for eco-mode](https://learn.greensoftware.foundation/carbon-awareness#demand-shaping) | | | | | Design and test your application to be compatible for a wide variety of devices, especially older devices | [Embodied Carbon](./sustainable-engineering-principles.md#embodied-carbon) | [Extending device lifespan](https://medium.com/google-design/to-make-apps-accessible-make-them-compatible-with-different-devices-11298c6d3f06) [Compatibility Testing](https://www.techdim.com/what-is-compatibility-testing/) | | | | When selecting a programming language | Consider the energy efficiency of languages | [Electricity Consumption](./sustainable-engineering-principles.md#electricity-consumption) | [Reasoning about the energy consumption of programming languages](https://thenewstack.io/which-programming-languages-use-the-least-electricity/), [Programming Language Energy Efficiency (PDF)](https://greenlab.di.uminho.pt/wp-content/uploads/2017/10/sleFinal.pdf) | [Making informed programming language choices](./sustainable-action-disclaimers.md#action-consider-the-energy-efficiency-of-languages) | ## Resources -- [Principles of Green Software Engineering](https://principles.green/) +- [Principles of Green Software Engineering](https://learn.greensoftware.foundation/) - [Green Software Foundation](https://greensoftware.foundation/) - [Microsoft Cloud for Sustainability](https://www.microsoft.com/en-us/sustainability) - [Learning Module: Sustainable Software diff --git a/docs/design/sustainability/sustainable-engineering-principles.md b/docs/design/sustainability/sustainable-engineering-principles.md index a114505f61..b79fdc77ff 100644 --- a/docs/design/sustainability/sustainable-engineering-principles.md +++ b/docs/design/sustainability/sustainable-engineering-principles.md @@ -1,16 +1,16 @@ # Sustainable Principles -The following principle overviews provide the foundations supporting specific actions in the [Sustainable Engineering Checklist](./README.md#sustainable-engineering-checklist). More details about each principle can be found by following the links in the headings or visiting the [Principles of Green Software Engineering website](https://principles.green/). +The following principle overviews provide the foundations supporting specific actions in the [Sustainable Engineering Checklist](./README.md#sustainable-engineering-checklist). More details about each principle can be found by following the links in the headings or visiting the [Principles of Green Software Engineering website](https://learn.greensoftware.foundation/). -## [Electricity Consumption](https://principles.green/principles/electricity/) +## [Electricity Consumption](https://learn.greensoftware.foundation/energy-efficiency) Most electricity is still produced through the burning of fossil fuels and is responsible for 49% of the carbon emitted into the atmosphere. Software consumes electricity in its execution. Running hardware consumes electricity even at zero percent utilization. Some of the best ways we can reduce electricity consumption and the subsequent emissions of carbon pollution is to make our applications more energy efficient when they are running and limit idle hardware. -## [Energy Proportionality](https://principles.green/principles/energy-proportionality/) +## [Energy Proportionality](https://learn.greensoftware.foundation/energy-efficiency#energy-proportionality) -![Illustrative graph showing a computer at 0% utilization draws 100 Watts, at 50% utilization it draws 180 Watts and at 100% utilization it draws 200 Watts. The relationship between power consumption and utilization is not linear and it does not cross the origin.](https://principles.green/assets/images/principles/energy-proportionality-1.png?v=e5febc24f5d4d4930ad43de3686aa856) +![Illustrative graph showing a computer at 0% utilization draws 100 Watts, at 50% utilization it draws 180 Watts and at 100% utilization it draws 200 Watts. The relationship between power consumption and utilization is not linear and it does not cross the origin.](https://learn.greensoftware.foundation/assets/images/06_energy_proportionality_updated-a6941b6c0d261511e74dc2217062373c.png) The relationship between power and utilization is not proportional. @@ -18,17 +18,17 @@ The more you utilize a computer, the more efficient it becomes at converting ele An idle computer, even running at zero percent utilization, still draws electricity. -## [Embodied Carbon](https://principles.green/principles/embodied-carbon/) +## [Embodied Carbon](https://learn.greensoftware.foundation/hardware-efficiency#embodied-carbon) Embodied carbon (otherwise referred to as "Embedded Carbon") is the amount of carbon pollution emitted during the creation and disposal of a device. When calculating the total carbon pollution for the computers running your software, account for both the carbon pollution to run the computer and the embodied carbon of the computer. Therefore a great way to reduce embodied carbon is to prevent the need for new devices to be manufactured by extending the usefulness of existing ones. -## [Demand Shaping](https://principles.green/principles/demand-shaping/) +## [Demand Shaping](https://learn.greensoftware.foundation/carbon-awareness#demand-shaping) Demand shaping is a strategy of shaping our demand for resources so it matches the existing supply. If supply is high, increase the demand by doing more in your applications. If the supply is low, decrease demand. This means doing less in your applications or delaying work until supply is higher. -## [Networking](https://principles.green/principles/networking/) +## [Networking](https://learn.greensoftware.foundation/) A network is a series of switches, routers, and servers. All the computers and network equipment in a network consume electricity and have [embedded carbon](#embodied-carbon). The internet is a global network of devices typically run off the standard local grid energy mix. diff --git a/docs/observability/observability-databricks.md b/docs/observability/observability-databricks.md index b657ac748c..6845b78cde 100644 --- a/docs/observability/observability-databricks.md +++ b/docs/observability/observability-databricks.md @@ -34,7 +34,7 @@ note that Linux OMS Agent is not specific to Azure Databricks. ### Application Logging -Of all the logs collected, this is perhaps the most important one. [Spark Monitoring library](https://github.com/mspnp/spark-monitoring) collects metrics about the driver, executors, JVM, HDFS, cache +Of all the logs collected, this is perhaps the most important one. Spark Monitoring library collects metrics about the driver, executors, JVM, HDFS, cache shuffling, DAGs, and much more. This library provides helpful insights to fine-tune Spark jobs. It allows monitoring and tracing each layer within Spark workloads, including performance and resource usage on the host and JVM, as well as Spark metrics and application-level logging. The library also includes ready-made Grafana dashboards that is a great starting point for building Azure Databricks dashboard. diff --git a/docs/observability/recipes-observability.md b/docs/observability/recipes-observability.md index 2a18ea69fa..fb5f9d6789 100644 --- a/docs/observability/recipes-observability.md +++ b/docs/observability/recipes-observability.md @@ -32,7 +32,7 @@ This dashboard recipe provides observability for AzDO pipelines by displaying va ## Python Logger Class for Application Insights using OpenCensus -The Azure SDK for Python contains an [Azure Monitor Opentelemetry Distro client library for Python ](https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/monitor/azure-monitor-opentelemetry). You can view samples of how to use the library in this [GitHub Repo](https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/monitor/azure-monitor-opentelemetry/samples). With this library you can easily collect traces, metrics, and logs. +The Azure SDK for Python contains an [Azure Monitor Opentelemetry Distro client library for Python](https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/monitor/azure-monitor-opentelemetry). You can view samples of how to use the library in this [GitHub Repo](https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/monitor/azure-monitor-opentelemetry/samples). With this library you can easily collect traces, metrics, and logs. ## Java OpenTelemetry Examples diff --git a/docs/observability/tools/loki.md b/docs/observability/tools/loki.md index 5dc82046df..68227c4cf7 100644 --- a/docs/observability/tools/loki.md +++ b/docs/observability/tools/loki.md @@ -33,6 +33,6 @@ of the log itself, using less space than just storing the raw logs. ## Resources - [Loki Official Site](https://grafana.com/oss/loki/) -- [Inserting logs into Loki](https://grafana.com/docs/loki/latest/getting-started/get-logs-into-loki/) +- [Inserting logs into Loki](https://grafana.com/docs/loki/latest/send-data/) - [Adding Loki Source to Grafana](https://grafana.com/docs/grafana/latest/datasources/loki/#adding-the-data-source) - [Loki Best Practices](https://grafana.com/docs/loki/latest/best-practices/) diff --git a/docs/source-control/component-versioning.md b/docs/source-control/component-versioning.md index c0f069207a..4b471ea602 100644 --- a/docs/source-control/component-versioning.md +++ b/docs/source-control/component-versioning.md @@ -79,7 +79,7 @@ This strategy allows projects to evolve at their own pace, without forcing all p `semantic-release` relies on commit messages to assess how codebase changes impact consumers. By adhering to structured conventions for commit messages, `semantic-release` autonomously identifies the subsequent semantic version, compiles a changelog, and releases the software. -[Angular Commit Message](https://gist.github.com/brianclements/841ea7bffdb01346392c) Conventions serve as the default for `semantic-release`. However, the configuration options of the @semantic-release/commit-analyzer and @semantic-release/release-notes-generator plugins, including presets, can be adjusted to modify the commit message format. +[Angular Commit Message](https://www.conventionalcommits.org/en/v1.0.0/) Conventions serve as the default for `semantic-release`. However, the configuration options of the @semantic-release/commit-analyzer and @semantic-release/release-notes-generator plugins, including presets, can be adjusted to modify the commit message format. The table below shows which commit message gets you which release type when `semantic-release` runs (using the default configuration): diff --git a/docs/source-control/git-guidance/README.md b/docs/source-control/git-guidance/README.md index 9970b5e498..e8dc61ef88 100644 --- a/docs/source-control/git-guidance/README.md +++ b/docs/source-control/git-guidance/README.md @@ -376,4 +376,4 @@ When working with a very large repository of which you don't require all the fil * Visual Studio Code is a cross-platform powerful source code editor with built in git commands. Within Visual Studio Code editor you can review diffs, stage changes, make commits, pull and push to your git repositories. You can refer to [Visual Studio Code Git Support](https://code.visualstudio.com/docs/editor/versioncontrol#_git-support) for documentation. * Use a shell/terminal to work with Git commands instead of relying on [GUI clients](https://git-scm.com/downloads/guis/). -* If you're working on Windows, [posh-git](https://github.com/dahlbyk/posh-git) is a great PowerShell environment for Git. Another option is to use [Git bash for Windows](http://www.techoism.com/how-to-install-git-bash-on-windows/). On Linux/Mac, install git and use your favorite shell/terminal. +* If you're working on Windows, [posh-git](https://github.com/dahlbyk/posh-git) is a great PowerShell environment for Git. Another option is to use [Git bash for Windows](https://gitforwindows.org/). On Linux/Mac, install git and use your favorite shell/terminal. diff --git a/lychee.toml b/lychee.toml index 2cdf5c0d5e..ddcc555e3a 100644 --- a/lychee.toml +++ b/lychee.toml @@ -49,7 +49,11 @@ retry_wait_time = 2 # accept = "200..=204, 429" # accept = ["200", "429"] # accept = "200, 429" -accept = ["200"] +# +# 403 (Forbidden) and 429 (Too Many Requests) are accepted because they indicate +# the target page exists but the host blocks or throttles automated clients in +# CI. Treating them as failures produces false positives for live links. +accept = ["200..=299", "403", "429"] # Proceed for server connections considered insecure (invalid TLS). insecure = false @@ -61,7 +65,7 @@ require_https = false method = "get" # Custom request headers -header = ["name=value", "other=value"] +# header = { name = "value", other = "value" } # Remap URI matching pattern to different URI. remap = [] @@ -96,10 +100,30 @@ exclude = [ "^https://github.com/marketplace/?$", # Other: "^https://opensource.org/license/", # works locally but fails with 403 on Github CI. + # Sites that block automated clients (TLS handshake / bot protection) but are + # valid in a browser: + "^https://www.postman.com", + "^https://blog.insightdatascience.com", + "^https://fate.fedai.org", + # Site with an expired TLS certificate (valid content, cert not renewed): + "^https://www.techdim.com", + # Valid but intermittently slow from CI (request timeouts): + "^https://www.gnu.org", + # Valid GitHub repos that trigger network errors under GitHub's bot protection: + "^https://github.com/tdurieux/anonymous_github", + # Academic and commercial sites that are valid but time out under automated checking: + "^https://dash.harvard.edu", + "^https://www.ranorex.com", + "^https://www.goodreads.com", + # vite.dev blocks GitHub Actions runner IPs with network errors: + "^https://vite.dev", + # invisionapp.com returns 500 for CI runner IPs (bot protection): + "^https://www.invisionapp.com", ] # Exclude these filesystem paths from getting checked. -exclude_path = [] +# .copilot-tracking and .projector are project-local metadata/tooling, not published documentation. +exclude_path = [".copilot-tracking", ".projector"] # URLs to check (supports regex). Has preference over all excludes. include = [] diff --git a/requirements-docs.txt b/requirements-docs.txt index 7fa7f29c0e..299dfa7973 100644 --- a/requirements-docs.txt +++ b/requirements-docs.txt @@ -1,6 +1,7 @@ mkdocs==1.3.* mkdocs-material==8.2.* pymdown-extensions>=10.0 +Pygments>=2,<2.20 markdown==3.3.* mdx_truly_sane_lists==1.2 mkdocs-git-revision-date-localized-plugin==1.0.*