facebook / facebook/hhvm

[RFC] Introduce `<<__Experimental>>`

Open
#8,775 2 comments 0 reactions 0 assignees View on GitHub
feature request hack
Dominant language
C++
Stars
18.7k
Forks
3.1k
Avg merge
1h 47m
Merged PRs (30d)
2

Description

a stable project sometimes introduces experimental APIs.

for example, we can look at `HSL` vs `HSL-experimental`, while most things in `HSL-experimental` work, people should not rely on the 100%, and that's the reason for using the `HH\Lib\Experimental` namespace, instead of the base namespace `HH\Lib`.

Other large projects such as [Symfony](https://github.com/symfony/symfony), use a different technique, that is using `@experimental` annotation, to inform the user that an API is experimental, and is not covered by the BC promise.

**Is your feature request related to a problem? Please describe.**

The current solution is:

If project B has an experimental API, it uses a different namespace and probably provides that experimental API in a different package, to avoid people using it by mistake as they are not aware of it being experimental.

**Describe the solution you'd like**

The solution for this could be a new annotation ( similar to `__Deprecated` ), this will give hh_client the power to warn users when using such an experimental API, but will not warn users about it if they are using it within another experimental component.

e.g:

```hack
namespace HH\Lib {
<<__Experimental>>
interface Handle {}

<<__Experimental>>
interface ReadHandle extends Handler { ... } // <-- no warnings about experimental features, as this in itself is an experiment.

<<__Experimental>>
interface WriteHandle extends Handler { ... }
}

namespace App {
// v-- warning, using experimental interface `ReadHandle`
async function read(ReadHandle $handle): Awaitable {}

<<__Experimental>> // ok, no warnings.
async function write(WriteHandle $handle, string $data): int {}
}

```

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.