Document new upcxx::experimental namespace

[Amir Kamil]

This proposal is an offshoot of issue #25 and PR #328. The following entities are defined in the upcxx namespace but unspecified:

destroy_heap()
restore_heap()
broadcast_nontrivial()
reduce_all_nontrivial()
reduce_one_nontrivial()
op_add
op_mul
op_bit_and
op_bit_or
op_bit_xor
op_min
op_max

@Dan Bonachea suggested moving this into a upcxx::experimental namespace. I think that’s a great idea.

For now, we are planning to keep the following unspecified entities in the top-level upcxx namespace:

say
os_env()
release_version()
spec_version()

As noted in PR #328 comments, the latter two are ECP requirements, and the former two are used extensively in the tests and unlikely to change.

[Dan Bonachea]

Sounds like a good plan to me, and I'd like to see this in time for the release.

We can either tack it onto PR 328 or do it separately, whichever is more convenient.

[Amir Kamil]

This is now in PR 328.

[Dan Bonachea]

Having thought about this further, I now think it makes sense to move upcxx::say to upcxx::experimental, and augment test/util.hpp to declare using upcxx::experimental::say (with appropriate version bracketing). This ensures tests can continue to use unqualified say, and avoids spurious breakage of version compatibility for tests.

If there are no strong objections to this idea, I'll pursue adding it to PR 328.

If it works well, I might do the same for os_env

[Amir Kamil]

Agreed.

[Dan Bonachea]

Merge of pull request #328 into develop @ 0e5f91c has made the suggested implementation changes.

Converting this issue into a documentation issue to decide if/how to document anything about this new experimental namespace.

I suggest we add something in docs/implementation-defined.md to at least explain the existence of the experimental and detail namespaces, and the caveats associated with each (the ChangeLog has some text in this direction). We could optionally also add sketches of selected experimental interfaces with appropriate caveats.

[Dan Bonachea]

Mass roll-over of open issues to next release milestone

[Amir Kamil]

Documentation done in PR 361.