Standard for releasing protocols from a monorepo

[smol-ninja]

Inspired from similar discussion started by @andreivladbrg.

I've outlined the following recommendations based on what I believe sounds like a good design. Since EVM protocols can be installed using both npm and git submodules, this places us in a unique category that requires new monorepo standards. Unlike web2 monorepos which don’t need to account for git submodule compatibility, we need to adopt an approach that can target both methods.

1. Versioning

• Whenever one or more protocols are released, the version of the protocol (package.json within protocol) should be bumped.
• The version of the monorepo (root package.json) should also be updated.

2. Changelog

• The changelog of the updated protocols should be updated (following common changelog conventions).
• The changelog of the monorepo should be updated. Unlike protocol's changelogs, this doesn’t need to strictly adhere to the common changelog format. Instead, it should prioritize readability. For ex. referring to React monorepo changelog, it can serve as a high-level summary of the changes.

3. NPM Releases

• An NPM release should be published for each protocol with an updated version. For ex. if only the Airdrops is bumped, a release should be published for @sablier/airdrops.

4. GitHub Tags and Releases

• Since the monorepo serves as the main git repository, a git tag for the monorepo should be created.
• Additionally, a GitHub release should also be created for the monorepo, summarizing all the changes in the release.

Q: Can forge install be used to install only a specific protocol in this new design?
A: No, a git submodule always refers to the entire repository. But here is an idea:

When a new tag is published, alongside the monorepo GitHub tag , we can also release protocol-specific tags. For ex, if only Lockup and Airdrops are updated, we would publish lockup-v3.1.0 and airdrops-v3.0.0 in addition to the monorepo tag 1.0.0, even though they all reference the same commit. Since these tags will be consistent with the NPM release tags, this will allow users to install a specific Lockup version without needing to reference the monorepo tag.

forge install sablier=sablier-labs/evm-monorepo@lockup-v3.1.0 --no-commit

And then user can create a remapping

@lockup/=lib/sablier/lockup/src/

cc @sablier-labs/evm.

[PaulRBerg]

Thanks @smol-ninja, some feedback.

The version of the monorepo root package.json should also be updated.

Why? The monorepo isn't published anywhere. We can keep that version frozen to 1.0.0 forever. That's what we do in Interfaces.

• The changelog of the monorepo should be updated

I don't think we need a changelog for the monorepo as a whole. It will undergo a lot of changes/refactors as we tailor it to suit our requirements. And Foundry will eventually add support for Bun workspaces, which will introduce a lot of changes.

a git tag for the monorepo should be created.

A git tag for each package in the monorepo, yes, like @sablier/lockup@3.0.0.

• a git tag for the monorepo should be created.

Yes

we would publish lockup-v3.1.0

Let's go with PROTOCOL@X.Y.Z syntax.

[smol-ninja]

The monorepo isn't published anywhere. We can keep that version frozen to 1.0.0 forever. That's what we do in Interfaces

I think that approach works for Interfaces because there are no releases whereas we publish releases on Github for EVM repos. However, I agree with you we can freeze root version to 1.0.0.

For the GH releases, we can publish it similar to how Microsoft fluentui does.

I don't think we need a changelog for the monorepo as a whole

Agree. We can make protocol level releases too similar to Microsoft fluentui. Do you agree with that?

Let's go with PROTOCOL@X.Y.Z syntax

OK but then forge install would have to use sablier-labs/evm-monorepo@lockup@v3.1.0. I hope it can resolve that correctly (we can check it later and change the strategy for whatever works best).

[PaulRBerg]

Agree regrading the fluentui release approach.

And yeah, it should able to resolve sablier-labs/evm-monorepo@lockup@v3.1.0 (if not, we can open a GitHub issue in the Foundry repo).

Tip

Maybe we should call the repo just evm? Instead of evm-monorepo?