Contributing

Relevant source files

• CONTRIBUTING.md
• Document-English.md
• Document.md
• LICENSE
• README-English.md
• README.md

This document provides guidance for developers who want to contribute to APIJSON. It covers the contribution process, bug reporting requirements, and development environment setup. APIJSON welcomes contributions in the form of code improvements, bug fixes, documentation updates, and community support.

For information about the project's development roadmap and planned features, see Development Roadmap.

---

Contribution Areas

APIJSON welcomes contributions across multiple technical areas:

Contribution Target Areas

Component	Location	Common Tasks
Request Parsing	APIJSONORM/src/main/java/apijson/orm/AbstractParser.java400-700	Add parsing logic, optimize performance
SQL Generation	APIJSONORM/src/main/java/apijson/orm/AbstractSQLConfig.java500-1500	Support new databases, add SQL features
Security Validation	APIJSONORM/src/main/java/apijson/orm/AbstractVerifier.java150-800	Enhance role checking, add validation rules
Database Execution	APIJSONORM/src/main/java/apijson/orm/AbstractSQLExecutor.java50-400	Optimize caching, improve connection handling
Spring Boot Integration	APIJSON-Java-Server/APIJSONBoot/src/main/java/apijson/demo/	Framework-specific features
Documentation	README.md Document.md wiki	Clarify usage, add examples
Test Coverage	APIJSONORM/src/test/java/	Add unit tests, integration tests
</old_str>

<new_str>

Contribution Areas

APIJSON welcomes contributions across multiple technical areas:

Contribution Target Areas

Component	Location	Common Tasks
Request Parsing	APIJSONORM/src/main/java/apijson/orm/AbstractParser.java400-700	Add parsing logic, optimize performance
SQL Generation	APIJSONORM/src/main/java/apijson/orm/AbstractSQLConfig.java500-1500	Support new databases, add SQL features
Security Validation	APIJSONORM/src/main/java/apijson/orm/AbstractVerifier.java150-800	Enhance role checking, add validation rules
Database Execution	APIJSONORM/src/main/java/apijson/orm/AbstractSQLExecutor.java50-400	Optimize caching, improve connection handling
Spring Boot Integration	APIJSON-Java-Server/APIJSONBoot/src/main/java/apijson/demo/	Framework-specific features
Documentation	README.md Document.md wiki	Clarify usage, add examples
Test Coverage	APIJSONORM/src/test/java/	Add unit tests, integration tests

Sources: APIJSONORM/src/main/java/apijson/orm/ APIJSON-Java-Server/ CONTRIBUTING.md1-95

Why Contribute Your Changes Back?

As emphasized in CONTRIBUTING.md90-95 there are critical reasons to submit Pull Requests rather than maintaining private forks:

1. Avoid Code Conflicts: Other contributors and maintainers may make incompatible changes, breaking your fork when you upgrade APIJSON versions
2. Reduce Maintenance Burden: You won't need to manually merge your changes every time APIJSON releases a new version
3. Community Review: Other developers can identify bugs, suggest improvements, and optimize your code
4. Long-term Sustainability: The project maintainers ensure your contribution remains compatible with future changes

The project strongly recommends submitting Pull Requests for any modifications to ensure compatibility and sustainability.

Sources: CONTRIBUTING.md1-95 README.md208-209

<old_str>

Required Information

The bug report template (.github/ISSUE_TEMPLATE/bug_report.yml) enforces the following required fields. Issues with missing required fields cannot be submitted.

1. APIJSON Version (Required)

Specify the exact version from your Maven/Gradle dependencies or GitHub release tag.

Important: Always test with the latest version first. The project maintains only the most recent release (see README.md208), and bug reports for old versions may be closed with a request to upgrade.

2. Database Type & Version (Required)

Specify the exact database type and version, as behavior varies significantly across versions.

Examples:

• MySQL 5.7.34
• PostgreSQL 13.4
• ClickHouse 21.8
• Oracle 19c

3. Environment Information (Required)

Provide complete environment details:

- JDK/基础库: OpenJDK 1.8.0_292
- OS/系统: Ubuntu 20.04 LTS (x86_64)
- Framework: Spring Boot 2.5.4

4. APIAuto Screenshots (Required)

This is the most critical requirement. All bug reports must include complete screenshots from APIAuto

APIAuto provides:

• Static validation: Catches syntax errors before submission
• Request visualization: Shows complete JSON structure
• Response details: Full output including error messages
• Auto-fix suggestions: Often proposes solutions

What to screenshot:

1. Complete request JSON in left panel
2. Complete response JSON in right panel
3. Any error messages or validation warnings
4. URL and HTTP method being used

Why this is required (from .github/ISSUE_TEMPLATE/bug_report.yml46-50):

"用 APIAuto 能静态检查出很多问题，甚至还有修复建议，不用浪费你我的时间"

Translation: "Using APIAuto can statically detect many problems and even provide fix suggestions, saving everyone's time."

5. Current Behavior / Problem Description (Required)

Provide a detailed description including:

• What you were attempting to accomplish
• What actually happened (unexpected behavior)
• Complete error messages (if any)
• Steps to reproduce the issue

Critical warnings from .github/ISSUE_TEMPLATE/bug_report.yml55-56:

"提 bug 请发请求和响应的【完整截屏】，没图的自行解决！"

Translation: "Bug reports must include complete request and response screenshots. Issues without screenshots will not be addressed."

"【描述不详细】 或 【文档/常见问题 已有答案】 的问题可能会被忽略！！"

Translation: "Issues with insufficient detail or that are already answered in documentation/FAQ may be ignored."

6. Expected Behavior (Optional)

Describe what you expected to happen. This helps maintainers understand if the issue is a bug or a misunderstanding of intended behavior.

Sources: .github/ISSUE_TEMPLATE/bug_report.yml1-84 CONTRIBUTING.md170-181 </old_str>

<new_str>

Commit Message Convention

APIJSON follows Conventional Commits for structured commit messages, enabling automatic CHANGELOG generation.

Message Structure

type(scope): subject

[optional body]

[optional footer]

Commit Types

Type	Description	Affected Files Example
feat	New feature	AbstractSQLConfig.java AbstractSQLExecutor.java
fix	Bug fix	AbstractVerifier.java AbstractParser.java
docs	Documentation	README.md Document.md
style	Code formatting	Any .java file
refactor	Code restructuring	AbstractParser.java AbstractObjectParser.java
perf	Performance optimization	AbstractSQLExecutor.java
test	Add/update tests	APIJSONORM/src/test/java/
chore	Build/dependencies	pom.xml build.gradle

Scope to File Mapping

Scope	Primary Files	Description
orm	APIJSONORM/src/main/java/apijson/orm/	Core ORM classes
sql	AbstractSQLConfig.java AbstractSQLExecutor.java	SQL generation/execution
security	AbstractVerifier.java	Access control
parser	AbstractParser.java AbstractObjectParser.java	Request parsing
demo	APIJSON-Java-Server/APIJSONBoot/	Demo applications

Example Commits

feat(sql): add TDengine dialect support in AbstractSQLConfig

- Implements getTDengineSQL() method
- Adds TDengine-specific date/time functions
- Updates AbstractSQLConfig.java:1200-1350

Closes #456

fix(parser): prevent NullPointerException in parseArray()

- Adds null check before calling getJSONArray()
- Location: AbstractParser.java:650-655
- Returns 400 error with descriptive message

Fixes #789

Sources: CONTRIBUTING.md154-157 APIJSONORM/src/main/java/apijson/orm/

---

Contribution Workflow

High-Level Process

For Small Changes

For minor documentation or code edits, APIJSON provides a streamlined workflow:

1. Direct Edit: Navigate to the file on GitHub (e.g., README.md or Document.md)
2. Click Edit Icon: Top-right pencil icon on the file view
3. Make Changes: Edit directly in the browser
4. Commit: Add a brief commit message and click "Commit changes"
5. Automatic PR: GitHub automatically creates a Pull Request

This workflow is ideal for:

• Typo fixes
• Documentation clarifications
• Small code corrections

Sources: CONTRIBUTING.md103-112

---

For Larger Changes

For substantial contributions (new features, refactoring, major bug fixes), follow the full Git workflow:

1. Fork and Clone

2. Add Upstream Remote

3. Keep Your Fork Synchronized

Alternatively, use the GitHub UI: Contribute → Open pull request on your fork's homepage.

4. Create a Feature Branch

5. Make Changes and Commit

Follow the commit message convention documented in CONTRIBUTING_COMMIT.md Typical format:

type(scope): subject

body (optional)

footer (optional)

Example commit messages:

• feat(orm): add support for InfluxDB 2.6+
• fix(parser): handle null values in @column correctly
• docs(readme): update installation instructions for Windows

Sources: CONTRIBUTING.md114-157

---

Commit Message Convention

APIJSON follows structured commit messages for automatic CHANGELOG generation:

Type	Description	Example
feat	New feature	feat(sql): add SQLite support
fix	Bug fix	fix(verifier): handle empty Access table
docs	Documentation	docs(api): add JOIN examples
style	Code style (formatting)	style: format AbstractParser.java
refactor	Code refactoring	refactor(executor): simplify SQL generation
perf	Performance improvement	perf(cache): optimize queryResultMap lookup
test	Add/update tests	test(parser): add unit tests for parseArray
chore	Build/tooling changes	chore: update Maven dependencies

Sources: CONTRIBUTING.md154-157

---

Code Review and Merge Process

Review Criteria

Pull Requests are reviewed for:

1. Functionality: Does the code work as intended? Are there edge cases?
2. Code Quality: Follows APIJSON conventions (see existing code patterns)
3. Performance: No performance regressions
4. Security: No SQL injection risks, proper access control
5. Documentation: Code comments, README updates if needed
6. Tests: Adequate test coverage for new features
7. Backwards Compatibility: Doesn't break existing APIs

Developer Availability

As noted in CONTRIBUTING.md8 maintainers are volunteers with limited time:

"开发者也是人，也需要工作、休息、恋爱、陪伴家人、走亲会友等，也有心情不好和身体病痛，往往没有额外的时间精力顾及一些小问题，请理解和支持"

Translation: "Developers are people too, with work, rest, relationships, and family obligations. Please be understanding and patient with response times."

Response time expectations:

• Simple PRs: 1-7 days
• Complex PRs: 1-4 weeks
• Issues: Best effort, prioritized by severity

Sources: CONTRIBUTING.md99-102 .github/ISSUE_TEMPLATE/bug_report.yml6-8

---

Bug Reporting Guidelines

APIJSON uses a structured bug report template to ensure issues contain sufficient information for diagnosis and resolution.

Required Information

The bug report template (.github/ISSUE_TEMPLATE/bug_report.yml) enforces the following required fields:

1. APIJSON Version

Specify the exact version from Maven/Gradle dependencies or GitHub release tag. Always test with the latest version first - the project maintains only the most recent release.

2. Database Type & Version

Include specific version numbers as behavior varies across database versions.

3. Environment Information

Example:

- JDK/基础库: OpenJDK 1.8.0_292
- OS/系统: Ubuntu 20.04 LTS (x86_64)

4. APIAuto Screenshots

Critical requirement: All bug reports must include complete screenshots from APIAuto showing:

• Request JSON (full structure)
• Response JSON (complete output)
• Error messages (if any)

APIAuto performs static validation and often provides fix suggestions, catching many issues before submission.

5. Problem Description

Detailed description including:

• What you were trying to do
• What actually happened
• Expected vs actual behavior
• Steps to reproduce

Important notes from .github/ISSUE_TEMPLATE/bug_report.yml55:

• Issues without screenshots may be ignored
• Maintainers focus on source code and documentation, not individual debugging
• Issues with incomplete information or poor tone may be closed/ignored

Sources: .github/ISSUE_TEMPLATE/bug_report.yml1-84 CONTRIBUTING.md170-181

---

Bug Report Validation Rules

The GitHub issue template enforces these rules:

Common Pitfalls

As warned in README.md264-266 and Document.md368:

JSON syntax is case-sensitive, comma-sensitive, space-sensitive:

• Table names start with uppercase letters: User, not user
• Keywords are exact: @column, not @Column or @ column
• No spaces in most places: "User[]":{}, not "User []": {}
• Strict syntax: Follow Document.md design specifications exactly

Examples of invalid vs valid requests:

Invalid ❌	Valid ✓	Issue
"user":{}	"User":{}	Table name must be capitalized
"@Column":"id"	"@column":"id"	Case-sensitive keyword
"User []":{}	"User[]":{}	No space before []
"id": 123	"id":123	No space before colon

Sources: README.md264-266 .github/ISSUE_TEMPLATE/bug_report.yml55

---

Development Environment Setup

Project Structure Overview

Key Source Files

Component	Path	Lines	Key Methods
Request Parser	APIJSONORM/src/main/java/apijson/orm/AbstractParser.java	~1800	parse(), parseResponse(), onObjectParse()
Security Validator	APIJSONORM/src/main/java/apijson/orm/AbstractVerifier.java	~1200	verifyAccess(), verifyRole(), verifyLogin()
SQL Generator	APIJSONORM/src/main/java/apijson/orm/AbstractSQLConfig.java	~2500	gainSQL(), gainWhereString(), combine()
SQL Executor	APIJSONORM/src/main/java/apijson/orm/AbstractSQLExecutor.java	~600	execute(), executeQuery(), getConnection()
Object Parser	APIJSONORM/src/main/java/apijson/orm/AbstractObjectParser.java	~800	parse(), onParse(), setSQLConfig()
Demo Config	APIJSON-Java-Server/APIJSONBoot/src/main/java/apijson/demo/DemoSQLConfig.java	~300	Database-specific overrides

Sources: APIJSONORM/src/main/java/apijson/orm/ APIJSON-Java-Server/APIJSONBoot/src/main/java/apijson/demo/

---

IDE Configuration

IntelliJ IDEA (Recommended)

1. Import Project:

   • File → Open → Select APIJSON/ root directory
   • Choose "Maven" when prompted
   • Wait for dependency resolution

2. Configure JDK:

   • File → Project Structure → Project
   • Set Project SDK: Java 8+ (minimum 1.8)
   • Language level: 8 - Lambdas, type annotations, etc.

3. Enable Annotation Processing:

   • Settings → Build, Execution, Deployment → Compiler → Annotation Processors
   • ✓ Enable annotation processing

4. Code Style:

   • Settings → Editor → Code Style → Java
   • Import scheme from APIJSONORM/.editorconfig if available

Eclipse

1. Import Maven Project:

   • File → Import → Maven → Existing Maven Projects
   • Root directory: APIJSON/
   • Select all modules

2. Set JDK:

   • Project Properties → Java Build Path → Libraries
   • Add Library → JRE System Library → JavaSE-1.8

3. Maven Update:

   • Right-click project → Maven → Update Project

VS Code

1. Install Extensions:

   • Java Extension Pack (Microsoft)
   • Maven for Java
   • Spring Boot Extension Pack (if working with APIJSONBoot)

2. Open Workspace:

   • File → Open Folder → Select APIJSON/
   • VS Code will detect Maven projects

3. Configure Java:

   • Command Palette (Ctrl+Shift+P) → "Java: Configure Java Runtime"
   • Set JDK 8+ path

Sources: README.md56 CONTRIBUTING.md1

---

Build Tools Setup

Maven (Primary)

APIJSON uses Maven for dependency management and builds. The project structure:

APIJSON/
├── pom.xml (parent POM)
├── APIJSONORM/
│   └── pom.xml (ORM library)
└── APIJSON-Java-Server/
    ├── APIJSONBoot/
    │   └── pom.xml (Spring Boot demo)
    └── APIJSONFinal/
        └── pom.xml (JFinal demo)

Build Commands:

Verify Installation:

Gradle (Alternative)

While Maven is the official build tool, some community projects use Gradle:

Sources: APIJSONORM/pom.xml APIJSON-Java-Server/

---

Running the Demo Server

Spring Boot Demo (Recommended)

Key files and their roles:

File	Purpose	Common Modifications
DemoApplication.java	Spring Boot entry point	Add beans, configure context
DemoController.java	HTTP endpoints (/get, /post, etc.)	Add custom endpoints
DemoSQLConfig.java	Database configuration	Override getDBUri(), getDBAccount(), add custom SQL generation
DemoParser.java	Request parsing customization	Override onVerifyLogin(), onVerifyRole()
DemoVerifier.java	Security rules	Override verifyAccess(), add custom validation
application.properties	Spring configuration	Database URL, port, logging

Example: Adding a custom database:

1. Edit DemoSQLConfig.java50-80 to override getDBUri(), getDBAccount(), getDBPassword()
2. Add JDBC driver dependency to pom.xml
3. Override database-specific SQL methods if needed

JFinal Demo

Key files: DemoConfig.java (configuration), DemoController.java (routing)

Sources: README.md276-278 APIJSON-Java-Server/APIJSONBoot/src/main/java/apijson/demo/

---

Database Setup for Testing

The APIJSON demos support multiple databases. For local testing:

MySQL (Default)

PostgreSQL

In-Memory Testing (H2)

For quick testing without external database:

Sources: README.md19-54

---

Testing Your Changes

Unit Tests

APIJSON uses standard JUnit tests. Test files are located in APIJSONORM/src/test/java/

Note: As of current version, test coverage is limited. Contributing tests is highly encouraged.

Integration Testing with APIAuto

APIAuto provides static validation and testing:

Workflow:

Example test case:

What to test:

Feature	Test Method	Key Classes Involved
Basic CRUD	GET, POST, PUT, DELETE requests	AbstractParser AbstractSQLExecutor
Array queries	"User[]":{"count":10}	AbstractParser
JOIN operations	"join":"</User"	AbstractSQLConfig
Reference queries	"id@":"/Moment/userId"	AbstractObjectParser
Remote functions	"isPraised()":"isContain(...)"	AbstractFunctionParser
Access control	Test with different @role values	AbstractVerifier
SQL injection	Try malicious input	AbstractVerifier

Sources: README.md120-159 Document.md69-85 APIJSONORM/src/main/java/apijson/orm/

---

Community and Recognition

Communication Channels

Channel	Purpose	Typical Response
GitHub Issues	Bug reports, feature requests	1-7 days
GitHub Pull Requests	Code contributions	1-4 weeks for review
GitHub Discussions	Questions, ideas	Community-driven

Contributor Recognition

Contributors are acknowledged in:

• CONTRIBUTING.md6-78 - Full list with profiles and affiliations
• README.md376-437 - Contributor avatars and company logos
• GitHub Contributors graph

Notable contributor categories:

• 6+ Tencent engineers (core team)
• Engineers from Microsoft, Alibaba Cloud, ByteDance, NetEase, Zoom, YTO Express
• Students from UC Berkeley, SUSTech
• Authors of language implementations (apijson-go APIJSON.NET apijson-php)

Sources: CONTRIBUTING.md6-78 README.md376-437

---

Contributor Achievements

APIJSON recognizes significant contributions:

Hall of Fame

Top contributors as of CONTRIBUTING.md79-84:

Contributor	Affiliation	Stats	Key Contributions
TommyLemon	Tencent	Project founder	Core architecture, APIJSON-Demo, apijson-framework, apijson-router
cloudAndMonkey	-	11 commits 1,496+ / 845-	Redis, Elasticsearch, Kafka, Lua support; multiple demos
justinfengchen	-	6 commits 3,130+ additions	Major feature additions
ruoranw	Los Angeles, USA	18 commits 328+ / 520-	APIJSONdocs documentation project
Zerounary	-	6 commits 1,104+ additions	APIJSONParser frontend library
sunxiaoguang	Zhihu	Core contributions	Infrastructure architecture expertise
caohao-go	Tencent	Multiple commits	Former Huawei/Hengsheng/WPS/360 engineer

Contributor Companies

APIJSON has received contributions from engineers at:

• 6 Tencent engineers (including core team)
• 1 Microsoft engineer
• 1 Alibaba Cloud engineer
• 1 ByteDance engineer (also contributed apijson-db2)
• 1 NetEase engineer (APIJSON-DOC project)
• 1 Zoom engineer
• 1 YTO Express engineer
• 1 Zhihu architect
• 1 Zhilian engineer
• Academic contributors: UC Berkeley, SUSTech students

Recognition

Contributors are acknowledged in:

1. CONTRIBUTING.md - Full contributor list with profiles
2. README.md - Contributor avatars and company logos
3. GitHub Contributors Graph - Automatic GitHub tracking
4. Project Documentation - Citations in wiki and docs

Sources: CONTRIBUTING.md6-88 README.md376-437

---

Next Steps

1. Read the Documentation: Review Document.md for API specifications
2. Explore the Codebase: Start with APIJSONORM/src/main/java/apijson/orm/AbstractParser.java
3. Check Open Issues: Look for issues labeled good first issue or help wanted
4. Join the Community: Introduce yourself in Discussions
5. Make Your First Contribution: Start with documentation or small bug fixes

Useful Resources

• APIJSON Protocol Specification - JSON transmission protocol details
• Core ORM Architecture - Understanding the engine internals
• Security and Access Control - RBAC and validation system
• Database Support - Multi-database configuration

Sources: README.md1-516 CONTRIBUTING.md1-182 Document.md1-25