Managing Multiple Projects with boilerplate

Introduction

Starting with version 1.1.0, boilerplate supports projects - a way to organize multiple independent collections of boilerplate content. This is particularly useful when:

You want to keep your personal boilerplate separate from shared content
You’re working with colleagues who have their own boilerplate collections
You manage boilerplate for different research areas or contexts
You want to experiment without affecting your main boilerplate database

Project Basics

Default Project

For backward compatibility, all boilerplate operations use a “default” project if you don’t specify one:

# These are equivalent:
boilerplate_init()
boilerplate_init(project = "default")

# Your existing code continues to work unchanged
db <- boilerplate_import()

Creating a New Project

To create a new project, simply specify the project name when initializing:

# Create a project for your lab's shared content
boilerplate_init(
  project = "lab_shared",
  categories = c("methods", "measures"),
  create_dirs = TRUE,
  confirm = FALSE
)

# Create a project for content from a colleague
boilerplate_init(
  project = "smith_measures",
  categories = "measures",
  create_dirs = TRUE,
  confirm = FALSE
)

Working with Projects

All core functions accept a project parameter:

# Import from a specific project
lab_db <- boilerplate_import(project = "lab_shared")

# Save to a specific project
boilerplate_save(lab_db, project = "lab_shared")

# Export from a specific project
boilerplate_export(
  db = lab_db,
  project = "lab_shared",
  format = "json"
)

Project Organization

Projects are stored in a structured directory hierarchy:

boilerplate/
└── projects/
    ├── default/
    │   └── data/
    │       └── boilerplate_unified.json
    ├── lab_shared/
    │   └── data/
    │       └── boilerplate_unified.json
    └── smith_measures/
        └── data/
            └── boilerplate_unified.json

Cross-Project Operations

Listing Projects

To see all available projects:

# Simple list
projects <- boilerplate_list_projects()
print(projects)

# With details
boilerplate_list_projects(details = TRUE)

Copying Between Projects

The boilerplate_copy_from_project() function enables selective copying of content between projects:

# Copy specific measures from a colleague's project
boilerplate_copy_from_project(
  from_project = "smith_measures",
  to_project = "default",
  paths = c("measures.anxiety", "measures.depression"),
  confirm = FALSE
)

# Copy with a prefix to avoid naming conflicts
boilerplate_copy_from_project(
  from_project = "smith_measures",
  to_project = "default",
  paths = c("measures.anxiety", "measures.depression"),
  prefix = "smith_",  # Results in smith_anxiety, smith_depression
  confirm = FALSE
)

Conflict Handling

When copying between projects, you can handle conflicts in three ways:

# Skip conflicting entries (default)
boilerplate_copy_from_project(
  from_project = "lab_shared",
  to_project = "default",
  paths = "methods.sampling",
  merge_strategy = "skip"
)

# Overwrite existing entries
boilerplate_copy_from_project(
  from_project = "lab_shared",
  to_project = "default",
  paths = "methods.sampling",
  merge_strategy = "overwrite",
  confirm = TRUE  # Will ask for confirmation
)

# Rename conflicting entries
boilerplate_copy_from_project(
  from_project = "lab_shared",
  to_project = "default",
  paths = "methods.sampling",
  merge_strategy = "rename"  # Creates sampling_2, sampling_3, etc.
)

Practical Workflow Example

Here’s a complete workflow for managing content from multiple sources:

# 1. Initialise your main project (if not already done)
boilerplate_init(
  project = "my_research",
  create_dirs = TRUE,
  confirm = FALSE
)

# 2. Create a project for colleague's content
boilerplate_init(
  project = "colleague_jane",
  categories = "measures",
  create_dirs = TRUE,
  confirm = FALSE
)

# 3. Import and add content to colleague's project
jane_db <- list(
  measures = list(
    work_stress = list(
      description = "Work stress scale from Jane's lab",
      items = 15,
      reference = "Smith2023"
    ),
    burnout = list(
      description = "Burnout inventory",
      items = 22,
      reference = "Smith2022"
    )
  )
)

boilerplate_save(jane_db, project = "colleague_jane")

# 4. Selectively import what you need
boilerplate_copy_from_project(
  from_project = "colleague_jane",
  to_project = "my_research",
  paths = "measures.work_stress",  # Only import the work stress scale
  prefix = "jane_",  # Avoid conflicts
  confirm = FALSE
)

# 5. Verify the import
my_db <- boilerplate_import(project = "my_research")
names(my_db$measures)  # Should include "jane_work_stress"

Best Practices

Use descriptive project names: Instead of “project1”, use “smith_lab_measures” or “meta_analysis_2024”

Document project sources: Keep notes about where content came from

# Add source information to imported content
my_db$measures$jane_work_stress$source <- "Jane Smith's lab, imported 2024-01-15"
boilerplate_save(my_db, project = "my_research")

Regular backups: Projects are independent, so back them up separately

boilerplate_export(
  db = my_db,
  project = "my_research",
  format = "json",
  output_file = paste0("backup_my_research_", Sys.Date(), ".json")
)

Use prefixes for external content: This prevents naming conflicts and makes sources clear

Migration from Pre-1.1.0

If you’re upgrading from an earlier version, your existing boilerplate data will continue to work:

Existing data in boilerplate/data/ is treated as the “default” project
No changes to your code are required
You can start using projects whenever you’re ready

Summary

Projects in boilerplate provide a flexible way to: - Keep different collections of content separate - Share content with colleagues without mixing databases - Experiment with new content without affecting your main database - Maintain clear organization as your boilerplate collection grows

The project system is entirely optional - if you don’t need multiple collections, simply continue using boilerplate as before, and everything will work with the “default” project.