search

SFDO-Community-Sprints / Snowfakery-Recipe-Templates

Repo for all contributed Snowfakery recipes, maintained by Data Gen Toolkit team.
BSD 3-Clause "New" or "Revised" License
27 stars 8 forks source link

Thoughts on how to classify and organize recipes #117

Closed prescod closed 2 years ago

prescod commented 2 years ago

We’ve been making “template recipes” for a while and perhaps we should have a conversation about what they are and are for.

Recipe Types

I propose that each recipe be designed with a specific goal in mind: A recipe is either “Pedagogic”, “Realistic” or “Performance” :

  1. A Pedagogic Recipe has a clear Educational purpose:

    1. “This recipe shows how to populate connect Contacts to Programs with Program Engagements randomly”
    2. “This recipe shows how to read a CSV file to populate Users”
    3. More likely to only contain required fields

  2. A Realistic Recipe is appropriate for doing demos of products. It should be considered from the point of view of someone who wants to try out a product and has no data for their trial.

  3. Performance recipes will not usually be created by the Open Source community. They are for stress-testing specific features by making large and potentially quite unrealistic datasets..

A Markdown or HTML document could link to all of the recipes.

On The Question of Code Reuse

I propose that we do not worry, for now, about the role of Code Reuse. Every recipe will be standalone except the few which are designed to demonstrate code reuse, or situations where for our own internal recipe-building purposes it seems easier to reuse code.

Here are some arguments against a focus on reuse:

  1. It is really hard to predict what kinds of “knobs and levers” a reusable recipe should provide for customization. Should the skew between two objects be hard-coded or configurable? Should the name template be hard-coded or configurable, etc.
  2. Making a recipe very reusable means adding the knobs and levers which also make it hard to read and hard to use for pedagogy.
  3. random_reference probably won’t do what you want if you have a bunch of different kinds of Account or Contact or whatever and construct a recipe from components.

On the question of complexity

It may be useful to identify recipes that employ advanced snowfakery features such as:

For the community owned recipe repo, we should try to use these features only when strictly necessary, as they introduce complexity that is harder to maintain and more difficult for end users to run smoothly without support.

prescod commented 2 years ago

I'll make this a discussion instead.

prescod commented 2 years ago

Discussion here:

https://github.com/SFDO-Community-Sprints/Snowfakery-Recipe-Templates/discussions/118