diff --git a/_data/sidebars/dg_dev_sidebar.yml b/_data/sidebars/dg_dev_sidebar.yml index f4bff9aa8b2..8aec4dbe22d 100644 --- a/_data/sidebars/dg_dev_sidebar.yml +++ b/_data/sidebars/dg_dev_sidebar.yml @@ -567,6 +567,8 @@ entries: url: /docs/dg/dev/frontend-development/yves/multi-theme.html - title: Image optimization usage url: /docs/dg/dev/frontend-development/yves/implement-image-optimization.html + - title: Basic SEO techniques to use in your project + url: /docs/dg/dev/frontend-development/yves/basic-seo-techniques-to-use-in-your-project.html - title: Oryx url: /docs/dg/dev/frontend-development/oryx/oryx.html @@ -1329,6 +1331,18 @@ entries: - title: "Tutorial: Architectural walkthrough" url: /docs/dg/dev/architecture/tutorial-architectural-walkthrough.html + - title: Non-functional requirement templates + url: /docs/dg/dev/architecture/non-functional-requirement-templates/non-functional-requirement-templates.html + nested: + - title: Operational and deployment guidelines + url: /docs/dg/dev/architecture/non-functional-requirement-templates/operational-and-deployment-guidelines.html + - title: Monitorable process guidelines + url: /docs/dg/dev/architecture/non-functional-requirement-templates/monitorable-process-guidelines.html + - title: Operatable feature guidelines + url: /docs/dg/dev/architecture/non-functional-requirement-templates/operatable-feature-guidelines.html + - title: Process documentation guidelines + url: /docs/dg/dev/architecture/non-functional-requirement-templates/process-documentation-guidelines.html + - title: Data import url: /docs/dg/dev/data-import/data-import.html nested: @@ -1536,26 +1550,6 @@ entries: - title: Security guidelines url: /docs/dg/dev/guidelines/security-guidelines.html - - title: Best practices - url: /docs/dg/dev/best-practices/best-practices.html - nested: - - title: Non-funcational requirement templates - url: /docs/dg/dev/best-practices/non-functional-requirement-templates/non-functional-requirement-templates.html - nested: - - title: Operational and deployment guidelines - url: /docs/dg/dev/best-practices/non-functional-requirement-templates/operational-and-deployment-guidelines.html - - title: Monitorable process Guidelines - url: /docs/dg/dev/best-practices/non-functional-requirement-templates/monitorable-process-guidelines.html - - title: Operatable feature guidelines - url: /docs/dg/dev/best-practices/non-functional-requirement-templates/operatable-feature-guidelines.html - - title: Process documentation guidelines - url: /docs/dg/dev/best-practices/non-functional-requirement-templates/process-documentation-guidelines.html - - - title: Basic SEO techniques to use in your project - url: /docs/dg/dev/best-practices/basic-seo-techniques-to-use-in-your-project.html - - title: Coding best practices - url: /docs/dg/dev/best-practices/coding-best-practices.html - - title: Troubleshooting url: /docs/dg/dev/troubleshooting/troubleshooting.html nested: diff --git a/docs/dg/dev/architecture/non-functional-requirement-templates/monitorable-process-guidelines.md b/docs/dg/dev/architecture/non-functional-requirement-templates/monitorable-process-guidelines.md new file mode 100644 index 00000000000..00fde524110 --- /dev/null +++ b/docs/dg/dev/architecture/non-functional-requirement-templates/monitorable-process-guidelines.md @@ -0,0 +1,274 @@ +--- +title: Monitorable process guidelines +description: Guidelines for log generation and metric generation to enable Operations Teams to track and correlate issues in operated and deployed applications. +last_updated: Apr 21, 2026 +template: concept-topic-template +related: + - title: NFR guidelines + link: docs/dg/dev/architecture/non-functional-requirement-templates/operational-and-deployment-guidelines.html + - title: Operatable feature guidelines + link: docs/dg/dev/architecture/non-functional-requirement-templates/operatable-feature-guidelines.html + - title: Process documentation guidelines + link: docs/dg/dev/architecture/non-functional-requirement-templates/process-documentation-guidelines.html +redirect_from: + - /docs/dg/dev/best-practices/non-functional-requirement-templates/monitorable-process-guidelines.html +--- + +This document provides guideline templates for development teams striving for high-quality software. These templates are flexible and serve as a starting point, so make sure to adjust them to your project's requirements. Defining and following these guidelines may be necessary to fulfill project Service Level Agreements (SLAs), with each guideline explicitly outlining the responsible team. Alignment with all involved teams is essential for ensuring a functioning concept. + + +Enable your Operations Team to track and correlate issues within deployed applications by implementing the following practices: +- Ensure comprehensive logging mechanisms for capturing relevant events and errors. +- Implement metric generation techniques to gather key health indicators. + +These practices provide essential data for troubleshooting and monitoring application health. + +## Log generation + +Applies to all application components. + +### Log entry best practices + +- Unified format: The format and text taxonomy of log entries must be unified across all log providers for ease of human processing. +- No PII: Log entries, under no circumstances, can contain Personal Identifiable Information (PII) for security reasons. +- No encryption keys or secrets: Log entries must not contain any encryption keys or secrets. +- Single event reflection: To ensure determinability, each log entry must reflect a single event and the other way around. +- Language use: Log entries must use simple English language or widely recognized characters, especially when representing complex data. +- Meaningful messages: Log entry messages must be meaningful and provide context to the event. For example, avoid vague messages like "Error occurred". +- State preservation: When creating log entries, avoid passing arguments to log statements that could alter the state of an object. This is crucial for traceability and readability. +- Cross-component tracing ID: Include a cross component tracing ID in log entries to enable tracking of all generated logs across multiple components. +- Data residency compliance: Ensure that logs comply with data residency requirements. + +### What to log + +- Requests: Incoming requests to a local component. +- Remote calls: All outgoing requests to a remote service. Log the duration of the call and the response, such as success or error, for future debugging. +- Scheduled tasks: All initiated scheduled tasks with their end results: error, success, interrupt. +- Application scoped resource issues: + - Exhausted resources + - Exceeded capacities + - Session management failures + - Connectivity issues +- Threats: Suspicious or malicious activities against the application, as well as successes and failures in authentication or authorization. +- Exceptions: + - Handled and unhandled application errors + - Stack traces + - Troubleshooting instances + - Thrown exceptions +- Silenced exceptions: Instances of an exception being consumed by an empty `catch()` clause. +- Significant user actions and events: + - Help requests + - Cancelled actions +- Notable user actions: + - Successful logins + - Privilege elevations + - Data validation failures + - Payment and transaction events + - Significant user journey events + +### What not to log + +- Unreasonable logging: Avoid logging without a clear purpose. When deciding to create a log entry, identify at least one use case for the data. +- Performance critical places: Minimize logging in areas where performance is critical. If there's a performance-critical process or a large cycle as a sub-process element, try to strike a balance between performance and traceability. +- Audit trail: While it's recommended to log the audit trails of significant entity changes, these logs shouldn't be sent to the regular log system because of the sensitive nature of the data typically involved in authentication and authorization. + +### Log levels + +Appropriately implement the following log levels in application workflows to simplify issue investigations and resolutions. The log levels are based on Syslog [RFC 5424](https://datatracker.ietf.org/doc/html/rfc5424). + +| Level | Description | +|-------|-------------| +| Debug | Provides detailed data that's mostly used for debugging. These logs allow to check variable values and/or error stacks. | +| Info | Provides information about the normal operation of the application. This level is often used to record the progress of a task or operation. | +| Notice | Provides information about normal, but significant, events that occur within the application. | +| Warning | Describes events that are less destructive than errors. They usually don't result in any reduction of the system's functionality or its full failure. Undesirable things that are not necessarily wrong. | +| Error | Identifies error events that may still let the software run but with restricted capabilities in the impacted routes. | +| Critical | Identifies extremely serious error events that are likely to cause the system to abort. Typically, this leads to catastrophic failures. | +| Alert | Indicates a situation that requires immediate attention. | +| Emergency | Indicates a severe problem that requires immediate action to prevent damage or loss. | + +### Log entry format + +A log entry must always answer the following items and follow the describes structure: +- *who* caused an event. +- *when* exactly did the event happen. +- *where* did the event take place, for example-context, component or application. +- *what* happened and/or why it happened. +- *result* of event: exception, success details, information details. + +The following are examples of log structure. When designing your own log structure, take into account recommendations from [CloudWatch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-metric-streams-formats-json.html) and [Cloud Handler](https://github.com/maxbanton/cwh). + +
+ Log structure example + +```JSON +{ + "actor": { + "actorId": "end-user-1", + "sessionId": "end-user-1-session-27", + "transactionId": "end-to-end-transaction-555", + "parentTransactionId": "end-to-end-transaction-554", + }, + "service": { + "host": "ip-11-111-1-111.eu-central-1.compute.internal", + "componentType": "GLUE", + "component": "StorefrontApi", + "activityId": "address-search-suggestions", + }, + "@timestamp": "2022-08-01T18:20:22.602934+00:00", + "message":"StorefrontAPI : GET : v2/stores/delivery : start", + "messageId":"unique-message-id", + "level": 0, + "levelCode": 0, + "extra" : { + "exception": {...} + "environment": { + "application": "", + "environment": "", + "store": "", + "codeBucket": "", + "locale": "" + }, + "server": { + "url": "", + "isHttps": true, + "hostname": "", + "requestMethod": "", + "referer": null + }, + "request": { + "requestId": "", + "type": "", + "requestParams": {} + }, + "externalRequest" : { + "externalDuration":"0", + "externalResponseCode": "remote-service-unique-answer-code" + }, +} +``` + +
+ +
+ Log structure with example values + +```JSON +{ + "@timestamp": "2022-08-01T18:20:22.602934+00:00", + "@version": 1, + "host": "ip-10-105-6-175.eu-central-1.compute.internal", + "message": "StorefrontAPI : Request : v2/stores/delivery", + "type": "GLUE", + "channel": "Glue", + "level": "INFO", + "monolog_level": 200, + "extra": { + "environment": { + "application": "GLUE", + "environment": "docker.dev", + "store": null, + "codeBucket": "US", + "locale": "en_US" + }, + "server": { + "url": "https://api.com/v1/action-name?param1=abc", + "is_https": true, + "hostname": "api.com", + "user_agent": "cypress/test-automation", + "user_ip": "35.205.30.220", + "request_method": "GET", + "referer": null + }, + "request": { + "requestId": "3c1f60f1", + "type": "WEB", + "request_params": { + "currency": "USD", + "service_type": "delivery", + "zip_code": "32773-5600", + "address": "3707 S Orlando Dr" + } + } + }, + "context": { + "payload": { + "find_by": [] + } + } +} +``` + +
+ + +
+ Log structure with example error values + +```JSON +{ + "@timestamp": "2021-08-19T14:54:23.447685+00:00", + "@version": 1, + "host": "localhost", + "message": "Exception - Sniffer run was not successful: Unknown error in \"/.../vendor/spryker/development/src/Spryker/Zed/Development/Business/ArchitectureSniffer/ArchitectureSniffer.php::165\"", + "type": "ZED", + "channel": "Zed", + "level": "CRITICAL", + "monolog_level": 500, + "extra": { + "environment": { + "application": "ZED", + "environment": "development", + "store": "US", + "codeBucket": "US", + "locale": "en_US" + }, + "server": { + "url": "http://:/", + "is_https": false, + "hostname": "", + "user_agent": null, + "user_ip": null, + "request_method": "cli", + "referer": null + }, + "request": { + "requestId": "ad26d9e1", + "type": "CLI", + "request_params": [] + } + }, + "context": { + "exception": { + "class": "Exception", + "message": "Sniffer run was not successful: Unknown error", + "code": 0, + "file": "/.../vendor/spryker/development/src/Spryker/Zed/Development/Business/ArchitectureSniffer/ArchitectureSniffer.php:165", + "trace": [ + "/.../vendor/spryker/development/src/Spryker/Zed/Development/Business/ArchitectureSniffer/ArchitectureSniffer.php:117", + "/.../vendor/spryker/development/src/Spryker/Zed/Development/Business/DevelopmentFacade.php:484", + "/.../vendor/spryker/development/src/Spryker/Zed/Development/Communication/Console/CodeArchitectureSnifferConsole.php:286", + "/.../vendor/spryker/development/src/Spryker/Zed/Development/Communication/Console/CodeArchitectureSnifferConsole.php:93", + "/.../vendor/symfony/console/Command/Command.php:258", + "/.../vendor/symfony/console/Application.php:938", + "/.../vendor/symfony/console/Application.php:266", + "/.../vendor/spryker/console/src/Spryker/Zed/Console/Communication/Bootstrap/ConsoleBootstrap.php:111", + "/.../vendor/symfony/console/Application.php:142", + "/.../vendor/spryker/console/bin/console:27" + ] + } + } +} +``` + +
+ +## Metric generation + +Each metric represents a condition of system attributes. There can be many of them, and they can be correlated with each other. + +- Every service or component can define and generate project-appropriate metrics for key processes to enable tracking of such events and reacting when they reach undesired scores. These metrics are generated with a basic dimension of the duration and outcome of the operation, such as success or failure. + - The start and end of a process must be recorded to enable tracking and tuning of the infrastructure. + - Instances of communication duration with remote services must be recorded to understand if a local process is delayed for a good reason. +- Critical metrics, along with their threshold values, must be highlighted in the [Operational guidelines](/docs/dg/dev/architecture/non-functional-requirement-templates/process-documentation-guidelines.html#operational-guidelines) to enable the setting up of a monitoring system. +- Deployment and rollback flows can generate metrics to enable tracking and interaction with these processes. diff --git a/docs/dg/dev/architecture/non-functional-requirement-templates/non-functional-requirement-templates.md b/docs/dg/dev/architecture/non-functional-requirement-templates/non-functional-requirement-templates.md new file mode 100644 index 00000000000..5d9b1a97a92 --- /dev/null +++ b/docs/dg/dev/architecture/non-functional-requirement-templates/non-functional-requirement-templates.md @@ -0,0 +1,17 @@ +--- +title: Non-functional requirement templates +description: Define key system expectations using Spryker's non-functional requirement templates. Focus on performance, scalability, and security to align development goals effectively. +template: concept-topic-template +redirect_from: + - /docs/dg/dev/best-practices/non-functional-requirement-templates/non-functional-requirement-templates.html +--- + +This section contains the templates for non-functional project requirements. The templates serve as a starting point for creating non-functional requirements for your project, so make sure to adjust them to your project's needs. Defining and following these guidelines may be necessary to fulfill project Service Level Agreements, with each guideline explicitly outlining the responsible team. Alignment with all involved teams is essential for ensuring a functioning concept. + +- [Operational and deployment guidelines](/docs/dg/dev/architecture/non-functional-requirement-templates/operational-and-deployment-guidelines.html) for ensuring a good collaboration between application development and operation. + +- [Monitorable process guidelines](/docs/dg/dev/architecture/non-functional-requirement-templates/monitorable-process-guidelines.html) for preparing an easy to monitor application. + +- [Operatable feature guidelines](/docs/dg/dev/architecture/non-functional-requirement-templates/operatable-feature-guidelines.html) for delivering easy to operate features. + +- [Process documentation guidelines](/docs/dg/dev/architecture/non-functional-requirement-templates/process-documentation-guidelines.html) for preparing high-quality documentation for easy operation. diff --git a/docs/dg/dev/best-practices/non-functional-requirement-templates/monitorable-process-guidelines.md b/docs/dg/dev/architecture/non-functional-requirement-templates/non-functional-requirement-templates/monitorable-process-guidelines.md similarity index 99% rename from docs/dg/dev/best-practices/non-functional-requirement-templates/monitorable-process-guidelines.md rename to docs/dg/dev/architecture/non-functional-requirement-templates/non-functional-requirement-templates/monitorable-process-guidelines.md index 4a841ba64b0..afc222c659a 100644 --- a/docs/dg/dev/best-practices/non-functional-requirement-templates/monitorable-process-guidelines.md +++ b/docs/dg/dev/architecture/non-functional-requirement-templates/non-functional-requirement-templates/monitorable-process-guidelines.md @@ -1,7 +1,7 @@ --- title: Monitorable process guidelines description: Guidelines for log generation and metric generation to enable Operations Teams to track and correlate issues in operated and deployed applications. -last_updated: April 23, 2024 +last_updated: Apr 21, 2026 template: concept-topic-template related: - title: NFR guidelines diff --git a/docs/dg/dev/best-practices/non-functional-requirement-templates/non-functional-requirement-templates.md b/docs/dg/dev/architecture/non-functional-requirement-templates/non-functional-requirement-templates/non-functional-requirement-templates.md similarity index 100% rename from docs/dg/dev/best-practices/non-functional-requirement-templates/non-functional-requirement-templates.md rename to docs/dg/dev/architecture/non-functional-requirement-templates/non-functional-requirement-templates/non-functional-requirement-templates.md diff --git a/docs/dg/dev/best-practices/non-functional-requirement-templates/operatable-feature-guidelines.md b/docs/dg/dev/architecture/non-functional-requirement-templates/non-functional-requirement-templates/operatable-feature-guidelines.md similarity index 99% rename from docs/dg/dev/best-practices/non-functional-requirement-templates/operatable-feature-guidelines.md rename to docs/dg/dev/architecture/non-functional-requirement-templates/non-functional-requirement-templates/operatable-feature-guidelines.md index 29c3627bba3..9fd34b7092a 100644 --- a/docs/dg/dev/best-practices/non-functional-requirement-templates/operatable-feature-guidelines.md +++ b/docs/dg/dev/architecture/non-functional-requirement-templates/non-functional-requirement-templates/operatable-feature-guidelines.md @@ -1,7 +1,7 @@ --- title: Operatable feature guidelines description: Learn Spryker's operatable feature guidelines to ensure features are scalable, reliable, and manageable. Optimize performance while maintaining operational efficiency. -last_updated: April 23, 2024 +last_updated: Apr 21, 2026 template: concept-topic-template related: - title: NFR guidelines diff --git a/docs/dg/dev/best-practices/non-functional-requirement-templates/operational-and-deployment-guidelines.md b/docs/dg/dev/architecture/non-functional-requirement-templates/non-functional-requirement-templates/operational-and-deployment-guidelines.md similarity index 99% rename from docs/dg/dev/best-practices/non-functional-requirement-templates/operational-and-deployment-guidelines.md rename to docs/dg/dev/architecture/non-functional-requirement-templates/non-functional-requirement-templates/operational-and-deployment-guidelines.md index 32029452ca8..2fb6080e906 100644 --- a/docs/dg/dev/best-practices/non-functional-requirement-templates/operational-and-deployment-guidelines.md +++ b/docs/dg/dev/architecture/non-functional-requirement-templates/non-functional-requirement-templates/operational-and-deployment-guidelines.md @@ -1,7 +1,7 @@ --- title: Operational and deployment guidelines description: Guidelines for defining and implementing Operational and Deployment Non-Functional Requirements (NFRs) to ensure the technical success of a project. -last_updated: April 23, 2024 +last_updated: Apr 21, 2026 template: concept-topic-template related: - title: Operatable feature guidelines diff --git a/docs/dg/dev/best-practices/non-functional-requirement-templates/process-documentation-guidelines.md b/docs/dg/dev/architecture/non-functional-requirement-templates/non-functional-requirement-templates/process-documentation-guidelines.md similarity index 99% rename from docs/dg/dev/best-practices/non-functional-requirement-templates/process-documentation-guidelines.md rename to docs/dg/dev/architecture/non-functional-requirement-templates/non-functional-requirement-templates/process-documentation-guidelines.md index 8a695c078a0..d83b8fd3136 100644 --- a/docs/dg/dev/best-practices/non-functional-requirement-templates/process-documentation-guidelines.md +++ b/docs/dg/dev/architecture/non-functional-requirement-templates/non-functional-requirement-templates/process-documentation-guidelines.md @@ -1,7 +1,7 @@ --- title: Process documentation guidelines description: Process documentation guidelines to improve communication and ensure smooth deployment of applications within cross-functional teams. -last_updated: April 23, 2024 +last_updated: Apr 21, 2026 template: concept-topic-template related: - title: NFR guidelines diff --git a/docs/dg/dev/architecture/non-functional-requirement-templates/operatable-feature-guidelines.md b/docs/dg/dev/architecture/non-functional-requirement-templates/operatable-feature-guidelines.md new file mode 100644 index 00000000000..5c6f3ce9c53 --- /dev/null +++ b/docs/dg/dev/architecture/non-functional-requirement-templates/operatable-feature-guidelines.md @@ -0,0 +1,59 @@ +--- +title: Operatable feature guidelines +description: Learn Spryker's operatable feature guidelines to ensure features are scalable, reliable, and manageable. Optimize performance while maintaining operational efficiency. +last_updated: Apr 21, 2026 +template: concept-topic-template +related: + - title: NFR guidelines + link: docs/dg/dev/architecture/non-functional-requirement-templates/operational-and-deployment-guidelines.html + - title: Process documentation guidelines + link: docs/dg/dev/architecture/non-functional-requirement-templates/process-documentation-guidelines.html + - title: Monitorable process guidelines + link: docs/dg/dev/architecture/non-functional-requirement-templates/monitorable-process-guidelines.html +redirect_from: + - /docs/dg/dev/best-practices/non-functional-requirement-templates/operatable-feature-guidelines.html +--- + + +This document provides guideline templates for development teams striving for high-quality software. These templates are flexible and serve as a starting point, so make sure to adjust them to your project's requirements. Defining and following these guidelines may be necessary to fulfill project Service Level Agreements (SLAs), with each guideline explicitly outlining the responsible team. Alignment with all involved teams is essential for ensuring a functioning concept. + +By addressing the following items, a development team can ensure that the operations team has the necessary information and resources to maintain the reliability of applications. + +## Survivability + +An application, during its life cycle, faces various expected and unexpected challenges. To enable the operations team to increase an application's survivability, it's recommended to design additional flexible configuration options, like feature or workflow disabling or switching, that can be adjusted on the fly without redeployment to decrease resolution impact on critical business flows. Such options need to be handed over in the operational guidelines. + +## Stability + +It is very common for business or technical teams to identify project-specific risks that may temporarily challenge the stability of the application. + +To enable the operations team to effectively address such events or explore alternative solutions, it's recommended that any gathered information related to these specific cases are shared via the Operational guidelines. This ensures that the operations team has the necessary information to address stability issues and maintain the reliability of the application. + +## Readability + +Code readability is a major quality attribute that can impact various aspects of a project, such as the following: +- Code review time +- Code fix time +- Feature delivery time +- Developer onboarding time +- Error evaluation time +- The number of human errors + +To improve the efficiency and effectiveness of the team, it's important to establish a set of readability rules that need to be followed. This ensures that the codebase is easy to understand and maintain, which can lead to faster delivery of features and fewer errors. + +## Credibility + +To ensure a credible application that can operate continuously, that is 24/7/365, and implement significant changes on a regular basis, it's recommended to develop and adhere to testing best practices that aim for error-free behavior in the production environment. As an optional step, a set of production-targeted smoke tests, considering their impact on the production environment, can be conducted to verify the proper behavior of recent changes to the system. These tests can be included as part of the operational or deployment guidelines. + +{% info_block infoBox %} +It's recommended to put extra attention over the environment specific application and infrastructure configuration and settings because they carry a higher risk of business impact on error. +{% endinfo_block %} + + +## Fault-tolerance + +We recommend preparing a fallback mechanism for your business critical workflows, like order placement, to make sure that the intentions of your end users are never lost. + +## Interruptibility + +Scheduled tasks need to be interruptible because they're more prune to face critical failures and deliberate interruptions if they are always running. Accordingly, they need to leave the processed entities and their related modified entities in a consistent state and not loose any critical business information in between. Special, not-recurring, long-running scheduled tasks need to be marked to be distinguishable from regular scheduled tasks for easy observation and management. diff --git a/docs/dg/dev/architecture/non-functional-requirement-templates/operational-and-deployment-guidelines.md b/docs/dg/dev/architecture/non-functional-requirement-templates/operational-and-deployment-guidelines.md new file mode 100644 index 00000000000..516d0413d79 --- /dev/null +++ b/docs/dg/dev/architecture/non-functional-requirement-templates/operational-and-deployment-guidelines.md @@ -0,0 +1,74 @@ +--- +title: Operational and deployment guidelines +description: Guidelines for defining and implementing Operational and Deployment Non-Functional Requirements (NFRs) to ensure the technical success of a project. +last_updated: Apr 21, 2026 +template: concept-topic-template +related: +- title: Operatable feature guidelines + link: docs/dg/dev/architecture/non-functional-requirement-templates/operatable-feature-guidelines.html +- title: Process documentation guidelines + link: docs/dg/dev/architecture/non-functional-requirement-templates/process-documentation-guidelines.html +- title: Monitorable process guidelines + link: docs/dg/dev/architecture/non-functional-requirement-templates/monitorable-process-guidelines.html +- title: Architecture performance guidelines + link: docs/dg/dev/guidelines/performance-guidelines/architecture-performance-guidelines.html +redirect_from: + - /docs/dg/dev/best-practices/non-functional-requirement-templates/operational-and-deployment-guidelines.html +--- + +This document provides guideline templates for development teams striving for high-quality software. These templates are flexible and serve as a starting point, so make sure to adjust them to your project's requirements. Defining and following these guidelines may be necessary to fulfill project Service Level Agreements (SLAs), with each guideline explicitly outlining the responsible team. Alignment with all involved teams is essential for ensuring a functioning concept. + +The following are generic NFRs grouped by quality, acting as a starting point for your project. Be sure to tailor the list to the specific requirements and constraints of your project, and to prioritize and organize the NFRs in a logical manner. + + +## Non-functional requirements + +Non-functional requirements (NFRs) are one of the core tools for architects and developers to describe how the system under development is supposed to work from a technical perspective. Defining NFRs can be as important as defining functional requirements, which are usually done by business, for example—Product Owners. Developing a project without NFRs usually results in +unintended behaviors being discovered late in the product's lifecycle, which costs a lot of resources to deal with. + +Involving all the relevant stakeholders into creating NFRs ensures there is a common understanding of how the system is supposed to work and its key characteristics. The list of stakeholders can include architects, developers, business analysts, and end users. + +Using a structured approach to creating NFRs ensures that all relevant NFRs are identified, and that they are prioritized and organized in a logical manner. This can involve using a specific framework or methodology, such as the [ISO 25010 standard](https://iso25000.com/index.php/en/iso-25000-standards/iso-25010), or the Quality Attribute Workshop method, or even [PASSME](https://nick-goupinets.medium.com/passme-muster-846a9997645b). + +As the system is being developed, the NFRs may also need to be adjusted to reflect changes in the project's goals and objectives. Regularly revisiting and updating NFRs ensures that the system continues to meet the technical and functional needs of the business and end users. + +## Availability guidelines + +Software architecture and design must ensure that there is no negative impact on application availability by following the guidelines: + +- Avoid designing the application to limit its own startup and shutdown: + - Avoid design patterns or coding practices that cause the application to exit unexpectedly in the middle of execution. + - Avoid using flags or other mechanisms to block the application from starting. + - Avoid setting limits on the number of concurrent processes that can be run by the application. +- Avoid designing the application to lock shared resources at the application level. For example, if the application uses a database, it shouldn't lock the database tables or rows that it reads or writes to. This can cause other parts of the system to become unavailable. +- Align resource consumption with expected workloads. For example, if using PHP-FPM, make sure the number of worker processes is sufficient to handle the expected workload without overloading the system. + +## Security guidelines + +Make sure to define and follow your own project's [security best practices](/docs/dg/dev/guidelines/security-guidelines.html). + +## Deployability guidelines + +- The same release candidate and branch must be redeployable without side effects. +- Deploy scripts must not break the behavior of the current system. + - Deploy script elements must be configured according to your project setup following the [deployment pipeline](/docs/cloud/dev/spryker-cloud-commerce-os/configure-deployment-pipelines/deployment-pipelines.html) process. + - The application to be deployed (version N+1) must upgrade the data structures and constants and data sets without causing downtime and without failing, losing, or compromising any (version N+1 or N) functionality. + - The message consumers to be deployed (version N+1) must be backward compatible with the present ( +This request is for the deployment of version 1.2.3 of the MyProject application to the production environment. + +**Requested Changes**: + +- Deployment of version 1.2.3 of the MyProject application +- Update of the following environment variables: + - Expected environment variable name: `DATABASE_URL`
+ Expected value: `postgresql://user:password@localhost:5432/mydatabase` + - Expected environment variable name: `API_KEY`
+ Expected value: `abcd1234` + - Expected environment variable name: `DEBUG`
+ Expected value: `false` +- Special manual steps: + - **Step 1**: Run the database migration script before starting the application. + - **Step 2**: Update the DNS records for the new application version. +- Infrastructure changes: + - Add an additional application server to the load balancer pool. + - Increase the size of the database server's disk. +*Expected behavior: + - There may be a temporary increase in error log entries because of a known issue with the new version that will be fixed in the next release. + +**Impact**:
+This deployment will include updates to the application's database connection and API key, as well as changes to the infrastructure. There is a low risk of downtime during the deployment. + +**Rollback Plan**:
+In the event of an issue during the deployment, we will roll back to the previous version of the application and revert any infrastructure changes. + +**Testing**:
+This release has been thoroughly tested in the staging environment. A final validation on the production environment to verify that the expected setup changes match the actual state will be performed before the deployment. + +**Approvals**: +- Lead developer: approved +- QA team: approved +- Operations team: approved + +## Operational guidelines + +The following guidelines apply to operating applications or for special failure scenarios that may as well occur during deployment or rollback. + +Given the size and complexity of a large applications, which delivers many features with each release, unexpected errors can have multiple potential resolutions. To ensure that the most effective resolution is chosen with minimal disruption to the functionality of a successfully deployed release, implement the following operation guidelines. + +### Main workflows + +To understand the main and critical workflows in the application, operational guidelines should outline the normal behavior of +important features and workflows at the logical, component, and infrastructure levels. + +This forms a general overview of the logic, components, and infrastructure. This overview is necessary for making informed operational decisions and building project-specific operational dashboards, for example—to to identify and highlight project-specific bottlenecks. Also, it's needed for analyzing, answering, and resolving requests. + +### Risks, early warnings, and counter actions + +Building a large application is usually coupled with massive application-level logging. In some cases, a critical system issue can be prevented or minimized with timely warning signals. By using regular signals, like logs and metrics, from identified business or technical bottlenecks or risks, the operations team can improve the application's stability. We recommend maintaining a list of such signals and risks in the operational guidelines. This includes recommended actions to take in order to deliver the best mitigation strategy. For more information on these guidelines, see [Operatable feature guidelines](/docs/dg/dev/architecture/non-functional-requirement-templates/operatable-feature-guidelines.html). + +### Silent undesired scenario + +Although monitoring systems are used to detect unwanted states, some business functionality may be within acceptable metrics but not desirable under certain conditions. For example, the minimum daily browsing customer count is 10, but 11 customers during Black Friday is not considered normal. To monitor such cases, these scenarios need to be documented for the operations team. + +### User guide + +To minimize the impact of resolution efforts and optimize the process, make sure to provide the operations team with the necessary business context. For example, resolving a small number of errors through the Back Office may be more optimal than rolling back an entire release. + +### Entity size expectations + +The number of entities plays an important role in determining how an application will function in a production environment. To mitigate risks in this area, performance, scaling, manual tests, and reviews can be applied. However, the identified and estimated number of entities for the project can serve as a warning to pay extra attention to these entities in order to further reduce risks. For example, a marketing campaign bringing 10,000 active users to the homepage at 17:08 on Friday. + + +### Remote service catalog + +To properly handle and monitor the cooperation between local and remote or third-party services, provide the operations team with a detailed communication protocol. Make sure to additionally include the expected outages and major impacts. This way, the operations team can ignore expected outages and actively focus on known risks. + +For example, a payment provider connected to the project needs to be monitored to ensure its availability. The following communication protocol is used: + +- The local service sends an HTTP GET request to the remote service's API endpoint, along with any necessary headers and query parameters. +- The remote service responds with an HTTP status code and a JSON payload containing the requested data. +- The local service processes the data and displays it to the user or performs any necessary actions. diff --git a/docs/dg/dev/best-practices/best-practices.md b/docs/dg/dev/best-practices/best-practices.md deleted file mode 100644 index a7916f9f4fa..00000000000 --- a/docs/dg/dev/best-practices/best-practices.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: Best practices -description: Discover best practices for Spryker development, including coding standards, modular architecture, testing strategies, and optimization techniques. -template: concept-topic-template -redirect_from: - - /docs/scos/dev/best-practices/ - - /docs/scos/dev/best-practices/best-practices.html ---- - -This section contains the following best practices guidelines and recommendations for developing on Spryker Commerce OS: - -- [Basic SEO techniques to use in your project](/docs/dg/dev/best-practices/basic-seo-techniques-to-use-in-your-project.html) to optimize your search functionality. - -- [Coding best practices](/docs/dg/dev/best-practices/coding-best-practices.html) describes a few common PHP coding problems and recommended solutions. diff --git a/docs/dg/dev/best-practices/coding-best-practices.md b/docs/dg/dev/best-practices/coding-best-practices.md deleted file mode 100644 index 30263d96c10..00000000000 --- a/docs/dg/dev/best-practices/coding-best-practices.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Coding Best Practices -description: In this article we outline a few common PHP coding problems and the recommended solutions. -last_updated: Jun 16, 2021 -template: concept-topic-template -originalLink: https://documentation.spryker.com/2021080/docs/coding-best-practices -originalArticleId: 5df9f9bf-c445-4d56-af59-a95757696009 -redirect_from: - - /docs/scos/dev/best-practices/coding-best-practices.html ---- - -This document outlines a few common PHP coding problems and the recommended solutions. - -## Merging arrays - -When merging arrays, one usually uses `array_merge($defaults, $options)`. However, when working with associative arrays (keys are all string identifiers), it's recommended to use the `+` operator. This is not only a lot faster, it also yields more correct results with edge cases. Beware of the switched order in this case: `$mergedOptions = $options + $defaults;` - -## Operations per line - -To facilitate readability and debugging, it's recommended to use only one operation per line. - -## Method size - -Long methods tend to have too many responsibilities, and are usually harder to understand and maintain than smaller ones. Therefore it's advisable to stick to the "single responsibility" principle, when a method is just a few lines long. diff --git a/docs/dg/dev/best-practices/basic-seo-techniques-to-use-in-your-project.md b/docs/dg/dev/frontend-development/latest/yves/basic-seo-techniques-to-use-in-your-project.md similarity index 98% rename from docs/dg/dev/best-practices/basic-seo-techniques-to-use-in-your-project.md rename to docs/dg/dev/frontend-development/latest/yves/basic-seo-techniques-to-use-in-your-project.md index 62cba650245..2292e9d8b36 100644 --- a/docs/dg/dev/best-practices/basic-seo-techniques-to-use-in-your-project.md +++ b/docs/dg/dev/frontend-development/latest/yves/basic-seo-techniques-to-use-in-your-project.md @@ -1,12 +1,13 @@ --- title: Basic SEO techniques to use in your project description: Learn how you can effectively use headings and mircodata to improve SEO for your project -last_updated: Jun 16, 2021 +last_updated: Apr 21, 2026 template: concept-topic-template originalLink: https://documentation.spryker.com/2021080/docs/basic-seo-techniques-to-use-in-your-project originalArticleId: 56e34beb-79e3-44b0-a7b9-06489c78e9ac redirect_from: - /docs/scos/dev/best-practices/basic-seo-techniques-to-use-in-your-project.html + - /docs/dg/dev/best-practices/basic-seo-techniques-to-use-in-your-project.html --- Search Engine Optimization or SEO is the process of improving a site to increase its visibility for relevant searches. The better visibility a page has in search results, the more likely you are to garner attention and attract prospective and existing customers to your business. diff --git a/docs/dg/dev/guidelines/coding-guidelines/coding-guidelines.md b/docs/dg/dev/guidelines/coding-guidelines/coding-guidelines.md index fa2c1b49c6d..1c9c4f57a6c 100644 --- a/docs/dg/dev/guidelines/coding-guidelines/coding-guidelines.md +++ b/docs/dg/dev/guidelines/coding-guidelines/coding-guidelines.md @@ -1,10 +1,11 @@ --- title: Coding guidelines description: This document lists everything you need to know about coding guidelines that are used at Spryker for your Spryker based projects. -last_updated: Jan 27, 2022 +last_updated: Apr 21, 2026 template: concept-topic-template redirect_from: - /docs/scos/dev/guidelines/coding-guidelines/coding-guidelines.html + - /docs/scos/dev/best-practices/coding-best-practices.html --- In this section, you can learn about coding guidelines that we use at Spryker. For more details, see the following documents: diff --git a/docs/dg/dev/guidelines/guidelines.md b/docs/dg/dev/guidelines/guidelines.md index 28b03232ae0..9d9a1426386 100644 --- a/docs/dg/dev/guidelines/guidelines.md +++ b/docs/dg/dev/guidelines/guidelines.md @@ -1,9 +1,12 @@ --- title: Guidelines description: A set of guidelines for developers to use whilst working on Spryker Cloud Commerce OS projects. +last_updated: Apr 21, 2026 template: concept-topic-template redirect_from: - /docs/scos/dev/guidelines/guidelines.html + - /docs/scos/dev/best-practices/ + - /docs/scos/dev/best-practices/best-practices.html --- This section contains a collection of useful guidelines for developing on the Spryker Commerce OS: