From 3f2f105c9aa4e5744411f025e970b4d36ecdcf5d Mon Sep 17 00:00:00 2001 From: Ryan Brooks Date: Thu, 23 Jan 2025 09:57:41 +0000 Subject: [PATCH 1/2] Fix 404 for direct link access GitHub pages handles requests differently to the current setup for client-siderouting, which is causing 404 errors if you refresh a page or attempt to visit a URL provided by someone. The site is generated with links that _don't_ have a trailing slash to denote a folder, e.g. `href="/ways-of-working"` when the actual HTML is stored in `/ways-of-working/index.html`. The client-side routing is configured in the same way, so within the site all links work. The build also succeeds because there are no invalid links according to the client-side routing rules. That in itself is not a problem, however GitHub pages doesn't resolve a non-trailing slash path to the `index.html` within the folder. Instead it's looking for content in `/ways-of-working.html`, which doesn't exist. As a result no links that are generated or valid within the Docusaurus Single Page App will resolve when accessed directly in GitHub Pages. This change configures Docusaurus to use trailing slashes for folders, which will change both the way it generates output folders/files _and_ how client side routing works. This _should_ make client and server routing consistent and fix the problem. This hasn't been tested because we don't have a staging environment so the easiest way to validate the fix is to ship it to production and revert it if we don't get the results we want. 1. Visit the playbook.hackey.gov.uk 2. Navigate to Ways of Working 3. Hard refresh or open the same link in a a new window. 4. Validate that the page isn't a 404 --- docusaurus.config.js | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docusaurus.config.js b/docusaurus.config.js index 5bf3ce0..7ec9318 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -22,7 +22,11 @@ const config = { // If you aren't using GitHub pages, you don't need these. organizationName: 'LBHackney-IT', // Usually your GitHub org/user name. projectName: 'lbhackney-it.github.io', // Usually your repo name. - trailingSlash: false, + + // CAUTION! This alters how client routing behaves but NOT the hosting + // provider. See https://github.com/slorber/trailing-slash-guide + // GitHub pages returns 404s when refreshing a page when trailingSlash: false + trailingSlash: true, onBrokenLinks: 'throw', onBrokenMarkdownLinks: 'warn', From adec0f2d3e93fdc7122b18312fd47065cadfa936 Mon Sep 17 00:00:00 2001 From: Ryan Brooks Date: Thu, 23 Jan 2025 10:37:20 +0000 Subject: [PATCH 2/2] Fix broken links following change in trailingSlash The previous commit changing trailingSlash handling to true introduced some broken links: ``` Exhaustive list of all broken links found: - Broken link on source page path = /api-playbook/Governance/api_compliance/: -> linking to ../../api-playbook/ (resolved as: /api-playbook/api-playbook/) - Broken link on source page path = /api-playbook/Governance/developer_onboarding/: -> linking to ../../api-specifications/ (resolved as: /api-playbook/api-specifications/) - Broken link on source page path = /api-playbook/Support/creating_support_doc/: -> linking to ../../api-playbook/ (resolved as: /api-playbook/api-playbook/) - Broken link on source page path = /architecture-pillars/Development practices/api_compliance/: -> linking to ../../api-playbook/ (resolved as: /architecture-pillars/api-playbook/) - Broken link on source page path = /architecture-pillars/Development practices/developer_onboarding/: -> linking to ../../ways-of-working/ (resolved as: /architecture-pillars/ways-of-working/) - Broken link on source page path = /architecture-pillars/Reliability/core_resource_compliance/: -> linking to ../../api-playbook/ (resolved as: /architecture-pillars/api-playbook/) ``` Fixing these links to point directly to the source markdown file resolves the build failure and lets Docusaurus generate the correct final link (whether it has as trailing slash or not), so this approach is more robust. --- docs/api-playbook/Governance/api_compliance.md | 2 +- docs/api-playbook/Governance/developer_onboarding.md | 2 +- docs/api-playbook/Support/creating_support_doc.md | 2 +- .../Development practices/api_compliance.md | 2 +- .../Development practices/developer_onboarding.md | 4 ++-- .../Reliability/core_resource_compliance.md | 2 +- 6 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/api-playbook/Governance/api_compliance.md b/docs/api-playbook/Governance/api_compliance.md index 285d7e0..4980d91 100644 --- a/docs/api-playbook/Governance/api_compliance.md +++ b/docs/api-playbook/Governance/api_compliance.md @@ -10,7 +10,7 @@ The APIs compliance checklist will be used as part of future Service Standard As ### Checklist 1. The API has corresponding SwaggerHub documentation for all of the API endpoints it exposes. 2. The API has completed the [API specification assessment process](../../api-specifications/assessment_process.md) -3. The API has been developed in Hackney’s preferred tech tech stack, unless otherwise agreed and as per standards defined in our [API playbook](../../api-playbook/). +3. The API has been developed in Hackney’s preferred tech tech stack, unless otherwise agreed and as per standards defined in our [API playbook](../README.md). 4. The API has been developed following the TDD approach and has end-to-end tets in place - End-to-end tests guide for DynamoDB - End-to-end tests guide for PostgreSQL diff --git a/docs/api-playbook/Governance/developer_onboarding.md b/docs/api-playbook/Governance/developer_onboarding.md index bfd15c3..a023fbd 100644 --- a/docs/api-playbook/Governance/developer_onboarding.md +++ b/docs/api-playbook/Governance/developer_onboarding.md @@ -46,7 +46,7 @@ All APIs must be built in a reusable manner, unless they implement a very specif We use [SwaggerHub](https://app.swaggerhub.com/organizations/Hackney) to document our APIs and their respective data contracts. All new and existing APIs must have corresponding SwaggerHub documentation. It is the responsibility of the engineers who amend existing APIs to also update the documentation so it is kept up-to-date. - If you or your team is building new APIs or making changes to existing API endpoints, please request SwaggerHub access so you can amend the specifications documented to ensure they are always up-to-date. -In addition, we also have [API specifications](../../api-specifications/), which capture a summary of the user needs and any other findings related to an API. +In addition, we also have [API specifications](../../api-specifications/README.md), which capture a summary of the user needs and any other findings related to an API. - A new API specification must be produced for all new APIs. - The API specification document should link off to the SwaggerHub page that outlines the API contract. - The API specification should be updated when the API introduces new endpoints or changes to existing functionality. diff --git a/docs/api-playbook/Support/creating_support_doc.md b/docs/api-playbook/Support/creating_support_doc.md index be71d94..5f628a4 100644 --- a/docs/api-playbook/Support/creating_support_doc.md +++ b/docs/api-playbook/Support/creating_support_doc.md @@ -25,4 +25,4 @@ To create support documentation that is easy to find and becomes quickly availab - The item to be included should match the id you have given to the support document created. - Create a pull request with your changes. -Once the changes are approved and merged, the support documentation will be available in the [API playbook](../../api-playbook/). +Once the changes are approved and merged, the support documentation will be available in the [API playbook](../README.md). diff --git a/docs/architecture-pillars/Development practices/api_compliance.md b/docs/architecture-pillars/Development practices/api_compliance.md index c902431..d9d55db 100644 --- a/docs/architecture-pillars/Development practices/api_compliance.md +++ b/docs/architecture-pillars/Development practices/api_compliance.md @@ -10,7 +10,7 @@ The APIs compliance checklist will be used as part of future Service Standard As ### Checklist 1. The API has corresponding SwaggerHub documentation for all of the API endpoints it exposes. 2. The API has completed the [API specification assessment process](../../api-specifications/assessment_process.md) -3. The API has been developed in Hackney’s preferred tech tech stack, unless otherwise agreed and as per standards defined in our [API playbook](../../api-playbook/). +3. The API has been developed in Hackney’s preferred tech tech stack, unless otherwise agreed and as per standards defined in our [API playbook](../../api-playbook/README.md). 4. The API has been developed following the TDD approach and has end-to-end tets in place - End-to-end tests guide for DynamoDB - End-to-end tests guide for PostgreSQL diff --git a/docs/architecture-pillars/Development practices/developer_onboarding.md b/docs/architecture-pillars/Development practices/developer_onboarding.md index 392187a..3c02ce6 100644 --- a/docs/architecture-pillars/Development practices/developer_onboarding.md +++ b/docs/architecture-pillars/Development practices/developer_onboarding.md @@ -6,7 +6,7 @@ We love innovation and are always open to learning, iterating and improving. To Our preferred BE stack is documented [here](../../api-playbook/Development%20Lifecycle/How%20to%20build%20an%20API/Preferred%20tech%20stack/Readme.md). ### Development standards -All technical members of a project team must familiarise themselves with [Hackney’s development standards](../../ways-of-working/), which follow the Twelve Factor Application methodology. Those define the high level principles to follow when developing a digital product. +All technical members of a project team must familiarise themselves with [Hackney’s development standards](../../ways-of-working/README.md), which follow the Twelve Factor Application methodology. Those define the high level principles to follow when developing a digital product. ### Playbooks @@ -63,7 +63,7 @@ To set up your developer workstation, please refer to the Workstation Setup Guid ### Technical ways of working #### Pull Request process -Hackney’s official pull request process to follow as part of the Software Development Lifecycle can be found [here](../../ways-of-working/). +Hackney’s official pull request process to follow as part of the Software Development Lifecycle can be found [here](../../ways-of-working/README.md). ### API specifications All APIs must be built in a reusable manner, unless they implement a very specific use case. Any new proposed reusable APIs or changes to the data models of existing ones should follow the [API specification assessment process](../../api-specifications/assessment_process.md). diff --git a/docs/architecture-pillars/Reliability/core_resource_compliance.md b/docs/architecture-pillars/Reliability/core_resource_compliance.md index f0475fe..313ffbf 100644 --- a/docs/architecture-pillars/Reliability/core_resource_compliance.md +++ b/docs/architecture-pillars/Reliability/core_resource_compliance.md @@ -1,7 +1,7 @@ # Core AWS resources compliance checks ### Context -At Hackney, we follow an infrastructure-as-code (IaC) approach and use Terraform to provision most of our AWS cloud resources. For our APIs, which are Lambda functions exposed via AWS API Gateway, we use the Serverless framework as it significantly speeds up the delivery and resource creation. For more information please refer to [our playbook](../../api-playbook/). +At Hackney, we follow an infrastructure-as-code (IaC) approach and use Terraform to provision most of our AWS cloud resources. For our APIs, which are Lambda functions exposed via AWS API Gateway, we use the Serverless framework as it significantly speeds up the delivery and resource creation. For more information please refer to [our playbook](../../api-playbook/README.md). From a Development perspective, each project manages its own Terraform files(or Serverless configuration) to provision resources for our microservices and frontend applications. Terraform is then applied automatically as part of the CI/CD pipeline workflow during deployment.