Packaging + versioning strategy

[siddharthkp]

This can be divided into 5 closely related questions. Feel free to nitpick/give your ideas on any of them.

1. What all do we ship? (packaging)

We have 2 code entities to ship:

1. component library
2. tokens

As tokens are a part of the cosmos system, we can ship them as a namespace in the same npm package: auth0-cosmos/tokens

import { spacing } from 'auth0-cosmos/tokens'

@import "node_modules/auth0-cosmos/tokens/colors.sass";

This can be the first incremental step of adopting cosmos into a codebase

---

2. What's our versioning model (versioning)

Once Cosmos comes out of it's alpha status, It will follow semver which means we will introduce breaking changes only in major versions (= major redesign, so not anytime soon).

If you use a component from Cosmos, you can be sure that it will not break when you update Cosmos version.

---

3. When do we freeze the API? (versioning)

As a team not directly working on the product, we are also aware that we will not always know the needs of product. For this reason, some components will be released in an experimental mode first before they make it into stable.

The way we can do this is by having a explicit namespace: cosmos/next or cosmos/beta.

Certain components can start in the next namespace and then make it to stable root import, after which their API can not change.

import { Button, Form } from 'auth0-cosmos'
import { Stack } from 'auth0-cosmos/next'

---

4. What code do we ship? (packaging)

We can transpile + bundle all the components (with tokens) into one file that we ship. We can also simply ship the source files.

I think it makes more sense to ship source files because there will always be a bundler in the application cosmos is used in either hidden inside create-react-app or a custom webpack setup. By shipping the source we give the application developers more power in terms of transpilation and tree-shaking.

(create-react-app doesn't transpile node_modules yet)

Example: If the application only supports only the last 2 versions of browsers (manage does that), they have the opportunity to have smaller bundles by shipping ES6 code. We cannot take that call for them.

On a similar note, if the application uses styled-components already, we don't want to package it with cosmos as well and end up with 2 versions of it.

Update
Here's what we do: Transpile all files in cosmos but don't bundle them into one file, ship libraries we depend on with cosmos

5. Should we ship each component in a different npm package or ship cosmos as one package (packaging)

It's important to state that this is not a performance problem, we can

1. make the imports more explicit: import Button from 'auth0/cosmos/button'
2. make sure our code is tree-shakable and promote that

This is more a question of adoption and the resulting maintenance for teams. Let me explain it with an example:

Manage and Support center both start using cosmos at 0.0.1

🔜 From the feedback of the support center team, we add more features to certain components say Button and List, we keep releasing new versions, support center keeps updating, we reach 0.0.4

🔜 Now, the team from manage comes up with a small request for Dialog, we reach 0.0.5. To upgrade, they not only have to test the Dialog, but also whatever happened since 0.0.1 which can be a lot of work. (even when we promise no breaking changes)

Maybe, they would like to only upgrade Dialog because that's what they need. Companies with multiple big teams (like atlassian) have to allow for that. So they publish each component as a different package enabling team to pick updates they like and ignore the rest.

If not done right, this can introduce design inconsistency between components in the same application.

So here's the adoption question:

Would we like teams to buy into cosmos as a whole and upgrade versions regularly? If yes, then we should not ship each package as a component. If we want to allow selective updates, we should. It's an open question at this point.

[siddharthkp]

I think this issue can be closed. We have a version deployed with little/no issues