From 68cec1349b7247d14449d6f5de7394e9a96a92d9 Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Wed, 7 Sep 2022 14:26:23 +0200 Subject: [PATCH] Fix broken doc links (#2046) ## What This PR fixes some broken links that have been hanging around in the docs for what seems like a very long time. ## Why As discovered by the link check in #1912, there are a fair few broken links in the docs. Everyone hates broken links because it makes it harder to understand what they were supposed to be pointing at. ## How There are 3 types of links that have been fixed: - Links that should have been internal but were absolute. E.g. `https://docs.getunleash.io/path/article` that should have been `./article.md` - External links that have changed, such as Slack's API description - GitHub links to files that either no longer exist or that have been moved. These links generally pointed to `master`/`main`, meaning they are subject to change. They have been replaced with permalinks pointing to specific commits. ----- * docs: fix slack api doc link * docs: update links in migration guide * docs: fix broken link to ancient feature schema validation * docs: update links to v3 auth hooks * docs: update broken link in the go sdk article * Fix: use permalink for GitHub link * docs: fix wrong google auth link --- website/docs/deploy/configuring-unleash-v3.md | 2 +- website/docs/deploy/migration-guide.md | 9 ++++----- website/docs/deploy/securing-unleash-v3.md | 14 +++++++------- website/docs/guides/feature-updates-to-slack.md | 10 ++++++---- website/docs/sdks/go.md | 2 +- 5 files changed, 19 insertions(+), 18 deletions(-) diff --git a/website/docs/deploy/configuring-unleash-v3.md b/website/docs/deploy/configuring-unleash-v3.md index a4b9670000..c011159ab2 100644 --- a/website/docs/deploy/configuring-unleash-v3.md +++ b/website/docs/deploy/configuring-unleash-v3.md @@ -60,7 +60,7 @@ unleash.start(unleashOptions); - `custom` - use this when you implement your own custom authentication logic. - **ui** (object) - Set of UI specific overrides. You may set the following keys: `headerBackground`, `environment`, `slogan`. - **getLogger** (function) - Used to register a [custom log provider](#how-do-i-configure-the-log-output). -- **eventHook** (`function(event, data)`) - If provided, this function will be invoked whenever a feature is mutated. The possible values for `event` are `'feature-created'`, `'feature-updated'`, `'feature-archived'`, `'feature-revived'`. The `data` argument contains information about the mutation. Its fields are `type` (string) - the event type (same as `event`); `createdBy` (string) - the user who performed the mutation; `data` - the contents of the change. The contents in `data` differs based on the event type; For `'feature-archived'` and `'feature-revived'`, the only field will be `name` - the name of the feature. For `'feature-created'` and `'feature-updated'` the data follows a schema defined in the code [here](https://github.com/Unleash/unleash/blob/master/lib/routes/admin-api/feature-schema.js#L38-L59). See an [api here](/api/admin/events). +- **eventHook** (`function(event, data)`) - If provided, this function will be invoked whenever a feature is mutated. The possible values for `event` are `'feature-created'`, `'feature-updated'`, `'feature-archived'`, `'feature-revived'`. The `data` argument contains information about the mutation. Its fields are `type` (string) - the event type (same as `event`); `createdBy` (string) - the user who performed the mutation; `data` - the contents of the change. The contents in `data` differs based on the event type; For `'feature-archived'` and `'feature-revived'`, the only field will be `name` - the name of the feature. For `'feature-created'` and `'feature-updated'` the data follows [this schema defined in the source code](https://github.com/Unleash/unleash/blob/a06d2c04bb0d83d9c8c5bf2a90e9dace50f0b10a/lib/routes/admin-api/feature-schema.js#L38-L59). See an [api here](/api/admin/events). - **baseUriPath** (string) - use to register a base path for all routes on the application. For example `/my/unleash/base` (note the starting /). Defaults to `/`. Can also be configured through the environment variable `BASE_URI_PATH`. - **unleashUrl** (string) - Used to specify the official URL this instance of Unleash can be accessed at for an end user. Can also be configured through the environment variable `UNLEASH_URL`. - **secureHeaders** (boolean) - use this to enable security headers (HSTS, CSP, etc) when serving Unleash from HTTPS. Can also be configured through the environment variable `SECURE_HEADERS`. diff --git a/website/docs/deploy/migration-guide.md b/website/docs/deploy/migration-guide.md index dc0fe0b447..e495956f02 100644 --- a/website/docs/deploy/migration-guide.md +++ b/website/docs/deploy/migration-guide.md @@ -42,7 +42,7 @@ const user = userService.loginUserWithoutPassword( req.session.user = user; ``` -- [Read more about Securing Unleash v4](./securing_unleash) +- [Read more about Securing Unleash v4](./securing-unleash.md) - [Read more about RBAC](../user_guide/rbac) ### 4. Legacy v2 routes removed {#4-legacy-v2-routes-removed} @@ -59,18 +59,17 @@ Read more in our [getting started documentation](./getting_started) ## Upgrading from v2.x to v3.x {#upgrading-from-v2x-to-v3x} -The notable change introduced in Unleash v3.x is a strict separation of API paths for client requests and admin requests. This makes it easier to implement different authentication mechanisms for the admin UI and all unleash-clients. You can read more about [securing unleash](https://github.com/Unleash/unleash/blob/master/docs/securing-unleash.md). +The notable change introduced in Unleash v3.x is a strict separation of API paths for client requests and admin requests. This makes it easier to implement different authentication mechanisms for the admin UI and all unleash-clients. You can read more about [securing unleash](./securing-unleash.md). The recommended approach is to first upgrade the `unleash-server` to v3 (which still supports v2 clients). After this is done, you should upgrade all your clients to v3. -After upgrading all your clients, you should consider turning off legacy routes, used by v2 clients. Read more about this option in the [Getting started guide](https://github.com/Unleash/unleash/blob/master/docs/getting-started.md#2-or-programmatically). +After upgrading all your clients, you should consider turning off legacy routes, used by v2 clients. To do this, set the configuration option `enableLegacyRoutes` to `false` as described in the [page on configuring Unleash v3](./configuring-unleash-v3.md). ## Upgrading from v1.0 to v2.0 {#upgrading-from-v10-to-v20} ### Caveat 1: Not used db-migrate to migrate the Unleash database? {#caveat-1-not-used-db-migrate-to-migrate-the-unleash-database} -In FINN we used liquibase, for internal reasons, to migrate our database. -Because unleash from version 2.0 migrates the database internally, with db-migrate, you need to make sure that all previous migrations for version 1 exist, so that Unleash does not try to create already existing tables. +In FINN we used liquibase, for internal reasons, to migrate our database. Because unleash from version 2.0 migrates the database internally, with db-migrate, you need to make sure that all previous migrations for version 1 exist, so that Unleash does not try to create already existing tables. #### How to check? {#how-to-check} diff --git a/website/docs/deploy/securing-unleash-v3.md b/website/docs/deploy/securing-unleash-v3.md index fea74d92e5..f08097a972 100644 --- a/website/docs/deploy/securing-unleash-v3.md +++ b/website/docs/deploy/securing-unleash-v3.md @@ -25,7 +25,7 @@ unleash adminAuthentication: 'custom', preRouterHook: myCustomAdminAuth, }) - .then(unleash => { + .then((unleash) => { console.log( `Unleash started on http://localhost:${unleash.app.get('port')}`, ); @@ -43,9 +43,9 @@ Additionally, you can trigger the admin interface to prompt the user to sign in Examples of custom authentication hooks: -- [google-auth-hook.js](https://github.com/Unleash/unleash/blob/master/examples/google-auth-hook.js) -- [basic-auth-hook.js](https://github.com/Unleash/unleash/blob/master/examples/basic-auth-hook.js) -- [keycloak-auth-hook.js](https://github.com/Unleash/unleash/blob/master/examples/keycloak-auth-hook.js) +- [google-auth-hook.js](https://github.com/Unleash/unleash-examples/blob/7ed25f97a31dfd8f773c00847080b1a4c889fd87/v3/securing-google-auth/google-auth-hook.js) +- [basic-auth-hook.js](https://github.com/Unleash/unleash-examples/blob/7ed25f97a31dfd8f773c00847080b1a4c889fd87/v3/securing-basic-auth/basic-auth-hook.js) +- [keycloak-auth-hook.js](https://github.com/Unleash/unleash-examples/blob/7ed25f97a31dfd8f773c00847080b1a4c889fd87/v3/securing-keycloak-auth/keycloak-auth-hook.js) We also have a version of Unleash deployed on Heroku which uses Google OAuth 2.0: https://secure-unleash.herokuapp.com @@ -73,7 +73,7 @@ const sharedSecret = '12312Random'; unleash .start({ databaseUrl: 'postgres://unleash_user:passord@localhost:5432/unleash', - preRouterHook: app => { + preRouterHook: (app) => { app.use('/api/client', (req, res, next) => { if (req.header('authorization') !== sharedSecret) { res.sendStatus(401); @@ -83,11 +83,11 @@ unleash }); }, }) - .then(unleash => { + .then((unleash) => { console.log( `Unleash started on http://localhost:${unleash.app.get('port')}`, ); }); ``` -[client-auth-unleash.js](https://github.com/Unleash/unleash/blob/master/examples/client-auth-unleash.js) +[client-auth-unleash.js](https://github.com/Unleash/unleash-examples/blob/7ed25f97a31dfd8f773c00847080b1a4c889fd87/v3/securing-client-auth/index.js) diff --git a/website/docs/guides/feature-updates-to-slack.md b/website/docs/guides/feature-updates-to-slack.md index 3fa05e59a8..9e661a1a94 100644 --- a/website/docs/guides/feature-updates-to-slack.md +++ b/website/docs/guides/feature-updates-to-slack.md @@ -4,7 +4,9 @@ title: Feature Updates To slack --- :::caution + This guide is deprecated. If you're looking for ways to integrate with Slack, you should refer to [the Slack add-on guide](../addons/slack.md) instead. + ::: ## Create a custom Slack WebHook url: {#create-a-custom-slack-webhook-url} @@ -12,7 +14,7 @@ This guide is deprecated. If you're looking for ways to integrate with Slack, yo 1. Go to [https://slack.com/apps/manage/custom-integrations](https://slack.com/apps/manage/custom-integrations) 1. Click Incoming WebHooks 1. Click “Add Configuration” -1. This is Slack's help page on how to do this: https://api.slack.com/custom-integrations/incoming-webhooks +1. This is Slack's help page on how to do this: https://api.slack.com/messaging/webhooks - Choose a channel, follow the wizard, get the custom URL. ## Send data to Slack using an event hook function {#send-data-to-slack-using-an-event-hook-function} @@ -63,10 +65,10 @@ function onEventHook(event, eventData) { text: text, }, ) - .then(res => { + .then((res) => { console.log(`Slack post statusCode: ${res.status}. Text: ${text}`); }) - .catch(error => { + .catch((error) => { console.error(error); }); } @@ -75,7 +77,7 @@ const options = { eventHook: onEventHook, }; -unleash.start(options).then(server => { +unleash.start(options).then((server) => { console.log(`Unleash started on http://localhost:${server.app.get('port')}`); }); ``` diff --git a/website/docs/sdks/go.md b/website/docs/sdks/go.md index d2dd2f215c..24211de758 100644 --- a/website/docs/sdks/go.md +++ b/website/docs/sdks/go.md @@ -69,7 +69,7 @@ Read more about the strategies in [the activation strategies document](../user_g ### Unleash context {#unleash-context} -In order to use some of the common activation strategies you must provide a [unleash-context](https://github.com/Unleash/unleash/blob/master/docs/unleash-context.md). This client SDK allows you to send in the unleash context as part of the `isEnabled` call: +In order to use some of the common activation strategies you must provide an [_Unleash context_](../user_guide/unleash-context.md). This client SDK allows you to send in the unleash context as part of the `isEnabled` call: ```go ctx := context.Context{