[Discussion] Define a backwards compatibility promise

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

I started to use Temporal a few months ago and I really like it and this SDK. I think you (the maintainers and community) have done an excellent job and I am impressed by many things. The use of Generators in Scope::next() is genius.

I am doing a private Symfony bundle around this package and I've found it a little difficult to work with.

Issue 1

We break backwards compatibility between releases. Here are some examples, but there are many more.

2.9.0

• Temporal\Client\ScheduleClient::getHandle() changed signature.
• Temporal\Client\ServerCapabilities was removed in a way that breaks BC.
• Temporal\Client\WorkflowExecutionHistory was moved to Temporal\Client\Workflow\WorkflowExecutionHistory
• Temporal\Client\WorkflowClient have many methods changing their signatures.

2.10.0

• Temporal\Activity\ActivityCancellationType was converted to enum
• Temporal\Workflow\ChildWorkflowCancellationType was converted to enum
• Temporal\Activity\ActivityOptions::withCancellationType() has changed signature
• Temporal\Worker\ChildWorkflowCancellationType was removed in a way that breaks BC.

Issue 2

We have a bunch of classes in the internal namespace. I suggest all of them should be marked with @internal for better IDE support. But I also see parts of our public API returning internal classes. Example:

Temporal\Worker\Worker::getWorkflows(): RepositoryInterface

Describe the solution you'd like

I would like us, staring with the next minor release, to follow BC very strictly. I suggest to write down a BC promise what it means for us and what third party libraries and application authors can expect from us. Ie, we don't need to be super generous, but we need to be predictable.

Additional context

There is no secret that I am a big fan of Symfony's BC promise. In the best of all worlds, I think we should follow the same promise. Just write a statement in our readme that we follow the same practices.

There is also the Roave/BackwardCompatibilityCheck that will check for any BC breaks as part of the CI workflow.

Begin with the README and the Symfony BC promise linked in the issue, then review the proposed Roave/BackwardCompatibilityCheck integration for the CI workflow. Done means the project’s backwards-compatibility promise and treatment of internal APIs are documented, with the requested compatibility check addressed in the workflow.