[Spike] Explore how to roll out experimental features #2676
Comments
|
@strongloop/loopback-next, thoughts? |
|
@dhmlau The experimental flag means we release features with different stages like what Node.js does: https://nodejs.org/api/documentation.html#documentation_stability_index (@bajtos could correct me if I am wrong) For "Encourage composition packages", my understanding is we treat features as separate modules that's not part of core. |
+1, that's my idea too.
IMO, experimental flags is a suboptimal approach as it does not offer enough flexibility both to framework users (they cannot pick a specific version of the experimental feature) and framework maintainers (we have to keep experimental code in our main codebase). Node.js core is in a different position than we are. Node.js is shipped as a single binary, it is not possible to build a custom Node.js version by combining multiple components. LoopBack is composed from multiple optional building blocks from the beginning, e.g. users can choose to exclude I'd like us to try to implement as many experimental features as possible in standalone packages.
These two approaches can be combined together:
The more I think about this topic the more reluctant I am to keep experimental code in the main loopback-next monorepo. The aspect most important to me: how to prevent experiments from negatively effecting our "main" work on production-grade codebase and our milestone plans.
With a new monorepo hosting experimental code, my four concerns are solved:
|
|
For experimental features, I think we want to:
With the reasons above, I'd prefer proposal 4. The repo name could be something else, but that's implementation details. :) @raymondfeng mentioned that setting up automated testing/CI for proposal 4 is more complicated. That might be something to consider too, but I don't have enough knowledge to comment on that. |
|
Let's start with the simplest case here - adding a new module such as
To support this case, we can do the following:
|
|
@raymondfeng please expand your proposal to describe how do you envision to address the concerns I raised in my earlier comment.
|
|
+1 to keeping the experimental code outside of
In this approach, it's easier to keep the experimental code up-to-date with the non-experimental code and it would be easier to open a PR to land them in the master We can add a link to the Overall, imo this approach mixes the best of having the code outside the main |
|
From the points made above, and from the graduation criteria for experimental features, I think setting up a new repository that can have lighter CI (e.g. just Travis instead of Travis/appveyor) and standalone code coverage would be good. Issues coming in for experimental features will also be triaged there. Discussing the topic with the team here, one concern is migration of the experimental code from the standalone repo to loopback-next once we deem it production ready. In that case, keeping the experimental features within loopback-next might make sense since it's all in one repository (plus we can use new labels in loopback-next for experimental stuff). Another point made in our discussion is when users have code in their experimental packages that also needs some changes in our core modules, then how it becomes tricky to integrate/test alongside without having the experimental code in our monorepo. I think we agree on rolling out these features, but not quite sure which direction to follow, so perhaps we could conduct a spike on the approach to take using one of the in-progress experimental packages. |
|
I like the idea of a separate repo for experimental stuff. |
|
For the replaceable/plugable functionalities, I prefer to have them in a separate monorepo like While for features that affect the core module, like So I would suggest we treat features differently. |
|
+1 for |
|
@hacksparrow, do you mean to have the experimental packages reside in |
Personally, I'd like to use a slightly different criteria to decide where to land a new component.
One of the goals of loopback-labs is to allow new components to be developed incrementally, starting with small bits and pieces that may not even work together well. So for example, to develop GraphQL server layer, we can start by landing a small pull request adding the new package and perhaps an empty (dummy) server class. Then we can incrementally add more meat to this walking skeleton, keeping individual pull requests small and easy to review. If we said that GraphQL should go directly to loopback-next because it's on our roadmap, then the first pull request would have to include a meaningfully-complete implementation with 90%+ code coverage, which may cause the pull request to be too large to be reviewed effectively. |
|
@dhmlau yes, everything in |
|
To get started, I have created https://github.com/strongloop/loopback-labs from https://github.com/strongloop/loopback-next. We can decide:
|
|
Had a discussion with the team, most of us are more inclined for a separate repo to contain the experimental features. Here is the summary:
Questions:
Acceptance CriteriaBased on the above conclusion, the spike should exercise the workflow to show how it works bi-directionally, with the use of a dummy experimental feature:
@strongloop/loopback-maintainers, I've put the summary of our discussion here. Please edit directly if there's anything I missed or that's incorrect. Please also review the acceptance criteria that was generated from the meeting. Thanks! |
|
As I was reviewing #2834, I realized there is one more area to research: how can experimental packages contribute documentation (hand-written markdown files) to https://loopback.io/doc/en/lb4 and API documentation to http://apidocs.loopback.io or the new apidocs solution proposed in #2834 |
dhmlau
changed the title
|
Update The diagram and work flow of how Let's continue the spike based on it. |
|
Answer acceptance criteria questions: Having experimental features inside
|
ComparisonGuide for using Con of using
Pro of using
|
|
Update Had a meeting with loopback team to update our findings, here is a summary of key points:
Given this branching strategy, adding lab packages in A PR is created to update the work flow of adding feature in The work flow for the Next to do:
|
👍 Few more tasks to consider:
Re 2: For example, we can set the convention that experimental packages contain all documentation in their README and then leverage README inclusion to show the docs on our site. |
|
The work flow of experimental features is documented in https://github.com/strongloop/loopback-next/blob/labs/base/LABS.md follow up story created as #3039. |
Capturing the discussion we had so far regarding this experimental feature and turning it in a discussion thread on GitHub for others to chime in.
Why experimental features
While we want to make sure high quality of code goes into our codebase which may take many iterations, releasing the features as
experimentalallow the community to try out and we can get early feedback, and improve the code incrementally.Discussion Topic 1 - Where the experimental code resides or how to indicate as experimental
Proposal 1: Introduce experimental flag
The experimental flag means we release features with different stages like what Node.js does: https://nodejs.org/api/documentation.html#documentation_stability_index
Proposal 2: Encourage composition packages
Create a separate package within the loopback-next monorepo but release only as
0.x.yto indicate it's experimentalProposal 3: Use master-experimental branch
Use
masteras the production ready branch (stay unchanged). Create amaster-experimentalbranch for the "master" of experimental features.Pros:
Cons:
masterandmaster-experimentalbranch. (might be able to set up a CI job for rebase)Proposal 4: a separate monorepo
loopback-labsPros:
Discussion Topic 2 - Acceptance criteria and graduation criteria
We need to determine on:
cc @strongloop/loopback-maintainers
The text was updated successfully, but these errors were encountered: