Skip to contents

Contributing to ggforge

Source: .github/CONTRIBUTING.md

Thank you for your interest in contributing to ggforge! This document provides guidelines for contributing to the project.

Getting Started

Fork and Clone Workflow

  1. Fork the repository on GitHub

  2. Clone your fork locally:

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

  3. Add the upstream repository as a remote:

    git remote add upstream https://github.com/Zaoqu-Liu/ggforge.git

  4. Create a new branch for your changes (see Branch Naming below)

  5. Make your changes, commit, and push to your fork

  6. Open a Pull Request against the upstream repository

Branch Naming Conventions

Use descriptive branch names that reflect the type of change:

  • fix/ - Bug fixes (e.g., fix/volcano-plot-labels)
  • feat/ - New features (e.g., feat/new-chord-plot-option)
  • docs/ - Documentation only (e.g., docs/update-readme)
  • refactor/ - Code refactoring (e.g., refactor/validator-module)
  • test/ - Adding or updating tests (e.g., test/heatmap-coverage)

Before Submitting a Pull Request

1. Run Package Checks

Your contribution must pass devtools::check() before submitting a PR:

devtools::check()

Resolve any errors, warnings, or notes before submitting.

2. Document Your Code

  • Use roxygen2 for all function documentation
  • Run devtools::document() after adding or modifying exported functions
  • Follow the existing documentation style (e.g., @inheritParams, @keywords internal for internal functions)

3. Follow Existing Code Style

  • Match the coding style used in the rest of the package
  • Use consistent indentation and naming conventions
  • For new plot types, follow the existing API conventions (see API Consistency below)

4. Add or Update Tests

  • Run tests with devtools::test()
  • Add tests for new functionality
  • Ensure existing tests continue to pass

5. Include a Reprex for Bug Reports

When reporting bugs (in issues or PR descriptions), include a minimal reproducible example using the reprex package when possible. This helps maintainers reproduce and fix the issue quickly.

API Consistency

ggforge uses a consistent API pattern across its plotting functions. When adding new plot types:

  • Use the *Plot naming convention (e.g., BarPlot, ScatterPlot, VolcanoPlot)
  • Follow the forge()-like pattern: high-level wrapper functions that accept data, x, y, and common parameters (theme, palette, facet_by, split_by, etc.)
  • Implement an internal *PlotAtomic function for the single-plot logic
  • Use build_plot() from the plot-builder system for split/facet/combine support
  • Reuse shared parameters from parameters.R via @inheritParams

Development Setup

# Install dependencies
install.packages("devtools")
devtools::install_deps(dependencies = TRUE)

# Load the package in development mode
devtools::load_all()

# Run checks
devtools::check()
devtools::test()
devtools::document()

Questions?

If you have questions about contributing, feel free to open an issue for discussion.