{"id":19029903,"url":"https://github.com/guardian/recommendations","last_synced_at":"2025-10-04T13:05:58.919Z","repository":{"id":22182946,"uuid":"25514942","full_name":"guardian/recommendations","owner":"guardian","description":"Recommendations for how to develop software at the Guardian","archived":false,"fork":false,"pushed_at":"2025-07-07T11:20:42.000Z","size":5258,"stargazers_count":72,"open_issues_count":10,"forks_count":5,"subscribers_count":56,"default_branch":"main","last_synced_at":"2025-07-18T20:16:59.170Z","etag":null,"topics":["documentation"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"reenigne/reenigne","license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/guardian.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"security.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2014-10-21T09:53:13.000Z","updated_at":"2025-06-18T15:07:59.000Z","dependencies_parsed_at":"2023-02-19T18:01:34.744Z","dependency_job_id":"23e0ccb5-ad59-4ad0-b918-f2fc9c3a68d2","html_url":"https://github.com/guardian/recommendations","commit_stats":{"total_commits":313,"total_committers":51,"mean_commits":6.137254901960785,"dds":0.9169329073482428,"last_synced_commit":"bcb8a97a70c5604da558cc5c4b1e3cb48f4ebe9e"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/guardian/recommendations","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guardian%2Frecommendations","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guardian%2Frecommendations/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guardian%2Frecommendations/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guardian%2Frecommendations/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/guardian","download_url":"https://codeload.github.com/guardian/recommendations/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guardian%2Frecommendations/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266596951,"owners_count":23953894,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-22T02:00:09.085Z","response_time":66,"last_error":null,"robots_txt_status":null,"robots_txt_updated_at":null,"robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["documentation"],"created_at":"2024-11-08T21:15:45.698Z","updated_at":"2025-10-04T13:05:53.889Z","avatar_url":"https://github.com/guardian.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# The Guardian software engineering recommendations\n\nThis repository document [principles](#principles), standards and [guidelines](#guidelines).\n\n## Principles\n\n## Security principles\n\n- Service should follow the [principle of least privilege](https://en.wikipedia.org/wiki/Principle_of_least_privilege) regarding user access and consider the sensitivity of any data or operations the service makes available. For example a service which provides `read-only` data on what's for lunch in the canteen may be accessed by all Guardian staff, but a service that publishes content to our site must be tightly controlled to a known set of users.\n\n- Service should follow a **zero-trust approach**. Service should not rely on the network level (`3`) only to grant privilege or make assumption but rather ensure each request is authenticated at application level (`7`), and may use multiple parameters (location, time, user, authentication method, behaviours) to grant or deny access. \n\n- Service should employ multiple techniques and have defense in depth: typesafe language, virtual machine, operating system hardening, code reviews, integration tests, safe libraries, code static analysis, vulnerabilities scanning, user input sanitising, browsers built-in restrictions, encryption, audits and pentesting.\n\n- All services should be registered in a service catalog with defined technical owners, state of the service and links to related artefacts.\n\n- All services in `production` should be maintained and kept up to date to latest version in alignment with vulnerabilities management standards and with the aim to **reduce exposure windows to a minimum**.\n\n- Technical debt should be actively managed and reduce in line with risk and business strategy.\n\n## Reliability principles\n\n- Publish services **availability SLA** to **communicate expectations** to users or dependent systems and identify area of improvements.\n\n\u003c!-- alex ignore simple --\u003e\n- Design for **simplicity** and **single responsibility**. Great designs model complex problems as simple discrete components. Monitoring, self-healing and graceful degradation are simpler when responsibilities are not conflated.\n\n- **Design for failures**. All things break, so the behaviour of a system when any of its components, collaborators or hosting infrastructure fail or respond slowly must be a key part of its design.\n\n- Ensure applications are **swim-laned** to enable **graceful degradation** and **prevent cascading failure**. Communication via **idempotent events** should be preferred **over remote procedure calls (RPC)** as they allow us to replay events in case of failure. When sending event use **at-least-once semantic** to ensure a message will always be sent even in case of a failure.\n\n- **Software and infrastructure are not separated concerns**. The simplest and most reliable solutions often require changes to both, so a team must be responsible for both and they should be designed together.\n\n- Leverage the vendors's recovery and resilience features in the underlying platforms in preference to implementing custom processes. Vendors SLAs usually provide **higher levels of availability** than could be achieved using our own processes: \n    - For example, prefer using `RDS` rather than hosting databases on our own `AWS` instances. With `RDS`, `AWS` manages patching, backups and replication of data to a standby instance in a different [Availability Zone (AZ)](https://aws.amazon.com/about-aws/global-infrastructure/regions_az/), providing resilience to data centre outages.\n\n    - For example, we use use `BigQuery` which [SLA](https://cloud.google.com/bigquery/sla) details a monthly uptime percentage superior to 99.99%. \n\n- Out of hours support. Team are responsible for their services but there is additional 24/7 compensated support to deal with unexpected issues.\n\n## Scalability principles\n\n- **Design for horizontal scaling** a system that can be scaled by adding additional servers provides simpler scalability and greater robustness.\n\n- **Scaling state is complex** avoid state where possible and where it is unavoidable, have a clear plan for how it can scale including CAP considerations, or why scaling is unnecessary.\n\n- Service should provide coherent features set with explicit documentation including SLA for use by other services.\n\n## Operational principles\n\n- All services should be using for defined common standards for infrastructure management, deployment, configuration management, logging, and observability.\n\n- Workflow and processes should be **automated** to enable users to **self-serve** based on their needs without unneeded time consuming interactions.\n\n- Deployment of changes, including infrastructure, should be automated, **repeatable**, **auditable** and **continuous**. \n\n- All services should be monitored to alert on business or technical issue and reduce time to restore service.\n\n- Reducing *time to detect and restore* service (availability to users) should be optimised rather than number of failures (reliability of services). \n\n## Data principles\n\n- Service should be designed with [data minimisation](https://ico.org.uk/for-organisations/guide-to-data-protection/guide-to-the-general-data-protection-regulation-gdpr/principles/data-minimisation/) and [data protection by design and default](https://ico.org.uk/for-organisations/guide-to-data-protection/guide-to-the-general-data-protection-regulation-gdpr/accountability-and-governance/data-protection-by-design-and-default) principles.\n\n\n- Data is classified and protected according to [classification](https://docs.google.com/document/d/1wXsshs7GKzVdQhO57-QR6RZDFV2ZySPeHjqTvxfceZk/edit) and associated standard regarding access, storage and protections. \n\n- Service should implement data retention policy in accordance with data governance standards.\n\n- Service should ensure compliance with `GDPR`, `PECR`, `CCPA`, and others data privacy regulations when creating or maintaining service through following defined processes (e.g Data Council), by using existing libraries and by integrating with existing capabilities for data ingestion (`Fivetrans`), transformation (`DBT`), storage (`BigQuery`) and orchestration of end users privacy requests ([`Baton`](https://github.com/guardian/baton)).   \n\n\n## Guidelines\n\n-   [Accessibility](accessibility.md)\n-   [Applications](applications.md)\n-   [AWS](AWS.md)\n-   [AWS Costs](AWS-costs.md)\n-   [Client Side](client-side.md)\n-   [Coding with empathy](coding-with-empathy.md)\n-   [Config](config.md)\n-   [Content Delivery Network (CDN)](cdn.md)\n-   [Continuous Deployment](continuous-deployment.md)\n-   [Continuous Integration](continuous-integration.md)\n-   [Domain Names](domain-names.md)\n-   [Elasticsearch](elasticsearch.md)\n-   [Emotion](emotion.md)\n-   [GitHub](github.md)\n-   [Github Actions](github-actions.md)\n-   [Logging](logging.md)\n- Publishing software libraries\n  - [NPM packages](npm-packages.md)\n  - [Maven Central for Scala, Kotlin \u0026 other JVM-based languages](publishing-libraries-to-maven-central.md)\n-   [Production Services, Ownership and Maintenance](ownership.md)\n-   [Pull requests](pull-requests.md)\n-   [Resiliency and Robustness](resiliency.md)\n-   [Scala](scala.md)\n-   [Security](security.md)\n-   [Services](services.md)\n-   [Thrift](thrift.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fguardian%2Frecommendations","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fguardian%2Frecommendations","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fguardian%2Frecommendations/lists"}