Contributing Guidelines

Thank you for your interest in contributing to the OHDSI GIS Working Group! This guide will help you get started.


Code of Conduct

All contributors are expected to follow the OHDSI Code of Conduct. We are committed to providing a welcoming and inclusive environment for all.


How to Contribute

1. Join the Community

Before contributing code, we encourage you to:

  1. Sign up for OHDSI Teams (registration link)
  2. Join the GIS Working Group (registration link)
  3. Attend weekly meetings - Fridays 10 AM US Eastern (Teams link)
  4. Introduce yourself - Let us know your interests and background

2. Find Something to Work On

Good First Issues

Check the GitHub Project Board for issues labeled: - good first issue - Beginner-friendly tasks - help wanted - Tasks needing contributors - documentation - Documentation improvements

Use Cases

Review open use cases to see active research projects.

Propose Your Own

Have an idea? Great! Either: - Submit a use case - Discuss in weekly meetings - Post in the Teams channel


Development Workflow

Step 1: Set Up Your Environment

Fork and Clone

# Fork the repository on GitHub, then:
git clone https://github.com/YOUR-USERNAME/REPOSITORY-NAME.git
cd REPOSITORY-NAME
git remote add upstream https://github.com/OHDSI/REPOSITORY-NAME.git

Install Dependencies

For gaiaDb and full stack (via gaiaDocker):

git clone https://github.com/OHDSI/gaiaDocker.git
cd gaiaDocker
docker compose --profile gaia up -d

See Deployment Strategies for detailed setup.

Step 2: Create a Branch

git checkout -b feature/your-feature-name
# or
git checkout -b fix/your-bug-fix

Branch Naming Conventions: - feature/description - New features - fix/description - Bug fixes - docs/description - Documentation - refactor/description - Code refactoring

Step 3: Make Your Changes

Coding Standards

R Code (gaiaCore R client): - Follow tidyverse style guide - Use roxygen2 for documentation - Include unit tests for new functions - Run devtools::check() before committing

SQL (gaiaDb - core processing logic): - Use lowercase for keywords - Indent for readability - Comment complex queries - Include transformation documentation - All geospatial processing stays in gaiaDb

Documentation: - Update relevant .Rmd files - Include examples where appropriate - Update function documentation

Testing

  • Add tests for new functionality
  • Ensure existing tests pass
  • Run full test suite before submitting PR

For R packages:

devtools::test()
devtools::check()

Documentation

Update documentation as you code:

For R functions:

#' Function Title
#'
#' Description of what the function does
#'
#' @param param1 Description of param1
#' @param param2 Description of param2
#' @return Description of return value
#' @examples
#' example_code()
#' @export
my_function <- function(param1, param2) {
  # implementation
}

Then run:

devtools::document()

For website/documentation: - Edit .Rmd files in rmd/ directory - Run source('./build_site.R') to rebuild

Step 4: Commit Your Changes

git add .
git commit -m "Brief description of changes

More detailed explanation if needed:
- Bullet point 1
- Bullet point 2

Closes #123"

Commit Message Guidelines: - First line: Brief summary (50 chars or less) - Blank line - Detailed explanation if needed - Reference issues/PRs: Closes #123, Relates to #456

Step 5: Push and Create Pull Request

git push origin feature/your-feature-name

Then on GitHub: 1. Click “Compare & pull request” 2. Fill out the PR template 3. Link related issues 4. Request reviewers

Step 6: Code Review

  • Respond to review comments
  • Make requested changes
  • Push updates (they’ll appear in the PR automatically)
  • Mark conversations as resolved when addressed

Step 7: Merge

Once approved: - Maintainer will merge your PR - Delete your feature branch - Pull latest changes from upstream


Pull Requests

Title: [Component] Brief description (e.g., [gaiaDb] Fix spatial indexing bug)

PR checklist: Describe changes, link issues, specify type (bug/feature/docs), include tests, update docs

See GitHub PR template for full checklist.


Coordination

Weekly meetings (Fridays 10 AM ET): 2-min updates - completed work, current tasks, blockers

Task tracking: GitHub Project Board

Labels: good first issue, help wanted, bug, enhancement, documentation, Use Case

Communication: Meetings (primary), Teams (async), GitHub issues (technical), Email (announcements)


Contribution Types

Code: Features, bug fixes, performance, tests Docs: Website, API docs, tutorials, examples Data: Transformation recipes, metadata, vocabularies Research: Use cases, validation, methods, publications Community: Forums, onboarding, presentations, reviews


Development Best Practices

Privacy & Security

  • Never commit patient data or PHI
  • Never commit credentials or API keys
  • Use .gitignore for sensitive files
  • Use environment variables for secrets

Data Handling

  • Work with synthetic data for development
  • Document data provenance
  • Respect data licenses
  • Follow institutional policies

Code Quality

  • Write readable, maintainable code
  • Comment complex logic
  • Follow DRY (Don’t Repeat Yourself)
  • Refactor when appropriate

Version Control

  • Commit early and often
  • Write meaningful commit messages
  • Keep commits focused
  • Don’t commit broken code to main


Getting Help

Technical Questions

  • Ask in weekly meetings
  • Post in Teams GIS channel
  • Create GitHub discussion
  • Tag relevant maintainers

Stuck on Something?

Don’t struggle alone! We’re here to help: - Post your question in Teams - Bring it to weekly meeting - Email working group leaders - Create a GitHub issue

New to GIS/OMOP/R?

We welcome all skill levels: - Pair with experienced contributors - Start with documentation tasks - Ask questions freely - Learn as you go


Attribution & Credit

Authorship

  • Significant code contributors may be listed as authors
  • Discussed on case-by-case basis
  • Typically for substantial, ongoing contributions

Acknowledgments

  • All contributors acknowledged in releases
  • GitHub automatically tracks contributions
  • Presentations credit community effort

Publications


Questions?

Contact the working group: - Email: houghtaling[at]ohdsi[dot]org - Teams: GIS Working Group channel - Meetings: Fridays 10 AM US Eastern - GitHub: @OHDSI/GIS


Thank you for contributing to OHDSI GIS! Together, we’re building tools that improve population health through integrated geospatial and clinical data analysis.