Contributing to WebDAV Server / WebDAV 服务器贡献指南

English Version

Thank you for your interest in contributing to the WebDAV Server project! This document provides guidelines and information to help you contribute effectively.

Getting Started
Development Workflow
Coding Standards
Testing Requirements
Commit Guidelines
Pull Request Process
Feature Request Process
Bug Report Process

Getting Started

Prerequisites

C11 compatible compiler (GCC ≥ 6.0 or Clang ≥ 6.0)
Make
CMake 3.10+ (optional, for modern builds)
Git

Quick Setup

# Clone the repository
git clone https://github.com/yourusername/webdav-server.git
cd webdav-server

# Build the project
make

# Run tests
make test
./webdav_server --test

# Run with sample data
./webdav_server -p 8080 --db test.db &

Development Workflow

1. Create a Branch

git checkout -b feature/your-feature-name
# or
git checkout -b fix/your-bug-description

2. Make Changes

Follow the Coding Standards
Add tests for new features
Update documentation as needed

3. Test Locally

# Standard build
make clean && make

# Cosmopolitan build (cross-platform)
make clean && make cosmo

# Run all tests
make test
./webdav_server --test

# Run litmus compatibility tests
./run_litmus.sh

# Test binary file handling
./test_webdav_operations.sh

# Test Unicode filenames
./unicode_test.sh

4. Commit Changes

See Commit Guidelines

5. Push and Create PR

git push origin your-branch-name
# Then create a Pull Request on GitHub

Coding Standards

C Code Style

K&R Style, 4-Space Indentation

/* Good */
void example_function(int param) {
    if (condition) {
        do_something();
    }
}

/* Bad - No tabs, 2 spaces, or Allman style */
void example_function(int param)
{
    if (condition) {
        do_something();
    }
}

Naming Conventions

/* Functions: lowercase with underscores */
void webdav_handle_request(void);

/* Variables: lowercase with underscores */
int request_count;

/* Constants: UPPERCASE_WITH_UNDERSCORES */
#define MAX_BUFFER_SIZE 8192

/* Types: lowercase_with_underscore_t */
typedef struct storage_engine storage_engine_t;

/* Macros: UPPERCASE */
#define ENSURE_SPACE(ptr, current_size, needed)

Formatting Rules

Indentation: 4 spaces (NO tabs)
Line Length: Maximum 100 characters
Braces: K&R style
Pointer Declaration: char *ptr (not char* ptr or char * ptr)
Spacing: if (condition) not if(condition)

Documentation Style

/**
 * webdav_propfind - Handle PROPFIND requests
 * @req: HTTP request structure
 * @storage: Storage engine
 * @path: Resource path
 * @response: Buffer for response
 *
 * Generates XML response with resource properties according to PROPFIND
 * depth header. SupportsDepth: 0, 1, infinity with default of 1.
 *
 * Returns: HTTP status code
 */
int webdav_propfind(http_request_t *req, storage_engine_t *storage,
                    const char *path, http_response_t *response);

Error Handling

/* Use explicit error codes */
#define WEBDAV_SUCCESS 0
#define WEBDAV_ERROR_INVALID_PATH 1
#define WEBDAV_ERROR_STORAGE 2

/* Check return values */
int result = storage_put(engine, path, data, size);
if (result != WEBDAV_SUCCESS) {
    log_error("Storage failed: %d", result);
    return WEBDAV_ERROR_STORAGE;
}

Memory Management

/* Always allocate with error checking */
char *buffer = malloc(size);
if (!buffer) {
    return WEBDAV_ERROR内存;
}

/* Always free in reverse order */
free(decoded_names[i]);
free(response_buffer);

String Handling

/* Use strnlen for safety */
size_t len = strnlen(input, MAX_INPUT_SIZE);

/* Avoid strcpy, use strncpy or custom functions */
strncpy(dest, src, sizeof(dest) - 1);
dest[sizeof(dest) - 1] = '\0';

/* For Cosmopolitan compatibility - NO sprintf, use snprintf */
snprintf(buffer, sizeof(buffer), "%s/%s", path, filename);

Cosmopolitan Compatibility

The project supports Cosmopolitan for cross-platform builds. Additional constraints:

No standard library assumptions: Use only POSIX functions
Avoid scanf family: Use manual parsing for JSON/XML
Static linking: Reminder for Cosmopolitan builds
Testing: All features must work with make cosmo

Memory Safety

/* Bounds checking */
if (index >= array_size) {
    return ERROR_OUT_OF_BOUNDS;
}

/* Null pointer checks */
if (!ptr) {
    return ERROR_NULL_POINTER;
}

/* Buffer overflow prevention */
size_t needed = strlen(src) + 1;
if (needed > buffer_size) {
    return ERROR_BUFFER_TOO_SMALL;
}

Thread Safety

/* Current design: Each request is handled in separate thread */
/* Ensure no global mutable state */

/* If you add global state, use mutex */
pthread_mutex_t my_lock = PTHREAD_MUTEX_INITIALIZER;

void critical_section(void) {
    pthread_mutex_lock(&my_lock);
    /* Access shared data */
    pthread_mutex_unlock(&my_lock);
}

Testing Requirements

Before Any Commit

✅ Standard build passes: make clean && make
✅ Cosmopolitan build passes: make clean && make cosmo
✅ All built-in tests pass: ./webdav_server --test
✅ Litmus tests pass: All 66/66 tests
✅ Binary file test: 100KB+ file uploads/downloads work
✅ Unicode test: Chinese filenames work correctly
✅ Large directory test: 150+ files without crashes

New Feature Testing

For new features, also verify:

# 1. Test with real clients
# - Windows Explorer
# - macOS Finder
# - cadaver CLI
# - davfs2

# 2. Test edge cases
# - Empty files
# - Very large files (> 10MB)
# - Special characters in filenames
# - Deep directory nesting
# - Concurrent access

# 3. Test PROPPATCH operations
./test_proppatch.sh

# 4. Test all WebDAV methods
curl -X OPTIONS http://localhost:8080/
# Should return: Allow: OPTIONS, GET, HEAD, PUT, DELETE, MKCOL, COPY, MOVE, PROPFIND, PROPPATCH, LOCK, UNLOCK

Performance Testing

# Stress test with many files
./stress_test.sh

# Benchmark memory usage
valgrind --tool=massif ./webdav_server -p 8080 --db test.db

Commit Guidelines

Commit Message Format

<type>: <description>

[optional body]

[optional footer]

Types

feat: New feature
fix: Bug fix
docs: Documentation changes
test: Test additions/changes
refactor: Code refactoring
perf: Performance improvements
build: Build system changes
ci: CI/CD changes
chore: Maintenance

Examples

feat: add support for custom property namespaces

PROPPATCH now supports properties with custom namespaces like:
<D:prop><custom:status>approved</custom:status></D:prop>

Fixes issue with litmus test 'propnspace'

Closes #12

fix: resolve binary file truncation with 100+ files

Dynamic XML buffer allocation in webdav_propfind() replaces
fixed 32KB buffer that caused crashes with large directories.

- Changed char buffer[32768] to dynamic malloc()
- Added automatic resizing with ENSURE_SPACE macro
- Tests: Handle 150 files / 86KB XML response

Fixes #45

fix: prevent duplicate folder listings

Added duplicate check in storage_list_collection() for direct
child files/directories to prevent showing duplicates in
large directory PROPFIND responses.

Test: 150 files now show correctly as 150 entries

Commit Message Rules

Subject line: ≤ 72 characters
Body: Wrap at 80 characters
Use imperative: "Add feature" not "Added feature"
Reference issues: Use Fixes #123 or Closes #123
Sign-off: Optional Signed-off-by: Name <email>

Pull Request Process

PR Template

## Description

Brief description of changes

## Type of Change

- [ ] Bug fix (non-breaking change)
- [ ] New feature (non-breaking change)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] Documentation update

## Testing

- [ ] Standard build: `make clean && make`
- [ ] Cosmopolitan build: `make clean && make cosmo`
- [ ] Built-in tests: `./webdav_server --test`
- [ ] Litmus tests: All 66/66 pass
- [ ] Binary file test works
- [ ] Unicode filename test works

## Checklist

- [ ] Code follows project style guidelines
- [ ] Tests have been added/updated
- [ ] Documentation has been updated
- [ ] All tests pass locally

## Related Issues

Fixes #[issue number]

PR Review Process

Automated checks: CI runs tests on Linux, macOS, Windows
Code review: Maintainers review for:
- Style compliance
- Test coverage
- Security implications
- Cosmopolitan compatibility
Manual testing: Required for new features
Approval: 1 required approval from maintainer

Branch Protection

main branch is protected
Requires passing CI checks
Requires 1+ approval
Requires rebase/squash on merge

Feature Request Process

How to Request a Feature

Check existing issues: Search for similar requests
Create new issue: Use "Feature Request" template
Describe clearly:
- Problem statement
- Proposed solution
- Use cases
- Alternative approaches considered

Feature Request Template

## Problem Statement

[What problem does this solve?]

## Proposed Solution

[How would you implement this?]

## Use Cases

- [Use case 1]
- [Use case 2]

## Alternatives Considered

- Alternative 1
- Alternative 2

## Additional Context

[Any other relevant information]

Bug Report Process

Bug Report Template

## Environment

- OS: [e.g., Ubuntu 22.04]
- Version: [e.g., v1.0.0 or commit hash]
- Build: [e.g., make or make cosmo]
- Database: [e.g., UnQLite]

## Expected Behavior

[What should happen?]

## Actual Behavior

[What actually happens?]

## Steps to Reproduce

1. [Step 1]
2. [Step 2]
3. [Step 3]

## Minimal Reproduction

```bash
# Commands to reproduce the issue
./webdav_server -p 8080 --db test.db
curl -X MKCOL http://localhost:8080/test

Logs/Screenshots

[Any relevant output, errors, or screenshots]

Additional Context

[Anything else relevant?]


## Getting Help

- **Documentation**: See README.md
- **GitHub Issues**: For bugs and feature requests
- **Discussions**: For questions and brainstorming

## Recognition

Contributors will be recognized in:
- Releases notes
- README.md (Contributors section)
- GitHub Sponsors page (if applicable)

## License

By contributing, you agree that your contributions will be licensed under the MIT License.

---

## <a id="chinese"></a>中文版本

感谢您对WebDAV服务器项目的兴趣！本文档提供贡献指南和信息，帮助您有效地进行贡献。

### 目录
- [开始之前](#开始之前)
- [开发工作流](#开发工作流)
- [代码规范](#代码规范)
- [测试要求](#测试要求)
- [提交规范](#提交规范)
- [拉取请求流程](#拉取请求流程)
- [功能请求流程](#功能请求流程)
- [错误报告流程](#错误报告流程)

### <a id="开始之前"></a>开始之前

**前提条件:**
- C11兼容编译器 (GCC ≥ 6.0 或 Clang ≥ 6.0)
- Make构建工具
- Git版本控制

**快速设置:**
```bash
# 克隆仓库
git clone https://github.com/yourusername/webdav-server.git
cd webdav-server

# 构建项目
make

# 运行测试
make test
./webdav_server --test

开发工作流

1. 创建分支

git checkout -b feature/你的功能名称
# 或
git checkout -b fix/你的修复描述

2. 进行修改

遵循代码规范
为新功能添加测试
根据需要更新文档

3. 本地测试

# 标准构建
make clean && make

# Cosmopolitan构建
make clean && make cosmo

# 运行所有测试
make test
./webdav_server --test

# 运行litmus兼容性测试
./run_litmus.sh

4. 提交更改

git add .
git commit -m "feat: 添加新功能"
git push origin your-branch-name

5. 创建拉取请求 在GitHub上创建Pull Request

代码规范

K&R风格，4空格缩进

/* 正确 */
void example_function(int param) {
    if (condition) {
        do_something();
    }
}

/* 错误 - 使用制表符或2空格 */
void example_function(int param)
{
    if (condition) {
        do_something();
    }
}

命名规范:

函数: lowercase_with_underscores
变量: lowercase_with_underscores
常量: UPPERCASE_WITH_UNDERSCORES
类型: lowercase_with_underscores_t
宏: UPPERCASE

行长度: 最多100字符 指针声明: char *ptr (不是 char* ptr)

测试要求

提交前必须验证:

✅ make clean && make - 标准构建成功
✅ make clean && make cosmo - Cosmopolitan构建成功
✅ ./webdav_server --test - 所有测试通过
✅ ./webdav_server.com --test - Cosmopolitan测试通过
✅ 中文文件名测试
✅ 所有WebDAV方法测试
✅ PROPPATCH操作测试

提交规范

提交信息格式:

<类型>: <描述>

[可选正文]

[可选脚注]

类型:

feat: 新功能
fix: 错误修复
docs: 文档更改
test: 测试添加/更改
refactor: 代码重构
perf: 性能改进
build: 构建系统更改
ci: CI/CD更改
chore: 维护

示例:

fix: 解决100+文件时的XML缓冲区溢出

在webdav_propfind()中将固定32KB缓冲区改为动态分配。
使用ENSURE_SPACE宏自动扩展缓冲区。

- 测试: 可处理150个文件/86KB XML响应
- 修复: #45

拉取请求流程

PR模板:

## 描述
简要描述更改

## 更改类型
- [ ] 错误修复 (非破坏性)
- [ ] 新功能 (非破坏性)
- [ ] 破坏性更改
- [ ] 文档更新

## 测试
- [ ] 标准构建: `make clean && make`
- [ ] Cosmopolitan构建: `make clean && make cosmo`
- [ ] 内置测试: `./webdav_server --test`
- [ ] Litmus测试: 全部66/66通过

## 相关Issue
Fixes #123

审查流程:

自动化检查: CI在Linux, macOS, Windows上运行测试
代码审查: 维护者检查风格、测试覆盖、安全性
手动测试: 新功能必须手动测试
批准: 需要1位维护者批准

功能请求流程

创建功能请求:

检查现有issue
创建新issue，使用"功能请求"模板
清晰描述:
- 问题陈述
- 拟议解决方案
- 使用场景
- 替代方案考虑

错误报告流程

错误报告模板:

## 环境
- OS: [例如: Ubuntu 22.04]
- 版本: [例如: v1.0.0]
- 构建: [例如: make 或 make cosmo]

## 预期行为
[应该发生什么？]

## 实际行为
[实际发生了什么？]

## 复现步骤
1. [步骤1]
2. [步骤2]
3. [步骤3]

## 附加信息
[任何其他相关信息]

获取帮助

文档: 查看 README.md 或 README_ZH.md
GitHub Issues: 用于bug和功能请求
讨论区: 用于问题和头脑风暴

认可

贡献者将在以下位置获得认可:

Release说明
README.md (贡献者部分)
GitHub Sponsors页面 (如适用)

许可证

通过贡献，您同意您的贡献将根据MIT许可证授权。

FilesExpand file tree

CONTRIBUTING.md

Latest commit

History