Distinguish in docs BridgeStan Users from src C-API callers

[roualdes]

It seems like the greater BridgeStan community could benefit from setting, and using consistently within our doc, specific nouns to distinguish between BridgeStan users and callers of the C level API.

As I think of it, users refers to people who touch the interface level API. Further, in my opinion, we don't have a relatively settled noun for those who touch exclusively the C level API, distinct from the interface API.

Do you all agree such a distinction would help? If so, what nouns do you suggest?

[WardBrian]

I don't think there are many places in our documentation as it currently stands where the distinction is particularly strong right now, but I can imagine there being more over time. Right now the "How it works" page uses "developers" as a proxy for the second group, but that doesn't fit perfectly either.

This is why I was going back and forth with myself on whether or not #91 would require a major version bump. It's only really a breaking change if you're using the C API outside of the "official" wrappers we provide. We could go ahead and say that the C API is a moving target and things like extra arguments will be added without a major version bump if we can handle them in a backwards-compatible way in our interfaces, but that has its own downsides, especially if we imagine a world where interfaces exist outside our repo (if we decide Rust #88 should stay an external effort, for example)

I think the only person I have heard of who is using BridgeStan at the C level is @jtassarotti, who might have some thoughts on this.

[bob-carpenter]

I think we should bump if we break backwards compatibility of the C API. Do we bump all the API's versions at once?

The client relationships in BridgeStan are:

API	Client of	Description
src/bridgestan.cpp		Core C++ API
src/bridgestan.h	src/bridgestan.cpp	Core C API
src/bridgestanR.cpp	src/bridgestan.cpp	R-specific C++ API
src/bridgestanR.h	src/bridgeStanR.cpp	R-specific C API
python/	src/bridgestan.h	Python API
julia/	src/bridgestan.h	Julia API
R/	/src/bridgestan.h	R API

[WardBrian]

Do we bump all the API's versions at once?

We have thus far. I really like this system, since it means "I have Bridgestan version x.y.z" installed has one, unambiguous meaning, but it makes things like major version bumps somewhat confusing if the breaking change doesn't affect the API in question.

#92 would likely require a breaking change in the interface-level code, so the next version would be a major version regardless of the C-API-only changes

[aseyboldt]

For users of the C API it would I think be nice to have a version specific to changes in the C API that can be inspected directly.
Something like this maybe:

int BS_CAPI_VERSION_MAJOR = 1;
int BS_CAPI_VERSION_MINOR = 0;

Without this, any external code that loads and uses a shared library that contains a stan model has to blindly trust that the symbols of the shared object correspond to functions of the expected type. With version symbols like those it would be possible to check that BS_CAPI_VERSION_MAJOR == expected_major and BS_CAPI_VERSION_MINOR >= expected_minor at runtime.
In other languages you would at least get a more or less decent error message if something doesn't make sense anymore, while the C code might do who-knows-what (probably segfault).

[WardBrian]

We already have the version information in the C++ source in version.hpp, we just need to expose it appropriately

[roualdes]

This issue started to get little muddied, probably because it wasn't super clear from the beginning. Is there anything preventing us from closing this?

[WardBrian]

I think we can close it. The discussion is relevant for things like how we communicate in release notes (#107) but otherwise I don't think we have anything specific/actionable