Skip to contents

Contributing to text2map

Source: CONTRIBUTING.md

Thanks for your interest in contributing! This document covers the practical steps — for the philosophy behind the package (why the text matrix is the central object, why dgCMatrix over other formats), see the README.

Ways to contribute

  • Bug reports: open an issue. Include a minimal reproducible example (a small DTM/embedding matrix, not your full corpus) and your sessionInfo().
  • Feature requests: also via issues. If it’s a new function, it helps to sketch the intended signature and a worked example up front.
  • Pull requests: fork the repository on GitLab and submit a merge request. Small, focused PRs (one function or one fix) are much easier to review than large ones.
  • Questions: for anything that isn’t a bug or a concrete feature request, reach the maintainers at maintainers [at] textmapping [dot] com.

Before you start coding

For anything beyond a small fix, open an issue first to confirm the approach — it saves rework on both sides. In terms of scope, new functions should work with base R matrices or the Matrix package’s dgCMatrix class; that’s the common interface the whole package is built around.

Style

We follow the Tidyverse style guide and rOpenSci’s packaging guide (see also Advanced R for the reasoning behind them). In short: snake_case names, spaces around infix operators, <- for assignment. Internal (non-exported) helper functions are prefixed with a . (e.g. .convert_mat_to_dgCMatrix()).

Development setup

# Install development dependencies
install.packages(c("devtools", "testthat", "roxygen2"))

# Regenerate documentation and NAMESPACE after changing roxygen comments
devtools::document()

# Run the full test suite
devtools::test()

# Run a single test file while iterating
devtools::test(filter = "utils-dtm")

# Full CRAN-style check before opening a PR
devtools::check()

Tests

  • We use testthat (3rd edition). New functions and bug fixes should come with tests — for a bug fix, a test that fails on the old behavior and passes on the fix is the clearest way to show the fix actually works.
  • Tests that need parallel/multiple cores live in test-z-nocran-*.R files and are skipped on CRAN by filename convention; don’t add skip_on_ci() to them; CI runners with enough cores should still run them.
  • Tests requiring optional packages (quanteda, tm, etc.) should guard with skip_if_not_installed().

Documentation

Function documentation is written as roxygen2 comments in R/ and compiled via devtools::document() — don’t hand-edit files in man/ directly, since they’ll be overwritten. If you’re adding an exported function, also add it to the relevant section of _pkgdown.yml’s reference: list, or the pkgdown site build will fail with a “missing from index” error.

Where to look for context

  • NEWS.md for what’s changed recently.
  • dev/AGENTS.md for internal conventions and known gotchas (parallel/core handling, Matrix import quirks, CI environment variables) if you’re working on package internals.
  • dev/improvement_backlog.md for a maintained list of known issues, planned extensions, and design questions that are open — a good place to find something to pick up, or to check whether an issue you’ve found is already known.

Code of conduct

Be respectful and constructive in issues, merge requests, and any other project communication. Disagreements about approach are normal and useful; personal attacks are not.