Could you please update ALL your documentation

[mahnunchik]

Environment

SaaS (https://sentry.io/)

Steps to Reproduce

Open any documentation or code sample after project creation.

Configure Koa SDK

const requestHandler = (ctx, next) => {
  return new Promise((resolve, reject) => {
    Sentry.runWithAsyncContext(async () => {
      const hub = Sentry.getCurrentHub();
      hub.configureScope((scope) =>
        scope.addEventProcessor((event) =>
          Sentry.addRequestDataToEvent(event, ctx.request, {
            include: {
              user: false,
            },
          })
        )
      );

      try {
        await next();
      } catch (err) {
        reject(err);
      }
      resolve();
    });
  });
};

• configureScope deprecated
• getCurrentHub deprecated

And there is no documentation how to replace deprecated methods.

CaptureConsole

https://docs.sentry.io/platforms/javascript/configuration/integrations/captureconsole/

CaptureConsole is deprecated and there is no documentation about how to use captureConsoleIntegration.

Expected Result

Documentation and code samples are update.

Actual Result

Documentation and code samples are outdated.

Product Area

Other

Link

any

DSN

any

Version

7.94.1

[getsantry]

Assigning to @getsentry/support for routing ⏲️

[getsantry]

Routing to @getsentry/product-owners-issues-suggested-fix for triage ⏲️

[Inlustra]

Obviously don't want to bump for bumps sake.
This is the third time I've added to my new monorepo and something come up as deprecated.

Capture console for one.
In a NextJS project this was automatically added by the CLI:

// This file configures the initialization of Sentry on the client.
// The config you add here will be used whenever a users loads a page in their browser.
// https://docs.sentry.io/platforms/javascript/guides/nextjs/

import * as Sentry from "@sentry/nextjs";

Sentry.init({
  dsn: "..redacted..",

  // Adjust this value in production, or use tracesSampler for greater control
  tracesSampleRate: 1,

  // Setting this option to true will print useful information to the console while you're setting up Sentry.
  debug: false,

  replaysOnErrorSampleRate: 1.0,

  // This sets the sample rate to be 10%. You may want this to be 100% while
  // in development and sample at a lower rate in production
  replaysSessionSampleRate: 0.1,

  // You can remove this option if you're not planning to use the Sentry Session Replay feature:
  integrations: [
    new Sentry.Replay({
      // Additional Replay configuration goes in here, for example:
      maskAllText: true,
      blockAllMedia: true,
    }),
  ],
});

However Sentry.Replay is also deprecated? The CLI added something already deprecated?

[hubertdeng123]

This doesn't look like the right product area, I'm going to transfer over to docs.

[getsantry]

Assigning to @getsentry/support for routing ⏲️

[mahnunchik]

At least documentation for NodeJS, Koa, Express, Vue, NextJS are outdated.

[mydea]

Hey, I will close this issue in favor of #8982 where we are tracking this.
We are currently in the process of preparing for v8, which includes a bunch of deprecations being shipped. We'll work on updating the docs to avoid the deprecations as soon as possible. For now, everything should still work as intended. I understand that it is a bit annoying to have these deprecations, so we'll try to resolve these as fast as possible.

For the koa specific one, please see my comment here: #8973 (comment)

[Inlustra]

Shouldn't the approach be - write the docs and solidify the new API with customers, and then deprecate?

[mydea]

There is nothing wrong with using the deprecated methods. They still work fine and we commit that they will continue to work fine in the v7 cycle. For some APIs a proper, full replacement relies on multiple pieces being in place, making it hard to document the full replacement in advance every time. I understand that this can still be annoying, and we're actively working to update the docs right now.

[Inlustra]

To clarify, I have no issues with using the deprecated methods, but every developer looking to keep their codebase up to date will immediately go looking to see what they should be using and therefore waste their time.

It would be better to only deprecate when you want developers to move away from a given API and have something for them to move to. Especially at sentry's scale.

On top of this, it is now my duty to go and check out your docs every so often to see if the new APIs are ready, resulting even more time wasted.

[mydea]

To clarify, I have no issues with using the deprecated methods, but every developer looking to keep their codebase up to date will immediately go looking to see what they should be using and therefore waste their time.

It would be better to only deprecate when you want developers to move away from a given API and have something for them to move to. Especially at sentry's scale.

On top of this, it is now my duty to go and check out your docs every so often to see if the new APIs are ready, resulting even more time wasted.

So for everything we deprecate there is immediately an entry in the MIGRATION.md file, as well as a jsdoc comment explaining how to refactor this specific piece of code. So you can already see how you should refactor your deprecated code - the docs are not (and will not be) the place to find how to update your deprecated code.

So if you see something in your codebase that is deprecated, you can choose to either ignore it for now until you update to the next major, or you can read the deprecation message that is provided via jsdoc to see how you need to update this. And for more details, you can refer to the MIGRATION.md file, which has more details on what is deprecated and how to replace it. These are living documents and are always up to date with the actual code base, and are also the only official place we maintain about deprecations.

To be clear, everything that is being deprecated already has a replacement. We spent a lot of effort ensuring this. The replacement is also always documented in the MIGRATION.md file as well as in the jsdoc deprecation message, at the time the deprecation is added. The only thing that we have not updated fully in time is the docs, but that should not affect anybody updating their application too much, it is only annoying for users getting started that start out with code that is deprecated (which, again, I totally understand and agree that it is annoying and not ideal, and we are working to address this).

I will try to see if we can add a note to the docs themselves pointing this out and refering to the migration doc, maybe that helps avoid confusion in the future.