Glossary of terms

[DRMacIver]

Generally about a year or two into a project I find myself thinking "Damn, I wish we'd decided on a glossary of terms back at the start of the project" when I discover that to pick a purely hypothetical scenario that definitely isn't anything to do with Hypothesis we've used the word "example" to refer to five different semantically very distinct things.

Anyway, I thought about this when I was looking at uniform::Generator and thinking "Is this really a generator? I'm not sure this is a generator. I think something like Csmith is a generator." to myself.

I've also noticed that we've implicitly introduced some terms like "choice point" in our discussions, and I've been reusing the terminology of "choice sequence" from the Hypothesis paper.

Shall we come up with a glossary of terms and try to use them consistently?

[regehr]

I think this is a good idea. separately, I think we can and should rethink the terminology in the code and API as early as possible, and try to get it right. David I'm pretty sure that I just borrowed "generator" from your Python prototype :). but could be misremembering. we also may want to revise "uniform" I'm not really sure any longer that uniform sampling is how we want to phrase our goals here.

[regehr]

for now at least I think it's fine to just put this into README.md (right after the problem statement), but if it's going to grow substantially then putting it in a different file may be better

[DRMacIver]

I'm pretty sure that I just borrowed "generator" from your Python prototype

Ha ha it's certainly possible. I haven't learned this lesson because I'm good at naming things.

[regehr]

want to take a stab or even just list some terms that might want defining?

[DRMacIver]

I think at present we've got the following needs:

• static choice point - somewhere in the calling code where choice is called.
• choice sequence - Hypothesis-derived terminology, a sequence of results from choice that we can run
• ??? - an object on which you call choice
• ??? - an object which acts as a source of the above objects
• ??? - a calling program/function/etc that takes a ??? and returns some test case.
• test case - some generated value as per the above

I'd lean in favour of it going in its own file, but this is a very weakly held opinion.

[DRMacIver]

Also I just checked my Python prototype and I think I'm using "Generator" to mean something more like Csmith. It's a thing that takes a generator definition and generates test cases.

[regehr]

ah, ok, I probably just remembered seeing the word there. so yeah we should try to get the terms right. I'm happy with "choice" but everything else can be changed :)

[regehr]

I think "balancer" is fine for the thing that guides exploration of the decision tree, or "guide" or something like that

[regehr]

tell you what though-- how about you drop some stuff into a skeleton glossary but let me own the code for now, I can make whatever changes to API terminology that we agree on

[DRMacIver]

Sure! Here's a very basic skeleton: https://github.com/regehr/uniform-tree-sampling/blob/main/GLOSSARY.md

[DRMacIver]

We've got a glossary now, so marking this as closed.