Contributing Guidelines
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The libfastjson project provides a high-performance, small-footprint JSON handling library. Contributing to this project requires adherence to specific code quality standards, automated testing requirements, and structured release procedures. As a fork of json-c, the project focuses on speed and essential functionality rather than 100% standard compliance.
The contribution process is governed by Continuous Integration (CI) platforms that validate code style and functional integrity. All modifications, whether bug fixes or new features, must be accompanied by appropriate tests to be integrated into the main codebase.
Sources: README.md:1-12, CONTRIBUTING.md:1-10
Continuous Integration and Testing
The project employs a mandatory CI pipeline to maintain code quality. Every Pull Request (PR) must successfully pass all automated tests before it can be merged.
Testbench Requirements
Contributors are expected to add related tests to the testbench when providing new functionality or fixing bugs. While exceptions exist for hard-to-test scenarios, the absence of tests is generally grounds for rejecting a merge.
Sources: CONTRIBUTING.md:1-15
Automated Verification Flow
The CI system utilizes specialized scripts to verify merges and code integrity. The try_merge.sh script automates the process of testing a PR against the current master branch.
The diagram above illustrates the automated merge testing logic used by the project's buildbots.
Sources: CI/try_merge.sh:1-32
Test Infrastructure
The project uses a common set of shell functions for output verification. The run_output_test function is the primary mechanism for comparing program output against expected results.
| Component | Description |
|---|---|
run_output_test | Compares execution output against .expected files. |
valgrind | Used during tests to detect memory leaks and errors. |
VERBOSE | Environment variable to enable detailed test output. |
CMP | Utility used for byte-to-byte comparison of results. |
Sources: tests/test-defs.sh:58-115
Code Style Standards
Code style is enforced via automated checks during CI runs. Currently, the project uses a specific style checker maintained by the rsyslog team.
Minimal Style Requirements
- Indentation: Must be done using TAB characters, not spaces.
- Whitespace: Trailing whitespace at the end of lines is strictly prohibited.
- Line Length: The style checker validates files against a maximum length, typically 130 characters.
Sources: CONTRIBUTING.md:20-29, CI/check_codestyle.sh:7
Style Validation Logic
The project clones the rsyslog/codestyle repository to compile and run the stylecheck utility against all .c and .h files in the repository.
Sources: CI/check_codestyle.sh:1-7
Development and Build Process
Contributors must be able to build and verify the project locally using the standard autotools chain.
Build Sequence
- Initialize build environment:
sh autogen.sh - Configure system:
./configure - Compile:
make - Verify:
make check
Sources: README.md:32-50
Release Procedures
The project follows a rigorous checklist for preparing and finalizing releases. This process ensures version consistency across headers, documentation, and build files.
Release Execution Steps
The release process involves branching, version updates, and documentation generation.
Sources: RELEASE_CHECKLIST.txt:1-60
Versioning and Checksums
Following a release, the project updates the master branch to a "newer" version (e.g., ${release}.99) to indicate post-release development. Checksums (SHA256 and MD5) are generated for the release tarballs and published on the project wiki to ensure artifact integrity.
Sources: RELEASE_CHECKLIST.txt:83-116
Summary
Contributing to libfastjson requires a commitment to performance and stability. By adhering to the mandatory CI testing, tab-based indentation, and the structured release checklist, contributors help maintain the library's utility as a fast and lightweight JSON processing solution for the rsyslog ecosystem and beyond.