Skip to content

docs: add comprehensive development guide for contributors#14586

Closed
DocJlm wants to merge 161 commits intoalibaba:masterfrom
DocJlm:docs/improve-readme-zh
Closed

docs: add comprehensive development guide for contributors#14586
DocJlm wants to merge 161 commits intoalibaba:masterfrom
DocJlm:docs/improve-readme-zh

Conversation

@DocJlm
Copy link
Contributor

@DocJlm DocJlm commented Mar 11, 2026

What this PR does

Add comprehensive DEVELOPMENT.md documentation to help new contributors get started quickly.

Changes

  1. Environment Requirements - JDK, Maven, MySQL versions
  2. Quick Start - Clone, build, run, access console
  3. Development Mode - IDE setup, module descriptions
  4. Testing - Unit tests, integration tests
  5. Database Configuration - MySQL setup guide
  6. Debugging Tips - Remote debug, logging
  7. Code Style - Commit message conventions, Checkstyle
  8. Contribution Workflow - Fork, branch, PR steps

Why we need it

Nacos lacks detailed developer documentation. New contributors struggle to set up development environment and understand the project structure.

Testing

  • Documentation follows project style
  • Links are valid
  • Code examples are accurate

Thanks for reviewing! 🎉

wuchubuzai2018 and others added 30 commits November 8, 2022 14:37
* [ISSUES alibaba#17] add oracle datasource plugin

* [ISSUES alibaba#17] add test query comment
* 添加damang插件

* dameng适配mysql的分页

* 添加文档以及注意事项

* 修改错误文字

* 添加表结构相关注意事项

* 添加错误码映射关系

* 适配2.3.0

* 删除脏的语句

* 添加注释

* 添加注释

---------

Co-authored-by: asdc <asdc>
* 添加 Microsoft SQL Server 支持

* 修正错误:意外的虚类的声明

* 修正错误:意外的继承错误与冗余代码的清理
- 实现兼容OpenGauss功能,整理Mapper结果,不在继承Mysql
- 添加 GaussDB 函数枚举类
- 创建 OpenGauss 兼容 MySQL 的数据库模式
- 在数据库类型常量中添加 GaussDB
升级nacos版本2.3.0-SNAPSHOT ==> 2.4.2

Co-authored-by: 杨翊 SionYang <xiweng.yy@alibaba-inc.com>
升级nacos版本2.3.0-SNAPSHOT ==> 2.4.2

Co-authored-by: 杨翊 SionYang <xiweng.yy@alibaba-inc.com>
…urrent time function. (alibaba#63)

Override getFunction method. Implement a function to get the current time dynamically from different databases

Closes alibaba#12786
…urrent time function. (alibaba#63)

Override getFunction method. Implement a function to get the current time dynamically from different databases

Closes alibaba#12786
…a#13703)

* [ISSUE#13322] A2A init.

* update.

* [ISSUE#13322] add agent's admin api.

* [ISSUE#13322] update.

* [ISSUE#13322] update get agent method.
* [ISSUE#13322] Refactor A2A related code and optimize.

* [ISSUE#13322] Update delete agent method.
* Upgrade os-maven-plugin version to 1.7.1

* revert to 1.5

* update version to 1.7.1

* Remove spaces

* add spaces
…c-develop

# Conflicts:
#	console/src/main/resources/static/index.html
#	console/src/main/resources/static/js/main.js
…ync-develop

Summer ospp#13322 sync develop
[ISSUE alibaba#13744]: fix bug, register CONFIG_INFO_GRAY_WRAPPER_ROW_MAPPER
* remove unnecessary comment

* [ISSUE alibaba#12191]: add filter

* [ISSUE alibaba#12191]: add global config

* [ISSUE alibaba#12191]: fix remark

* [ISSUE alibaba#12191]: check for ai and config module

* [ISSUE alibaba#12191]: fix unit test

* [ISSUE alibaba#12191]: enhance check

* [ISSUE alibaba#12191]: modify filter

* [ISSUE alibaba#12191]: unit test

* [ISSUE alibaba#12191]: formatter

* [ISSUE alibaba#12191]: comment

* [ISSUE alibaba#12191]: modify filter

* [ISSUE alibaba#12191]: mark validation

* [ISSUE alibaba#12191]: unit test

* [ISSUE alibaba#12191]: remove comment

* [ISSUE alibaba#12191]: comment
* remove unnecessary comment

* [ISSUE alibaba#13711]: security fixes

* [ISSUE alibaba#13711]: security fixes

* [ISSUE alibaba#13711]: fit unit test
WangzJi and others added 25 commits January 14, 2026 15:50
…libaba#14101)

* feat(plugin): implement cluster-wide state synchronization

* feat(plugin): implement state synchronizer interface and remove availability monitor

  - Implement PluginStateSynchronizer interface with Raft and Standalone implementations
  - Add mode-specific conditional annotations
  - Remove PluginAvailabilityMonitor and related RPC components
… to return 400 instead of 500 (alibaba#14099)

When gRPC subscribe request contains blank serviceName or groupName,
NamingUtils.getGroupedName() throws IllegalArgumentException which
is incorrectly returned as 500 error code. This causes SDK clients
to retry infinitely and eventually become UNHEALTHY.

Add parameter validation in SubscribeServiceRequestHandler to throw
NacosException with INVALID_PARAM (400) error code before calling
getGroupedName(), allowing SDK to distinguish client errors from
server errors.

Fixes alibaba#14094
…aba#14114)

In checkChangedConfigGrayMigrateState, the gray rule comparison was missing
a negation (!), which caused the migration/sync logic to be skipped when
only the gray rule changed.
…ibaba#14115) (alibaba#14121)

When API requests fail (e.g., 403 permission error), the pagination
state was incorrectly reset to currentPage: 0. This caused subsequent
API calls to use pageNo=0, which is invalid since pagination starts
from 1.

Fixed in the following components:
- ServiceList: service list query error handler
- ClusterNodeList: cluster node list query error handler
- ConfigurationManagement: config clone/import error handlers

Signed-off-by: cxhello <caixiaohuichn@gmail.com>
* feat(ai): 添加版本参数支持到AI维护服务

- 在getAgentCard方法中添加version参数
- 实现默认方法重载以保持向后兼容性
- 更新HTTP请求参数以包含版本信息
- 修改测试用例以适应新的方法签名

* style(a2a-maintainer): 统一代码风格格式化

- 统一方法声明中的throws关键字格式
- 统一字符串参数传递中的空字符串表示方式
…ba#14117)

* feat(console): console plugin management

* feat(console): add remote handler support for plugin management
…update (alibaba#14210)

添加 componentDidUpdate 生命周期方法,监听语言变化并重新获取公告
…libaba#14307)

Add --add-opens JVM options to startup scripts for Java 9+ to resolve
JRaft reflection issues when running on JDK 17+.

Added options:
- --add-opens=java.base/java.lang=ALL-UNNAMED
- --add-opens=java.base/java.lang.reflect=ALL-UNNAMED
- --add-opens=java.base/java.util=ALL-UNNAMED

Closes alibaba#14122

Signed-off-by: cxhello <caixiaohuichn@gmail.com>
- Add config.yml to disable blank issues and guide users to proper channels
- Add anti-spam.yml GitHub Actions workflow with:
  - Keyword-based spam detection (airline names, multi-language terms)
  - New account detection (< 7 days)
  - Auto-close, label, and lock spam issues
- Remove deprecated old-issue-template.md

This addresses the recent spam bot attacks targeting the repository.

Signed-off-by: cxhello <caixiaohuichn@gmail.com>
Signed-off-by: slightsharp <slightsharp@outlook.com>
- Fix account age detection by fetching user data via GitHub API
  (issue.user.created_at is not available in webhook payload)
- Add more airline names (Swiss Air, Austrian Airlines, TAP Portugal, etc.)
- Add French spam keywords (billet, réservation, vol, etc.)
- Add phone number pattern detection (2+ phone numbers triggers spam)
- Improve logging for debugging

This fixes the issue where spam from new accounts was not being detected.

Signed-off-by: cxhello <caixiaohuichn@gmail.com>
…libaba#14401)

* ConfigRowMapperInjector 返回错误的created字段导致console展示创建时间不对

* ConfigRowMapperInjector 返回错误的created字段导致console展示创建时间不对
…ndencies (alibaba#14125)

* feat(build): activate dev profile by default for plugin dependencies

* feat: Support JDK 17+ and macOS ARM64, update dependencies
- [istio] Upgrade os-maven-plugin to 1.7.1 for macOS ARM64 support.
- [istio] Split protobuf-maven-plugin executions to prevent file locking issues.
- [bootstrap] Add dev profile to include default plugins for development.
…#14449)

ThreadLocal was removed in finally, so it never cached MessageDigest; use MessageDigest.getInstance(MD5) per call instead. Related: alibaba#14394
…tainer-client (alibaba#14450)

* fix(console): honor nacos.console.remote.server.context-path

When console is deployed standalone (remote handler), maintainer-client requests should include the server context-path. Map nacos.console.remote.server.context-path to client contextPath when building maintainer services.\n\nRelated: alibaba#14090

* fix(console): extract magic constants and add unit tests for resolveRemoteContextPath

- Extract magic strings and numbers to static final constants to fix PMD UndefineMagicConstantRule violation
- Add unit tests for resolveRemoteContextPath method covering default value, normalization, and root path cases
…aba#14454)

* fix: No exception is thrown when form parameters are too large. (alibaba#14423).

* style: Adjust some formatting. (alibaba#14423).

* style: Fix Checkstyle violation by replacing /// comments with standard Javadoc
alibaba#14463)

* refactor(config): remove deprecated v1 and v2 controllers and move to api-legacy-adapter module.

Change-Id: Ie82daa287199fec8013f83cceb7cf43213c2c48c

* chore(api-legacy-adapter): cleanup legacy API compatibility and console integration.

Change-Id: Id39f6a953f6ba176a342b7cd11410c4a0d8aa39a

* refactor(auth-plugin): remove deprecated v1 role and permission controllers.

Change-Id: I096ab1f9bb904cc9b6be3e00db696e94e4f96fd6

* chore(legacy-adapter): enhance legacy auth adapter configuration and logging.

Change-Id: I217720a1aa7f2ec350fa9150d9e4963bdbde7a20

* fix(nacos-default-plugin-all): enable default-auth-plugin dependency.

Change-Id: Id4b663cdbddf2519fb51e360822060d63ac70e64

* chore(api-legacy-adapter): add legacy API adapter module and update bootstrap dependencies.

Change-Id: I787aebe11400128797109d90b006933e3ea74033

* test(exception): fix mock method in GlobalExceptionHandlerTest.

Change-Id: I97a1a7909697b0bf2f0764967a624bac5e406bb1
…int. (alibaba#14464)

Change-Id: If53dfdb26251774c71536c2403ae0f5ba16a7bb0
… to nacos-group/nacos-api-legacy-adapter). (alibaba#14467)

Change-Id: I11e2c6659de0749866f9863355f66b23f3a3d28e
- Add DEVELOPMENT.md with setup instructions
- Add module descriptions
- Add debugging tips
- Add code style guidelines
- Add JVM tuning recommendations
- Add cluster mode setup
- Add common troubleshooting scenarios
@CLAassistant
Copy link

CLAassistant commented Mar 11, 2026

CLA assistant check
Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you all sign our Contributor License Agreement before we can accept your contribution.
23 out of 25 committers have signed the CLA.

✅ aihai
✅ KomachiSion
✅ zhan7236
✅ Sunrisea
✅ JGoP-L
✅ INotWant
✅ cxhello
✅ luoxiner
✅ QingYuanQ
✅ chunhai1127
✅ WangzJi
✅ echooymxq
✅ shichaoyuan
✅ luky116
✅ Cholesterol12138
✅ 1lck
✅ lvren1485
✅ codezkk
✅ slightsharp
✅ Zjianru
✅ youngledo
✅ FangYuan33
✅ chlch
❌ henglianghu
❌ root


root seems not to be a GitHub user. You need a GitHub account to be able to sign the CLA. If you have already a GitHub account, please add the email address used for this commit to your account.
You have signed the CLA already but the status is still pending? Let us recheck it.

@DocJlm
Copy link
Contributor Author

DocJlm commented Mar 11, 2026

Closing this PR as the changes are not aligned with project needs. Apologies for the noise.

@DocJlm DocJlm closed this Mar 11, 2026
@DocJlm DocJlm deleted the docs/improve-readme-zh branch March 11, 2026 02:35
@github-actions
Copy link

Thanks for your this PR. 🙏
Please check again for your PR changes whether contains any usage/api/configuration change such as Add new API , Add new configuration, Change default value of configuration.
If so, please add or update documents(markdown type) in docs/next/ for repository nacos-group/nacos-group.github.io


感谢您提交的PR。 🙏
请再次查看您的PR内容,确认是否包含任何使用方式/API/配置参数的变更,如:新增API新增配置参数修改默认配置等操作。
如果是,请确保在提交之前,在仓库nacos-group/nacos-group.github.io中的docs/next/目录下添加或更新文档(markdown格式)。

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.