2.0 Release planning

[WardBrian]

With #91 and #98 merged, we can start to think about when we want to press release on 2.0

Changes since 1.0.2:

• Fix: Const correctness in C api in Fix: Const correctness in C api #89
• Send Stan outputs to stdout rather than stderr in Send Stan outputs to stdout rather than stderr #94
• Allow Stan outputs to be redirected to higher-level things like Python's sys.stdout in Add the ability to provide a callback function for printing #108
• Expose version numbers in C API in Expose version numbers in C API #101
• Breaking change: Propagate error messages through C API in Breaking change: Propagate error messages through C API #91
• Allow nullptr as data argument to constructor in Allow nullptr as data argument to constructor #104
• Breaking change: Implement param_constrain in a thread-safe way in Breaking change: Implement param_constrain in a thread-safe way #98
• Updated Stan to 2.32.0 in (Update to Stan 2.32 #109)

Further changes coming at some point (non-breaking, could be 2.1 if we don't want to wait):

• Rust interface Rust backend #105 (timeline TBD)

[WardBrian]

Thoughts @roualdes @bob-carpenter? I'm in favor of releasing 2.0 soon (maybe Monday?), and then when #105 is ready that would be 2.1 later on

[roualdes]

There was some discussion in #105 about adding functions to parse variable names. If we added such functions to all interfaces, do you imagine that would be a minor version bump after releasing 2.0?

[WardBrian]

Yes, it should be possible to add those in a way which is entirely backwards-compatible. I'm hesitant to attempt them before tuples (which I am pushing for in the next Stan version), both because so much will change and because it's possible new features in the generated code would make it easier.

[roualdes]

Sounds good. I'm in favor of releasing 2.0 too.

[aseyboldt]

If we work around the library unloading issue in #105, I think I can get this ready for review on Monday. So if you want to get it into 2.0 as well, I guess that wouldn't delay things all that much, assuming there aren't any other major issues.

[WardBrian]

I'd personally rather do a 2.1 for that, if only because it lets us take our time for review and keeps the release notes more focused.

Speaking of, here's my proposal for release notes:

---

BridgeStan 2.0.0

This version of BridgeStan features several breaking changes, primarily to the C API which is used "under the hood", but also to how models with generated quantities must be called. Additionally, many "quality of life" features have been added, ranging from const correctness in the C API, to vastly improved error messages in the interfaces.

The BridgeStan documentation has been updated, and old versions of the docs are now available via a dropdown at the top of each page.

Interface changes

Breaking Changes

• For all interfaces, the param_constrain family of functions now accept an rng argument of type StanRNG. This is required if include_gq is set in the function, otherwise it may be omitted. These RNGs are now used in any RNG function calls inside the generated quantities block, rather than using an RNG stored inside the BridgeStan model object.
• This means that the param_constrain function is now thread-safe if each thread has its own StanRNG. See the documentation for your preferred interface for more on how to instantiate StanRNGs.

Other Changes

• BridgeStan has updated to Stan 2.32.1
• Error messages are now properly reported by each language's preferred exception mechanism. This means no more "See C++ stderr for details" messages when an error occurs.
• All interfaces: print() statements inside of Stan models will now be directed to stdout instead of stderr.
• Python: print() statements inside of Stan models are re-directed to sys.stdout by default to allow them to appear in things like Jupyter notebooks. See the capture_stan_prints argument to the StanModel constructor for more details.

C API

Breaking Changes

• Mirroring the above changes for param_constrain, the bs_model_rng type has been split into two types, bs_model and bs_rng. The creation and destruction functions have been renamed to bs_model_construct/bs_rng_construct and bs_model_destruct/bs_rng_desctruct.
• The param_constrain function accepts a new bs_rng* argument, which can be NULL if include_gq is false.
• Any function in the C API which can fail (those which return integer return codes) now accept an additional argument of type char **. If a non-null pointer is provided, it will be set to a newly allocated error message string if a failure occurs. Error messages are no longer printed to stderr. These strings must later be freed by calling a new function bs_free_error_msg.

Other Changes

• The C API functions now properly mark bs_model* arguments as const where appropriate. With the param_constrain changes, this means all functions except for bs_model_destruct take a const pointer now.
• Three new constants are available in the C API - bs_major_version, bs_minor_version, bs_patch_version.
• The data argument to the bs_model_construct function can now be NULL, indicating "no data".
• A new function, bs_set_print_callback is available. This can be used to provide a function which is called when print statements in the Stan model are run. This is primarily used in the Python interface to re-direct to sys.stdout.
• The C API now uses the stdbool.h header file's bool type, rather than typedef int bool

[WardBrian]

We're going to hold off for Stan 2.32.1 which will fix a build issue and improve a couple error messages (which would be relevant to bridgestan users in bs_param_unconstrain_json)

The above release notes will still be correct aside from the .1 in the vendored Stan version