Consider creating a new repository for API

[dyladan]

@open-telemetry/javascript-approvers @open-telemetry/javascript-maintainers I am working on a PR to separate the API and context-base packages out of the lerna repo so that they can be versioned separately. Currently, I'm adding them to a new ./stable folder, but I was thinking it might be better for build/release/changelog reasons if we move them into their own repositories. I expect that we will only very rarely see changes to the API package so complicating the main repo build scripts even more and slowing down the CI build for all changes might be more annoying than having the API as a separate repo. This will also make it easy for us to very easily track changes to the API separately from other packages.

[obecny]

In theory api should not changed anymore or very often, so having this in separate repo will definitely be some improvement. I would then rather move it to separate repo then trying to make more changes in current one with build etc.

[dyladan]

Ok. I think the first step is to split metrics out of it so i'll make a PR for that today. At the gov meeting i'll ask about making a new repo and move the stable part of the API over when I can.

[dyladan]

One more question related to this. What should the repo be called? I assume we're ok with opentelemetry-js-api?

[vmarchaud]

I expect that we will only very rarely see changes to the API package so complicating the main repo build scripts even more and slowing down the CI build for all changes might be more annoying than having the API as a separate repo

Its possible to only trigger a workflow if specific path on the repo is changes so i don't think this should be a "valid" reason to move out.

@dyladan Also i'm interested in what other languages are doing ? Do you know if some are looking to do this too ?

My main worry is that i wouldn't (as an end user) want having too many repos to look at to understand how the JS implementations works. With the core / contrib split there are often questions on whats where (on gitter or issues), i don't want to increase this problem :/

[dyladan]

I understand not wanting to split to too many repos, but I think the API/SDK split is pretty well established. When I am trying to find a package I typically go to NPM and look for the repository link there and this would still work.

I know it is possible to solve this in CI, but I think it is much easier to solve it by splitting into another repo. This will also encourage the distinction between an SDK change and an API change.

[dyladan]

We discussed this in SIG today. @obecny was also in favor of creating a separate repo for the API. Some people on the call, particularly @MSNev and @johnbley, expressed concerns that having the API in a separate repository might present its own challenges. I'll let them add their thoughts here in their own words if they choose, but in the end the group was in general agreement that the benefits of a separate repository probably outweighed the drawbacks. In particular enforcing a hard separation between API changes and SDK changes, and even what it means for a component to be a part of the SDK vs a part of the API. It also opens the possibility of stricter access controls (branch protections, etc) than the main repository, a simpler workflow to backport fixes to previous versions if need be, and separate github pages documentation for the API and SDK.

[vmarchaud]

I agree than that it would be way harder to "break" the api since its another repo, and its already an advantage for which i think would be worth to make the move

[MSNev]

My concern was based purely on the additional (local) steps that will be required when we get to merging in metrics and logging into the API (to avoid creating multiple releases - because of unexpected issues) -- its not impossible it just gets messy and it's not fun building a separate repro locally and applying it on top of another one (into the node_modules).

But long term, I do agree that by splitting it will make it harder to accidently or inadvertently break the "api".

Another issue that I've just thought of is that if we have any "common" helpers which are not exported (because they are not and we don't want them to be part of the API) will require code duplication etc.

[vmarchaud]

@MSNev Do you have an example for "common" helpers ? Most of them are in core already

[dyladan]

Originally posted by @MSNev #1795 (comment)

I was talking generically, in terms of internal helpers. If we always export everything then it's a mute point.

And when I'm saying "exported", I'm meaning exported by the resulting "package" / project (i.e. generally Index.ts) and not just exported from a local project file.

[dyladan]

I can give at least one example. Noop implementations are not exported by the API module but are used in some tests. They are not an official part of the API, so if they are moved or changed those tests will break.

[MSNev]

I was talking generically, in terms of internal helpers. If we always export everything then it's a mute point.

[MSNev]

And when I'm saying "exported", I'm meaning exported by the resulting "package" / project (i.e. generally Index.ts) and not just exported from a local project file.

[dyladan]

Please try to respond within the thread if you are responding to a particular message.