Contributing Guidelines

Thank you for considering contributing to nx9-dns-server! This document outlines the process for contributing to the project and provides guidelines to ensure your contributions can be efficiently reviewed and integrated.

Table of Contents

Code of Conduct

All contributors are expected to adhere to our Code of Conduct. Please read CODE_OF_CONDUCT.md before contributing to ensure a respectful and inclusive environment for everyone.

Getting Started

  1. Fork the repository on GitHub
  2. Clone your fork to your local machine: bash git clone https://github.com/YOUR_USERNAME/nx9-dns-server.git cd nx9-dns-server
  3. Add the upstream repository as a remote to keep your fork in sync: bash git remote add upstream https://github.com/thakares/nx9-dns-server.git
  4. Create a new branch for your contribution: bash git checkout -b feature/your-feature-name

Development Environment

Prerequisites

Setup

  1. Install Rust dependencies: bash cargo install cargo-audit cargo-watch cargo-insta

  2. Set up pre-commit hooks: bash cp hooks/pre-commit .git/hooks/ chmod +x .git/hooks/pre-commit

  3. Build the project: bash cargo build

  4. Create a development database: bash cp conf/dns.db.sample dev-dns.db sqlite3 dev-dns.db < conf/dns_records.sql

  5. Run the tests: bash cargo test

  6. Start the server in development mode: bash DNS_DB_PATH=dev-dns.db DNS_BIND=127.0.0.1:5353 cargo run

Contribution Workflow

  1. Sync your fork with the upstream repository: bash git fetch upstream git checkout main git merge upstream/main git push origin main

  2. Create a new branch for your work: bash git checkout -b feature/your-feature-name

  3. Implement your changes

  4. Add tests for your changes

  5. Update documentation if necessary

  6. Run tests to ensure they pass: bash cargo test

  7. Format your code: bash cargo fmt

  8. Run lints: bash cargo clippy

  9. Commit your changes with meaningful commit messages

  10. Push your branch to your fork: bash git push origin feature/your-feature-name

  11. Create a Pull Request from your fork to the upstream repository

Code Style

We follow the standard Rust style guidelines. All code should be formatted using rustfmt and should pass clippy checks:

```bash

Format code

cargo fmt

Run clippy

cargo clippy -- -D warnings ```

Additional style guidelines:

  • Use meaningful variable names
  • Add comments for complex logic
  • Keep functions small and focused
  • Use Rust idioms and patterns
  • Avoid using unsafe code without strong justification
  • Use type-safe approaches rather than string manipulation when possible

Testing Guidelines

All new features and bug fixes should include appropriate tests:

  • Unit tests: Test individual components in isolation
  • Integration tests: Test components working together
  • End-to-end tests: Test complete workflows

To run tests:

```bash

Run all tests

cargo test

Run specific test

cargo test test_name

Run tests with extended output

cargo test -- --nocapture ```

For DNS-specific testing, use the included test scripts in the tools/ directory:

bash ./tools/dnscheck.sh 127.0.0.1:5353

Documentation

Documentation is crucial for the project's usability:

  • Code Documentation: All public API interfaces should have rustdoc comments
  • Wiki: Update wiki pages when adding or changing features
  • README: Keep the README up-to-date with current features and instructions
  • Examples: Provide example configurations and usage scenarios

Generate documentation locally:

bash cargo doc --open

Priority Areas

We're currently focusing on these key areas for contributions:

  1. Web UI Development:
  2. Implementation of administrative interface
  3. Record management components
  4. Dashboard visualizations

  5. User experience improvements

  6. API Service:

  7. RESTful API implementation
  8. Authentication and authorization
  9. Rate limiting and security

  10. API documentation

  11. User Management:

  12. Authentication mechanisms
  13. Role-based access control
  14. User profile management

  15. Multi-factor authentication

  16. Testing Improvements:

  17. Automated integration tests
  18. Performance benchmarks
  19. Security testing

  20. Test coverage improvements

  21. Documentation:

  22. User guides
  23. API documentation
  24. Deployment scenarios
  25. Troubleshooting guides

Issue and Pull Request Process

Creating Issues

  • Use issue templates when available
  • Provide clear reproduction steps for bugs
  • Include environment details (OS, Rust version, etc.)
  • For feature requests, explain the use case and benefits

Pull Request Process

  1. Reference any related issues using GitHub keywords (e.g., "Fixes #123")
  2. Provide a clear description of the changes
  3. Include screenshots for UI changes
  4. Add notes about testing done
  5. Update documentation as needed
  6. Ensure CI checks pass

Commit Message Guidelines

We follow a simplified version of the Conventional Commits format:

``` ():

[optional body]

[optional footer] ```

Types include: - feat: A new feature - fix: A bug fix - docs: Documentation changes - style: Code style changes (formatting, etc.) - refactor: Code refactoring - test: Adding or updating tests - chore: Updates to build process, dependencies, etc.

Example: ``` feat(dns): add support for CAA record type

Implement support for Certificate Authority Authorization records according to RFC 6844.

Resolves: #45 ```

Review Process

All contributions undergo review before being merged:

  1. Automated checks: CI pipeline for tests, linting, and security scans
  2. Code review: At least one maintainer must approve the changes
  3. Discussion: Address any feedback or questions
  4. Final approval: Maintainer approves and merges

Expect feedback within 1-2 weeks. Please be responsive to review comments.

Release Process

nx9-dns-server follows semantic versioning (MAJOR.MINOR.PATCH):

  • MAJOR: Incompatible API changes
  • MINOR: New functionality in a backward-compatible manner
  • PATCH: Backward-compatible bug fixes

Release steps: 1. Update version in Cargo.toml and other relevant files 2. Update CHANGELOG.md with notable changes 3. Create a release tag 4. Build and publish release artifacts

Getting Help

If you need assistance with contributing:

  • Open a discussion on GitHub
  • Check existing issues and PRs for similar topics
  • Join our community chat (link in project README)
  • Email the maintainers directly for sensitive matters

Thank you for contributing to nx9-dns-server! Your efforts help improve DNS infrastructure for everyone.