Contributing to dross¶

Thank you for your interest in contributing to dross! This guide will help you get started.

Getting Started¶

Fork the repository on GitHub

Clone your fork locally:

git clone https://github.com/YOUR_USERNAME/dross.git
cd dross

Add the upstream repository:

git remote add upstream https://github.com/skipbit/dross.git
git fetch upstream

Create a new branch for your work:

git checkout -b feature/your-feature-name

Development Setup¶

Build Requirements¶

C++23 compatible compiler (GCC 13+, Clang 16+, MSVC 2022+)
CMake 3.20 or later
Git

Building the Project¶

# Debug build (recommended for development)
cmake -S . -B build/debug -DCMAKE_BUILD_TYPE=Debug
cmake --build build/debug

# Run tests
cd build/debug && ctest -V

Development Tools¶

The project generates compile_commands.json for IDE support:

# The file is generated automatically in the build directory
ls build/debug/compile_commands.json

Code Style¶

Please follow the coding style guidelines in CODINGSTYLE.md:

General Rules¶

Use C++23 features where appropriate
All code must be in the dross namespace
Use 4 spaces for indentation (no tabs)
Target 80 character line length (flexible for readability)

Naming Conventions¶

Classes/Structs: lowercase (e.g., value, string)
Functions: lower_snake_case (e.g., to_string())
Variables: lower_snake_case (e.g., my_variable)
Private members: _snake_case (e.g., _impl)
Constants: kCamelCase (e.g., kDefaultSize)
Concepts: snake_case_type (e.g., string_type)

Code Organization¶

Separate headers (.h) and implementation (.cpp)
Use Pimpl idiom for ABI stability in public classes
No exceptions - use std::optional and std::expected
Apply const, constexpr, and noexcept appropriately

Testing¶

All contributions must include appropriate tests:

Writing Tests¶

Tests use GoogleTest and are located in the test/ directory:

#include <gtest/gtest.h>
#include <dross/value.h>

TEST(ValueTest, DefaultConstruction) {
    dross::value v;
    EXPECT_TRUE(v.is_null());
}

TEST(ValueTest, NumberConstruction) {
    dross::value v(42);
    EXPECT_TRUE(v.is_number());
    EXPECT_EQ(v.as_number(), dross::number(42));
}

Running Tests¶

# Run all tests
cd build/debug && ctest

# Run specific test
./build/debug/dross_test --gtest_filter="ValueTest.*"

# Run with detailed output
./build/debug/dross_test --gtest_list_tests

Test Coverage¶

Aim for:

100% coverage of public APIs
>90% overall code coverage
Test both success and error paths
Include edge cases and boundary conditions

Documentation¶

API Documentation¶

Use Doxygen-style comments for all public APIs:

/**
 * @brief Converts the value to a string representation.
 *
 * @return String representation of the value
 * @note Never throws
 */
string to_string() const noexcept;

Documentation Building¶

# Build documentation locally
cd docs
make clean
make html-with-doxygen

# View documentation
open _build/html/index.html

Submitting Changes¶

Pull Request Process¶

Ensure your code follows the style guide
Add tests for new functionality
Update documentation as needed
Ensure all tests pass

Commit your changes:

git add .
git commit -m "feat: add new feature

Detailed description of what changed and why"

Push to your fork:

git push origin feature/your-feature-name

Create a pull request on GitHub

Commit Message Format¶

Use conventional commits format:

feat: New feature
fix: Bug fix
docs: Documentation changes
test: Test additions or modifications
refactor: Code refactoring
style: Code style changes
perf: Performance improvements
chore: Build system or auxiliary tool changes

Pull Request Guidelines¶

Keep PRs focused on a single feature or fix
Provide a clear description of the changes
Reference any related issues
Respond to review feedback promptly
Ensure CI passes before requesting review

Reporting Issues¶

Bug Reports¶

When reporting bugs, please include:

dross version or commit hash
Compiler and version
Operating system
Minimal reproducible example
Expected vs actual behavior
Any error messages or logs

Feature Requests¶

For feature requests, please describe:

The problem you’re trying to solve
Your proposed solution
Alternative solutions considered
Any API design considerations

Community¶

GitHub Issues: Bug reports and feature requests
GitHub Discussions: General questions and discussions
Pull Requests: Code contributions

Code of Conduct¶

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

License¶

By contributing to dross, you agree that your contributions will be licensed under the same MIT License that covers the project.

Thank You!¶

Your contributions help make dross better for everyone. We appreciate your time and effort in improving the library!