diff --git a/docs/en/changes/changes.md b/docs/en/changes/changes.md index 0a2b100a5f2b..d8410c1ee562 100644 --- a/docs/en/changes/changes.md +++ b/docs/en/changes/changes.md @@ -21,5 +21,6 @@ * Update the release notification mail a little. * Polish docs structure. Move customization docs separately from the introduction docs. * Add webhook/gRPC hooks settings example for `backend-alarm.md`. +* Begin the process of `SWIP - SkyWalking Improvement Proposal`. All issues and pull requests are [here](https://github.com/apache/skywalking/milestone/202?closed=1) diff --git a/docs/en/swip/readme.md b/docs/en/swip/readme.md new file mode 100644 index 000000000000..dd18a75a5e7d --- /dev/null +++ b/docs/en/swip/readme.md @@ -0,0 +1,57 @@ +# SWIP - SkyWalking Improvement Proposal + +SWIP - SkyWalking Improvement Proposal, is an official document to propose a new feature and/or feature improvement, +which +are relative to end users and developers. + +SkyWalking has been very stable since v9.x. We are getting over the rapid changing stage. The core concepts, protocols for +reporting telemetry and query, 3rd party integration, and the streaming process kernel are very stable. From now(2024) on, +SkyWalking community would focus more on improvement and controllable improvement. All major changes should be evaluated +more seriously, and try as good as possible to avoid incompatible breaking changes. + +## What is considered a major change? + +The catalogs of a major change are listed as follows + +- New Feature. A feature doesn't exist for the latest version. +- Any change of the network Interfaces, especially + for [Query Protocol](https://github.com/apache/skywalking-query-protocol), + [Data Collect Protocols](https://github.com/apache/skywalking-data-collect-protocol), + Dynamic Configuration APIs, Exporting APIs, AI pipeline APIs. +- Any change of storage structure. + +**Q: Is Agent side feature or change considered a SWIP?** + +A: Right now, SWIP targets on OAP and UI side changes. All agent side changes are pending on the reviews from the +committers of those agents. + +## SWIP Template + +The purpose of this template should not be considered a hard requirement. The major purpose of SWIP is helping the PMC +and community member to understand the proposal better. + +* Title: SWIP-1234 xxxx + +- Motivation - the description of new feature or improvement. +- Architecture Graph - describing the relationship between your new proposal part and existing components. +- Imported Dependencies libs and their licenses. +- Compatibility - Whether breaking configuration, storage structure, protocols. +- General usage docs - This doesn't have to be final version, but help the reviews to understand how to use this new + feature. + +## SWIP Process + +Here is the process for starting a SWIP. + +1. Start a discussion at [GitHub Discussion Page](https://github.com/apache/skywalking/discussions) with + title `[DISCUSS] xxxx`. +2. Fill in the sections as described above in `SWIP Template`. +3. At least one SkyWalking committer commented on the discussion to show interests to adopt it. +4. This committer could update this page to grant a **SWIP ID**, and update the title to `[SWIP-ID NO.] [DISCUSS] xxxx`. +5. All further discussion could happen on the discussion page. +6. Once the consensus is made by enough committer supporters, and/or through a mail list vote, this SWIP should be + added [here](./) as `SWIP-ID NO.md` and listed in the below as `Known SWIPs`. + +## Known SWIPs + +Next SWIP Number: 2 diff --git a/docs/menu.yml b/docs/menu.yml index 6a6432919af1..d88ad1cdbf97 100644 --- a/docs/menu.yml +++ b/docs/menu.yml @@ -370,6 +370,8 @@ catalog: path: "/en/guides/how-to-bump-up-zipkin" - name: "I18n" path: "/en/guides/i18n" + - name: "SWIP" + path: "/en/swip/readme" - name: "Changelog" catalog: - name: "Current Version"