From 5c83c398de7f06cb2f0ab6108f13121b29282315 Mon Sep 17 00:00:00 2001 From: RAprogramm Date: Sun, 19 Oct 2025 07:21:18 +0700 Subject: [PATCH] #6 docs: add comprehensive project documentation - Add CHANGELOG.md with git-cliff auto-generation - Add cliff.toml for changelog configuration - Add CONTRIBUTING.md with development guidelines - Add SECURITY.md with security policy - Update REUSE.toml to include new documentation files CHANGELOG.md: - Auto-generated from git commits using git-cliff - Follows Keep a Changelog format - Categorizes changes (feat, fix, chore, docs) - Based on Conventional Commits standard CONTRIBUTING.md: - Development setup instructions - Code style guidelines (rustfmt, clippy) - Testing requirements (95%+ coverage) - Pull request process - Conventional commit format - Edition 2024 and Rust 1.90+ requirements SECURITY.md: - Vulnerability reporting process - Supported versions table - Response timeline (48h initial, 7-30d fix) - Security best practices - Disclosure policy cliff.toml: - Professional changelog generation config - Conventional commits parsing - Semantic versioning support - Keep a Changelog format Benefits: - Professional open-source project appearance - Clear contribution guidelines for developers - Transparent security policy - Automated changelog generation - REUSE 3.3 compliant --- CHANGELOG.md | 22 ++++++ CONTRIBUTING.md | 205 ++++++++++++++++++++++++++++++++++++++++++++++++ REUSE.toml | 2 +- SECURITY.md | 146 ++++++++++++++++++++++++++++++++++ cliff.toml | 58 ++++++++++++++ 5 files changed, 432 insertions(+), 1 deletion(-) create mode 100644 CHANGELOG.md create mode 100644 CONTRIBUTING.md create mode 100644 SECURITY.md create mode 100644 cliff.toml diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..838a792 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,22 @@ +# Changelog + +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [unreleased] + +### Miscellaneous Tasks + +- Update benchmark results [skip ci] + +## [0.1.0] - 2025-10-18 + +### Miscellaneous Tasks + +- Update benchmark results [skip ci] +- Update benchmark results [skip ci] +- Update benchmark results [skip ci] + + diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..f6c67f1 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,205 @@ + + +# Contributing to cstring-array + +Thank you for your interest in contributing to cstring-array! This document provides guidelines and instructions for contributing to this project. + +## Development Setup + +### Prerequisites + +- Rust 1.90 or later (Edition 2024) +- cargo, rustfmt, clippy +- Git + +### Getting Started + +1. Fork the repository on GitHub +2. Clone your fork: + ```bash + git clone https://github.com/YOUR_USERNAME/cstring-array.git + cd cstring-array + ``` +3. Add upstream remote: + ```bash + git remote add upstream https://github.com/RAprogramm/cstring-array.git + ``` +4. Install development dependencies: + ```bash + cargo build --all-features + cargo test --all-features + ``` + +## Code Style + +This project follows strict coding standards: + +### Rust Edition and Version + +- **Edition**: 2024 +- **Minimum Rust Version**: 1.90 + +### Code Formatting + +- Use `rustfmt` for all Rust code +- Run before committing: + ```bash + cargo +nightly fmt + ``` + +### Linting + +- All code must pass clippy with no warnings: + ```bash + cargo clippy --all-targets --all-features -- -D warnings + ``` + +### Documentation + +- All public APIs must have documentation comments (`///`) +- Module-level documentation is required +- Use `::` only in imports +- Avoid inline comments except for `///` doc comments + +### Code Structure + +- Follow RAII patterns for resource management +- Prefer zero-copy operations where possible +- Write safe code - `unsafe` requires detailed justification + +## Testing Requirements + +### Test Coverage + +- Maintain 95%+ test coverage +- All new features must include tests +- Bug fixes must include regression tests + +### Running Tests + +```bash +# Run all tests +cargo test --all-features + +# Run tests with coverage +cargo install cargo-llvm-cov +cargo llvm-cov --all-features + +# Run doctests +cargo test --all-features --doc + +# Run benchmarks +cargo bench +``` + +### Test Organization + +- Unit tests in module files (mod tests) +- Integration tests in tests/ directory +- Doctests for usage examples +- Benchmarks in benches/ directory + +## Pull Request Process + +### Before Submitting + +1. Update to latest upstream: + ```bash + git fetch upstream + git rebase upstream/main + ``` + +2. Run full test suite: + ```bash + cargo +nightly fmt -- --check + cargo clippy --all-targets --all-features -- -D warnings + cargo test --all-features + cargo build --release --all-features + ``` + +3. Update documentation if needed +4. Update CHANGELOG.md (auto-generated from commits) + +### Commit Messages + +Follow conventional commits format: + +- `feat: add new feature` - New feature +- `fix: resolve bug` - Bug fix +- `docs: update documentation` - Documentation changes +- `perf: improve performance` - Performance improvements +- `refactor: restructure code` - Code refactoring +- `test: add tests` - Test additions +- `chore: maintenance task` - Chores and maintenance + +### PR Guidelines + +1. Create a new branch for your changes: + ```bash + git checkout -b feature/your-feature-name + ``` + +2. Make your changes following the code style above + +3. Commit with conventional commit messages + +4. Push to your fork: + ```bash + git push origin feature/your-feature-name + ``` + +5. Create a pull request on GitHub with: + - Clear description of changes + - Reference to related issues + - Screenshots/examples if applicable + +### CI/CD Pipeline + +All PRs must pass: +- Formatting check (rustfmt) +- Linting (clippy) +- REUSE compliance +- Security audit (cargo audit) +- Tests (Linux, macOS, Windows × stable, beta, nightly) +- Coverage check +- Documentation build + +## Licensing + +This project uses: +- **Code**: MIT License +- **Configuration files**: CC0-1.0 (Public Domain) + +All contributions must comply with [REUSE Specification 3.3](https://reuse.software/spec/). + +### Adding License Headers + +For new Rust files: +```rust +// SPDX-FileCopyrightText: 2025 YourName +// SPDX-License-Identifier: MIT +``` + +For new config files: +```yaml +# SPDX-FileCopyrightText: 2025 YourName +# SPDX-License-Identifier: CC0-1.0 +``` + +## Getting Help + +- Open an issue for bugs or feature requests +- Check existing issues and discussions +- Read the documentation at [docs.rs/cstring-array](https://docs.rs/cstring-array) + +## Code of Conduct + +- Be respectful and inclusive +- Provide constructive feedback +- Focus on technical merits +- Welcome newcomers + +Thank you for contributing to cstring-array! diff --git a/REUSE.toml b/REUSE.toml index 2f06851..87f2518 100644 --- a/REUSE.toml +++ b/REUSE.toml @@ -4,7 +4,7 @@ SPDX-PackageSupplier = "RAprogramm " SPDX-PackageDownloadLocation = "https://github.com/RAprogramm/cstring-array" [[annotations]] -path = ["Cargo.toml", "Cargo.lock", ".gitignore", ".rustfmt.toml", "REUSE.toml", "codecov.yml", ".config/nextest.toml"] +path = ["Cargo.toml", "Cargo.lock", ".gitignore", ".rustfmt.toml", "REUSE.toml", "codecov.yml", ".config/nextest.toml", "cliff.toml", "CHANGELOG.md", "CONTRIBUTING.md", "SECURITY.md"] precedence = "aggregate" SPDX-FileCopyrightText = "2025 RAprogramm " SPDX-License-Identifier = "CC0-1.0" diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..31077f8 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,146 @@ + + +# Security Policy + +## Supported Versions + +We actively support the following versions of cstring-array with security updates: + +| Version | Supported | +| ------- | ------------------ | +| 0.1.x | :white_check_mark: | +| < 0.1 | :x: | + +## Reporting a Vulnerability + +We take the security of cstring-array seriously. If you discover a security vulnerability, please follow these steps: + +### 1. Do NOT Open a Public Issue + +Please **do not** open a public GitHub issue for security vulnerabilities, as this could put users at risk before a fix is available. + +### 2. Contact Us Privately + +Report security vulnerabilities by emailing: + +**Email**: andrey.rozanov.vl@gmail.com + +Include in your report: +- Description of the vulnerability +- Steps to reproduce the issue +- Potential impact +- Suggested fix (if available) +- Your contact information + +### 3. Response Timeline + +- **Initial Response**: Within 48 hours +- **Vulnerability Assessment**: Within 7 days +- **Fix Timeline**: Depends on severity + - Critical: Within 7 days + - High: Within 14 days + - Medium: Within 30 days + - Low: Next release + +### 4. Disclosure Policy + +We follow coordinated vulnerability disclosure: + +1. We will confirm receipt of your report +2. We will investigate and assess the vulnerability +3. We will develop and test a fix +4. We will release a security update +5. We will publicly disclose the vulnerability after the fix is released + +You will receive credit for the discovery unless you prefer to remain anonymous. + +## Security Best Practices + +When using cstring-array: + +### Safe Usage + +- Always handle `Result` types properly +- Validate input strings for null bytes before conversion +- Use RAII pattern - arrays are automatically cleaned up +- Avoid manual pointer manipulation + +### Unsafe Code + +This crate uses `unsafe` code for FFI interoperability: +- All unsafe blocks are carefully reviewed +- Safety invariants are documented +- Pointer validity is guaranteed through RAII + +### Dependencies + +- This crate has **zero runtime dependencies** +- Development dependencies are audited regularly +- CI/CD pipeline includes `cargo audit` security checks + +## Security Features + +### Memory Safety + +- RAII-based lifetime management prevents dangling pointers +- Null termination guaranteed for C compatibility +- Automatic cleanup prevents memory leaks +- Safe abstractions over raw pointers + +### Testing + +- 95%+ test coverage +- Integration tests for FFI scenarios +- Property-based testing for edge cases +- Cross-platform testing (Linux, macOS, Windows) + +### CI/CD Security + +Our continuous integration includes: +- Dependency vulnerability scanning (`cargo audit`) +- REUSE compliance checking +- Cross-platform testing +- Code coverage analysis + +## Known Limitations + +### Not Thread-Safe by Design + +`CStringArray` is `Send + Sync` but requires external synchronization for concurrent access. This is by design for FFI compatibility. + +### Interior Null Bytes + +Creating arrays from strings containing null bytes (`\0`) will return an error. This is expected behavior for C string compatibility. + +## Security Updates + +Security updates are released as: +- Patch versions for fixes (0.1.x) +- Documented in CHANGELOG.md +- GitHub Security Advisories +- crates.io release notes + +Subscribe to releases on GitHub to receive security update notifications. + +## Audit History + +| Date | Auditor | Scope | Result | +|------------|---------|-------|--------| +| 2025-10-18 | Internal | v0.1.0 | No issues | + +## Contact + +For security concerns: andrey.rozanov.vl@gmail.com +For general issues: https://github.com/RAprogramm/cstring-array/issues + +## Acknowledgments + +We appreciate responsible disclosure of security vulnerabilities. Contributors will be acknowledged in: +- Security advisories +- Release notes +- CHANGELOG.md + +Thank you for helping keep cstring-array secure! diff --git a/cliff.toml b/cliff.toml new file mode 100644 index 0000000..44c8d46 --- /dev/null +++ b/cliff.toml @@ -0,0 +1,58 @@ +# SPDX-FileCopyrightText: 2025 RAprogramm +# SPDX-License-Identifier: CC0-1.0 + +[changelog] +header = """ +# Changelog + +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +""" +body = """ +{% if version %}\ + ## [{{ version | trim_start_matches(pat="v") }}] - {{ timestamp | date(format="%Y-%m-%d") }} +{% else %}\ + ## [unreleased] +{% endif %}\ +{% for group, commits in commits | group_by(attribute="group") %} + ### {{ group | upper_first }} + {% for commit in commits %} + - {% if commit.breaking %}[**breaking**] {% endif %}{{ commit.message | upper_first }}\ + {% endfor %} +{% endfor %}\n +""" +trim = true +footer = """ + +""" + +[git] +conventional_commits = true +filter_unconventional = false +split_commits = false +commit_parsers = [ + { message = "^feat", group = "Features" }, + { message = "^fix", group = "Bug Fixes" }, + { message = "^doc", group = "Documentation" }, + { message = "^perf", group = "Performance" }, + { message = "^refactor", group = "Refactor" }, + { message = "^style", group = "Styling" }, + { message = "^test", group = "Testing" }, + { message = "^chore\\(release\\): prepare for", skip = true }, + { message = "^chore\\(deps\\)", skip = true }, + { message = "^chore\\(pr\\)", skip = true }, + { message = "^chore\\(pull\\)", skip = true }, + { message = "^chore|^ci", group = "Miscellaneous Tasks" }, + { body = ".*security", group = "Security" }, + { message = "^revert", group = "Revert" }, +] +protect_breaking_commits = false +filter_commits = false +tag_pattern = "v[0-9]*" +skip_tags = "" +ignore_tags = "" +topo_order = false +sort_commits = "oldest"