From 057cc0b63229c1c05fe9fc05b19185b559a358aa Mon Sep 17 00:00:00 2001 From: Jean-Hadrien Chabran Date: Thu, 2 May 2024 15:28:33 +0200 Subject: [PATCH] Introduce a Notion specific file to register redirections as part of the migration process (#8922) We already have some code handling redirections, but for simplifying the contribution process for teammates not too familiar with code, we instead introduce a specific YAML file. The format is dead simple, and should not pose any problems for anyone to contribute. ```yaml # data/notion_migration.yaml redirections: - source: /departments/engineering/teams/devinfra destination: https://sourcegraph.notion.site/Developer-Infrastructure-Team-a46433b93bb2445abc1966c93a570a26 ``` Additionally, the deprecation banner also recommend to teammates to submit pull requests if they know the Notion equivalent of a given page: image The separate file is practical for at a later stage, turning the redirections in Cloudflare page rules, once we make handbook.sourcegraph.com point at Notion instead of the legacy handbook app. --------- Co-authored-by: jhchabran Co-authored-by: Robert Lin --- README.md | 20 ++++++++++++++++++++ data/notion_migration.yaml | 6 ++++++ src/components/Banner.tsx | 5 ++++- src/scripts/redirects.mjs | 15 +++++++++++++++ 4 files changed, 45 insertions(+), 1 deletion(-) create mode 100644 data/notion_migration.yaml diff --git a/README.md b/README.md index 64290b52390f..f8f2e706214c 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,26 @@ The handbook is a living document and we expect every teammate to propose improv All content is in [Markdown](https://www.markdownguide.org/getting-started/#what-is-markdown) files under the [📁 content](./content) folder. +## :warning: Ongoing migration to Notion.so + +We are in the process of moving the handbook over Notion.so. In the original spirit of the handbook, we want most pages to stay publicly accessible. + +- If you intend to contribute to the handbook, please instead do so on the Notion corresponding page, or port it if that's not yet done. +- If you maintain a set of pages, please take some time to add the corresponding redirection to the Notion equivalent in [data/notion_migration.yaml]. + +### Plan + +- [x] Set up basic Notion structure +- [x] Port the most important pages +- [] Port the remaining content +- Populate redirections for important pages to their Notion equivalent. +- May 1st: pull request for content change are subject to strict review. + - Only necessary changes are allowed. +- May 15th: content changes are forbidden, only redirections are accepted. +- May 31th: repository is archived. +- `handbook.sourcegraph.com` is now serving Notion pages. + - Previously set redirections are ported from the application to Cloudflare page rules. + ### Need help editing? Ask in the [#handbook channel](https://app.slack.com/client/T02FSM7DL/CQ44Y7F4G) (for Sourcegraph team members), and/or [post an issue](https://github.com/sourcegraph/handbook/issues). diff --git a/data/notion_migration.yaml b/data/notion_migration.yaml new file mode 100644 index 000000000000..cf66126536fc --- /dev/null +++ b/data/notion_migration.yaml @@ -0,0 +1,6 @@ +# Add your desired redirections here! +# - 'source': URL path to redirect, as currently visible on handbook.sourcegraph.com +# - 'destination': New URL top direct to. If a public 'sourcegraph.notion.site' page is available, prefer that instead of the internal Notion URL. +redirections: + - source: /departments/engineering/teams/devinfra + destination: https://sourcegraph.notion.site/Developer-Infrastructure-Team-a46433b93bb2445abc1966c93a570a26 diff --git a/src/components/Banner.tsx b/src/components/Banner.tsx index 4c73d2d8040b..06907c1eb6c1 100644 --- a/src/components/Banner.tsx +++ b/src/components/Banner.tsx @@ -21,7 +21,10 @@ export function Banner({ path }: { path: string }): JSX.Element {
The contents of this page will only be retained until end of May 2024. If you own this page, please maintain an equivalent in the new{' '} - Notion-based handbook. + Notion-based handbook. You can set up a redirection to + the corresponding Notion page by making a pull request against{' '} + this file to + match the handbook path with the new Notion page. , ] diff --git a/src/scripts/redirects.mjs b/src/scripts/redirects.mjs index 3d4d0fedaa64..36a2ac378211 100644 --- a/src/scripts/redirects.mjs +++ b/src/scripts/redirects.mjs @@ -1,3 +1,7 @@ +import { readFile } from 'fs/promises' + +import { load } from 'js-yaml' + import { getMovedPagesFromHistory } from './getMovedPagesFromHistory.mjs' /** @@ -24,6 +28,15 @@ export function cleanupRedirects(movedPages) { return [...redirects.entries()].map(([source, destination]) => ({ source, destination })) } +/** + * Reads Notion specific redirections from data/notion_migration.yaml. + * + * @returns {redirections: {source: string, destination: string}[]} + */ +async function readNotionMigrationRedirects() { + return load(await readFile('data/notion_migration.yaml', 'utf8')) +} + /** * Returns all redirects that should be generated. * @@ -31,8 +44,10 @@ export function cleanupRedirects(movedPages) { */ export default async function redirects() { const movedPages = await getMovedPagesFromHistory() + const notionRedirections = await readNotionMigrationRedirects() return cleanupRedirects([ ...movedPages, + ...notionRedirections.redirections, // Add custom redirects {