Skip to contents

Contributing to MockData

Source: CONTRIBUTING.md

Thank you for considering contributing to MockData! This package is part of the recodeflow ecosystem and benefits from community input.

Getting Started

Prerequisites

  • R (>= 4.2.0)
  • RStudio or another R IDE (recommended)
  • Git
  • Package development tools: install.packages(c("devtools", "testthat", "roxygen2"))

Setting Up Development Environment

  1. Fork and clone the repository:
git clone https://github.com/your-username/MockData.git
cd MockData
  1. Open in RStudio:
    • Double-click MockData.Rproj
    • Or: File → Open Project → Select MockData.Rproj
  2. Install development dependencies:
devtools::install_dev_deps()
  1. Load the package:
devtools::load_all()

Development Workflow

Making Changes

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

  1. Make your changes following the coding standards below

  2. Document your changes:

    • Update function documentation (roxygen2 comments)
    • Add examples where appropriate
    • Update NEWS.md with your changes

  3. Write tests for new functionality:

    • Add tests to tests/testthat/test-mockdata.R
    • Ensure all tests pass: devtools::test()

  4. Run checks:

devtools::check()

  1. Commit your changes following commit message guidelines

  2. Push and create a pull request

Coding Standards

R Code Style

  • Use 2 spaces for indentation (not tabs)
  • Line length: aim for < 80 characters, max 100
  • Use <- for assignment, not =
  • Function names: snake_case
  • Variable names: snake_case
  • Constants: SCREAMING_SNAKE_CASE

Documentation

  • All exported functions must have roxygen2 documentation
  • Include @param, @return, @examples, @export tags
  • Examples should be runnable (use \dontrun{} sparingly)
  • Use Canadian spelling (behaviour, colour, centre)

Commit Messages

Follow Canadian Government Digital Standards: - Format: type: brief description - Types: - feat: New feature - fix: Bug fix - docs: Documentation changes - test: Adding or updating tests - refactor: Code refactoring - style: Code style changes (formatting, etc.) - chore: Maintenance tasks

Examples:

feat: add support for date variable generation
fix: handle missing NA codes in categorical variables
docs: update README with CHMS example
test: add tests for parse_range_notation edge cases

Do not credit AI tools in commit messages (as per project guidelines).

Testing

Running Tests

# Run all tests
devtools::test()

# Run specific test file
testthat::test_file("tests/testthat/test-mockdata.R")

# Run with coverage
covr::package_coverage()

Writing Tests

  • Place tests in tests/testthat/test-mockdata.R
  • Use descriptive test names: test_that("parse_range_notation handles closed intervals", { ... })
  • Test edge cases and error conditions
  • Aim for high code coverage

Test Data

  • Use existing metadata in inst/extdata/ for tests
  • If adding new test data, document its purpose
  • Keep test data small and focused

Building Documentation

Prerequisites for documentation builds

  1. Install Quarto: Download from https://quarto.org/docs/get-started/ or use Homebrew:
brew install quarto
  1. Ensure pkgdown and roxygen2 are available:
# These are in Suggests, install if needed
renv::install(c("pkgdown", "roxygen2"))
  1. Configure PATH for IDE users (Positron/RStudio):

If you encounter “System command ‘quarto’ failed” errors, add Quarto to your PATH in ~/.Renviron:

PATH="/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin:/usr/sbin:/sbin:${PATH}"

Then restart your R session.

Building the pkgdown site

# 1. Regenerate .Rd files from roxygen comments (after editing R documentation)
roxygen2::roxygenize()

# 2. Build the pkgdown site
pkgdown::build_site()

# 3. Preview locally
browseURL("docs/index.html")

Important: Always run roxygen2::roxygenize() before pkgdown::build_site() if you’ve modified roxygen documentation in R files.

Rendering individual vignettes

# From project root
quarto render vignettes/getting-started.qmd --to html

Validation Tools

Before submitting, run the validation tools:

# Validate metadata quality
Rscript mockdata-tools/validate-metadata.R

# Test coverage across cycles
Rscript mockdata-tools/test-all-cycles.R

Areas for Contribution

High Priority

  • Date variable support: Implement create_date_var() for linkage testing
  • Data quality injection: Add functions to inject realistic data quality issues
  • Performance optimization: Improve generation speed for large datasets
  • Additional vignettes: Real-world use cases and workflows

Medium Priority

  • More survey examples: Add metadata from other recodeflow projects
  • Validation improvements: Enhance metadata quality checks
  • Documentation: Expand README, add pkgdown site

Low Priority

  • Distribution options: Add more probability distributions for continuous variables
  • Correlation structure: Generate correlated variables
  • Time series: Support for longitudinal data

Recodeflow Schema Compliance

When adding or modifying parsers:

  1. Check the schema: See inst/metadata/schemas/ for authoritative definitions
  2. Test with real metadata: Use CCHS, CHMS, or DemPoRT examples
  3. Document notation support: Update README if adding new notation patterns
  4. Coordinate with cchsflow/chmsflow: Major schema changes should be discussed

Questions or Issues?

  • Package questions: Contact Juan Li () or Doug Manuel ()
  • Bug reports: Open a GitHub issue
  • Feature requests: Open a GitHub issue with the “enhancement” label
  • Security issues: Email maintainers directly (do not open public issue)

Code of Conduct

Our Standards

  • Be respectful and inclusive
  • Focus on constructive feedback
  • Prioritize technical accuracy over personal preferences
  • Give credit where credit is due

Unacceptable Behaviour

  • Harassment or discriminatory language
  • Personal attacks or trolling
  • Sharing private information without permission

License

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

Thank you for contributing to MockData and the recodeflow ecosystem!