From a104643346216a776574e44e877e693ff1030f4f Mon Sep 17 00:00:00 2001 From: Wenzhao Hu Date: Thu, 23 Jan 2025 22:16:12 +0800 Subject: [PATCH] chore(core): add deprecate API (#4539) --- CONTRIBUTING.md | 58 ++++++++----------- .../CONTRIBUTING-FACADE.md | 22 ++++++- packages/core/src/services/log/log.service.ts | 31 +++++++++- packages/find-replace/docs/README.md | 24 ++++---- 4 files changed, 85 insertions(+), 50 deletions(-) rename packages/facade/docs/CONTRIBUTING.md => docs/CONTRIBUTING-FACADE.md (64%) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0c50b4676a8..d0517fcb32c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -10,9 +10,9 @@ Please read our [Code of Conduct](./CODE_OF_CONDUCT.md) before you join in the U If you encounter any issues while using Univer, you can seek help in the following communities: -- [Discord community](https://discord.gg/z3NKNT6D2f) -- [GitHub Discussions](https://github.com/dream-num/univer/discussions) -- Join the Univer Chinese community (please scan the QR code [here](https://univer.ai/enterprises/#%E8%8E%B7%E5%8F%96%E5%95%86%E4%B8%9A%E7%89%88)) +- [Discord community](https://discord.gg/z3NKNT6D2f) +- [GitHub Discussions](https://github.com/dream-num/univer/discussions) +- Join the Univer Chinese community (please scan the QR code [here](https://univer.ai/enterprises/#%E8%8E%B7%E5%8F%96%E5%95%86%E4%B8%9A%E7%89%88)) ## Reporting Issues @@ -20,9 +20,9 @@ If you encounter any issues or have any suggestions while using Univer, please f To better assist you, we recommend: -- Before submitting an issue, please search to see if someone has already raised a similar question. -- We provide an [issue template](https://github.com/dream-num/univer/issues/new/choose) and encourage you to fill it out with sufficient information, which helps us quickly identify the problem. -- Please try to describe the issue in English, as it enables more people to participate in the discussion. We will also make an effort to reply in English to benefit a wider audience. +- Before submitting an issue, please search to see if someone has already raised a similar question. +- We provide an [issue template](https://github.com/dream-num/univer/issues/new/choose) and encourage you to fill it out with sufficient information, which helps us quickly identify the problem. +- Please try to describe the issue in English, as it enables more people to participate in the discussion. We will also make an effort to reply in English to benefit a wider audience. > If you're new to submitting issues, we recommend to read [How To Ask Questions The Smart Way](http://www.catb.org/~esr/faqs/smart-questions.html) and [How to Report Bugs Effectively](https://www.chiark.greenend.org.uk/~sgtatham/bugs.html) before posting. Well-written bug reports help us and help you! @@ -58,7 +58,7 @@ Please refer to [Architecture](https://univer.ai/guides/sheet/architecture/unive The structure of the repository is as follows: -``` +```txt . ├── common/ shared configuration and utilities ├── docs/ documentation @@ -72,7 +72,7 @@ The structure of the repository is as follows: The file structure of a plugin should be organized as follows: -``` +```txt |- common/ |- models/ |- services/ @@ -90,10 +90,10 @@ The file structure of a plugin should be organized as follows: There are some limits on what paths could a file import from. -- common cannot import file in other folders -- models can only import files from common -- services can only import files from models and common -- commands can only import files from common, models and services +- common cannot import file in other folders +- models can only import files from common +- services can only import files from models and common +- commands can only import files from common, models and services During the refactoring process, it is recommended to remove legacy folders such as `Enum`, `Interface`, `Basics`, and `Shared`. @@ -103,7 +103,7 @@ Avoid creating barrel imports (index.ts) unless it is the main root index.ts fil We added experimental support for mobile platforms since June 2024. After that, all UI plugins should split ui related code by their running platforms: -``` +```txt |- controllers/ |- render-controllers/ |- common/ @@ -138,8 +138,8 @@ Please refer to [Univer Naming Convention](./docs/NAMING_CONVENTION.md). Before merging a pull request, please make sure the following requirements are met: -- All tests are passed. ESLint and Prettier errors are fixed. -- Test coverage is not decreased. +- All tests are passed. ESLint and Prettier errors are fixed. +- Test coverage is not decreased. We provide preview deployments for pull requests. You can view the preview deployment by clicking the "Preview" link in the "View Deployment" section. @@ -210,18 +210,17 @@ pnpm dev:libs Univer uses Playwright to perform visual comparison tests. If you have made changes to the UI, the CI may fail due to visual differences. You can update the snapshots by running this GitHub Action [📸 Manually Update Snapshots · Workflow runs · dream-num/univer (github.com)](https://github.com/dream-num/univer/actions/workflows/update-snapshots-manually.yml) on your branch. - ### Clean code > Programs are meant to be ready by humans and only incidentally for computers to execute. - Harold Abelson -- Do not expose properties or methods those are not necessary to be exposed. -- Group related methods or properties together. Do not always use blank lines to separate them. -- Keep your concepts consistent by naming your variables consistently. +- Do not expose properties or methods those are not necessary to be exposed. +- Group related methods or properties together. Do not always use blank lines to separate them. +- Keep your concepts consistent by naming your variables consistently. References: -* [Make your code readable](https://www.notonlycode.org/make-your-code-readable/) +- [Make your code readable](https://www.notonlycode.org/make-your-code-readable/) ### New Package @@ -237,20 +236,13 @@ npm create @univerjs/cli init ``` ### How to Contribute to Facade API -#### Synchronous API Priority -* For asynchronous APIs, consider the following: Can a synchronous sub-API be extracted, separating logic such as secondary confirmation. -* For APIs that must be asynchronous, indicate this in the method name, such as `addCommentAsync`. - -#### Chaining Principle -*. APIs must adhere to the chaining principle. -*. APIs with `modify` semantics should return `this`. -*. APIs with `create` semantics should return the created instance. -*. APIs with `delete` semantics should return `true/false`. -#### Easy to Get -*. All APIs/constants/enums should be accessible from the `univerAPI` variable. +Please refer to [How to Contribute to Facade API](./docs/CONTRIBUTING.md). +### Deprecate API -## Links +If you are going to deprecate an API, please follow the steps below: -* [How to Contribute to Facade API](./packages/facade/docs/CONTRIBUTING.md) +1. Mark the API as deprecated in the JSDoc, and use `{@link }` to refer to the new API. +2. In the implementation, call `deprecate` of `ILogService` to log a deprecation message. +3. Remove the API in the next minor version. If the API is considered heavily used, you can remove it in the next major version, e.g. 1.0.0. diff --git a/packages/facade/docs/CONTRIBUTING.md b/docs/CONTRIBUTING-FACADE.md similarity index 64% rename from packages/facade/docs/CONTRIBUTING.md rename to docs/CONTRIBUTING-FACADE.md index a82125e6323..a5cceec6f68 100644 --- a/packages/facade/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING-FACADE.md @@ -1,8 +1,6 @@ # How to Contribute to Facade API -Facade API is an API layer of all other packages of Univer and it helps users to use Univer easily. For a detailed introduction of Facade API, please visit [Facade API](https://univer.ai/guides/sheet/facade/facade). - -## How to Contribute +Facade API is an API layer of all other packages of Univer and it helps users to use Univer easily. For a detailed introduction of Facade API, please visit [Facade API](https://docs.univer.ai/en-US/guides/sheets/getting-started/facade). Facade API is consists of multi classes such as `FUniver`, `FWorkbook` and `FRange` etc. You can refer to Google's [AppScripts](https://developers.google.com/apps-script/reference/spreadsheet) to design Facade API. @@ -31,6 +29,24 @@ export class FWorkbook { } ``` +## Synchronous API Priority + +- For asynchronous APIs, consider the following: Can a synchronous sub-API be extracted, separating logic such as secondary confirmation. +- For APIs that must be asynchronous, indicate this in the method name, such as `addCommentAsync`. + +## Chaining Principle + +APIs must adhere to the chaining principle: + +- APIs with `modify` semantics should return `this`. +- APIs with `create` semantics should return the created instance. +- APIs with `delete` semantics should return `true/false`. + +## Easy to Get + +All APIs/constants/enums should be accessible from the `univerAPI` variable. + ## Documentation It is strongly suggested to add documentation for your code [here](https://github.com/dream-num/univer.ai/tree/dev/packages/community/src/content/docs/guides/sheet/facade). Please refer to our [documentation repo](https://github.com/dream-num/docs) for more guidance. + diff --git a/packages/core/src/services/log/log.service.ts b/packages/core/src/services/log/log.service.ts index 3ca9388dc6a..debbda9d252 100644 --- a/packages/core/src/services/log/log.service.ts +++ b/packages/core/src/services/log/log.service.ts @@ -17,7 +17,6 @@ /* eslint-disable no-console */ import { createIdentifier } from '../../common/di'; - import { Disposable } from '../../shared/lifecycle'; export enum LogLevel { @@ -28,13 +27,17 @@ export enum LogLevel { VERBOSE = 4, } +// eslint-disable-next-line ts/no-explicit-any type ArgsType = any[]; +type ConsoleType = typeof console.log | typeof console.error | typeof console.warn | typeof console.debug; + export interface ILogService { debug(...args: ArgsType): void; log(...args: ArgsType): void; warn(...args: ArgsType): void; error(...args: ArgsType): void; + deprecate(...args: ArgsType): void; setLogLevel(enabled: LogLevel): void; } @@ -43,6 +46,7 @@ export const ILogService = createIdentifier('univer.log'); export class DesktopLogService extends Disposable implements ILogService { private _logLevel: LogLevel = LogLevel.INFO; + private _deduction = new Set(); debug(...args: ArgsType): void { if (this._logLevel >= LogLevel.VERBOSE) { @@ -68,12 +72,18 @@ export class DesktopLogService extends Disposable implements ILogService { } } + deprecate(...args: ArgsType): void { + if (this._logLevel >= LogLevel.WARN) { + this._logWithDeduplication(console.error, ...args); + } + } + setLogLevel(logLevel: LogLevel): void { this._logLevel = logLevel; } private _log( - method: typeof console.log | typeof console.error | typeof console.warn | typeof console.debug, + method: ConsoleType, ...args: ArgsType ): void { const firstArg = args[0]; @@ -84,4 +94,21 @@ export class DesktopLogService extends Disposable implements ILogService { method(...args); } } + + private _logWithDeduplication( + method: ConsoleType, + ...args: ArgsType + ): void { + const hashed = hashLogContent(...args); + if (this._deduction.has(hashed)) { + return; + } + + this._deduction.add(hashed); + this._log(method, ...args); + } +} + +function hashLogContent(...args: ArgsType): string { + return args.map((a) => JSON.stringify(a)).join(''); } diff --git a/packages/find-replace/docs/README.md b/packages/find-replace/docs/README.md index 6d0d902e153..49ec028ef38 100644 --- a/packages/find-replace/docs/README.md +++ b/packages/find-replace/docs/README.md @@ -12,26 +12,26 @@ Overall, F&D is divided into many packages and works as plugins. This package (@ What does this package do? -- UI - - TODO: Some UI should be determined by business plugins? +- UI + - TODO: Some UI should be determined by business plugins? What do business packages (e.g @univerjs/sheets-find-replace) do? 由 find-replace 包提供查找替换的调度服务、接口以及 UI，业务包提供具体的查找替换方法 -- 输入查找内容 -- 确定搜索范围，当前 focused 的业务，或者全部的业务 -- 切换查找模式 -- 接收各个业务提供的查找结果（可能需要支持动态查找） -- 定位查找项的位置 -- 结束查找 -- 执行替换或者全部替换 +- 输入查找内容 +- 确定搜索范围，当前 focused 的业务，或者全部的业务 +- 切换查找模式 +- 接收各个业务提供的查找结果（可能需要支持动态查找） +- 定位查找项的位置 +- 结束查找 +- 执行替换或者全部替换 各个包要做的事情 -- 根据查找字符串的变化来搜索并把结果塞给 find-replace -- 查找高亮，定位到查找位置 -- 执行替换 & re-update 查找结果 +- 根据查找字符串的变化来搜索并把结果塞给 find-replace +- 查找高亮，定位到查找位置 +- 执行替换 & re-update 查找结果 ## Supported features in Jan 2024