Spike: Move documentation to monorepo

[bajtos]

It would be great to have the documentation for loopback-next in the monorepo, so that we can keep documentation changes together with all other changes (runtime, CLI templates, API docs, etc.).

Spike Goals

Assuming the monorepo has a docs package:

• Where will it live?
• What technologies will it use?
• How will we update it?
• Can we make it a self-contained testable site? (like the current loopback.io's local jekyll run)

[bajtos]

I think the important (and possibly difficult) requirement is that we want a single place aggregating documentation for all major versions of LoopBack (2.x, 3.x, 4.x and beyond). If we keep the docs in the monorepo, then we need a solution that can fetch markdown files from different monorepo branches (master, 4.x, etc.). I am not sure if the current approach leveraging GitHub pages and static-site generator supports such workflow. Maybe if we switched from GitHub pages to Netlify then we could leverage their Continuous Deployment (docs)?

[raymondfeng]

There is preliminary support to pull in markdown files from git/npm into loopback.io repo: https://github.com/strongloop/loopback.io/blob/gh-pages/update-v4-readmes.sh. It supports different branches.

One thing missing is to relink markdown files if they reference each other.

[b-admike]

Problem Description

It would be great to have the documentation for loopback-next in the monorepo,
so that we can keep documentation changes together with all other changes
(runtime, CLI templates, API docs, etc.).

Current Approach Overview

Aggregated documentation for LoopBack 2.x, 3.x, and 4.x lives in loopback.io
module. Each release has static pages which have info on different features as
.md files. Changes to readmes from the different repositories associated with
different releases are picked up by bash
scripts
and commited to loopback.io as part of Jenkins' builds as slnode. Any
documentation update for LoopBack requires a PR to be submitted in loopback.io
for the specific feauture/fix it aims to address. To learn more, here it how it
works.

Assumptions/considerations

• @loopback/docs to house static pages from loopback.io pertaining to
  LoopBack4 content.
• source of truth to be @loopback/docs, so documentation updates should not be
  made in loopback.io. That is, updates go only one way; from @loopback/docs
  to loopback.io.
• Use master branch in loopback-next as the current release version. Thus,
  when we release LoopBack v5, docs for LoopBack4 will be contained in 4.x
  branch

Proposal

• [EDIT: not part of revised proposal] Strip out minimal needed js/css/html etc. files to run a website for lb4 docs
  from loopback.io. Landing page will be the current
  http://loopback.io/doc/en/lb4/. This is going to be used for testing changes
  to the docs in loopback-next before being promoted to loopback.io. Tests
  will be local jekyll runs as they currently are run for loopback.io. We
  could also run them as part of Netlify's Continuous
  Deployment feature (it's
  included under their free offering!). Their support for
  Webhooks would allow us to bake it
  into our pipeline. We can also use http2live, which is an open source static web site
  hosting service which comes in a module and invoked using CLI. It can run as
  part of CI, but discarding of stale instances would be manual. Another
  alternative is surge, but it does not offer a lot for
  free, so would need to pay $13/month for things like Unlimited Publishing.
• Create a new @loopback/docs package in loopback-next
  • top level -> same as
    pages/en/lb4
    in loopback.io
  • the rest of the package will use
    get-md-docs and filter out
    certain .md files such as those in test
    folders
    and mimic monorepo structure
• Create a script (or modify existing ones) to pull changes from
  @loopback/docs into loopback.io

Spike Questions

1. Where will it live?
   A new package @loopback/docs as part of loopback-next monorepo.
2. What technologies will it use?
   Current stack used at loopback.io (Jekyll, Liquid, etc.), get-md-docs
   module created by @kjdelisle, possibly Netlify or http2live.
3. How will we update it?
   We will update it as part of our feature, fix, etc. PR in loopback-next.
4. Can we make it a self-contained testable site? (like the current
   loopback.io's local jekyll run)
   Yes, it's possible to do so as outlined in the Proposal.

[bajtos]

@loopback/docs to house static pages from loopback.io pertaining to
LoopBack4 content.

I would prefer to host our documentation files in docs folder of our monorepo. Why would we want to create a new npm package @loopback/docs instead? What are the benefits of this new package, and what would be the downsides of keeping docs files in /docs instead?

EDIT: docs folder is referring to this: https://github.com/strongloop/loopback-next/tree/master/docs

[bajtos]

The proposal looks mostly good to me. I am missing one answer though: how are we going to trigger propagation of docs updates from loopback-next to loopback.io repository? I understand get-md-docs can do the job of pulling changes, but how are we going to execute that script? What conditions are we going to use - will we update our docs whenever loopback-next@master branch changes, or wait until the changes are published to npmjs.org? Where are we going to run get-md-docs script - do we have a machine provisioned in cloud that can run the script for us? IIRC, we have a Jenkins pipeline configured for loopback.io right now, are we going to keep using it? Are there any changes needed in that pipeline to make it able to pick changes made to multiple branches of loopback-next (master, eventually also v4.x, v5.x, etc.).

[kjdelisle]

A possibility would be setting up a script to poll for changes against loopback-next@master and then run the script to refresh the documentation. If jekyll is running in incremental mode, it can refresh the changes without having to take the site down!

The downside to this would be that there is no staging area for the documentation, but I think it would be preferable to knocking the site down (I'm not saying that those are the only two choices, but fixing that problem separately would require additional effort)

[raymondfeng]

We can use github webhooks to watch https://developer.github.com/v3/activity/events/types/#releaseevent.

Another option is to pull versions of @loopback/docs from npmjs in a similar way as we deal with apidocs.

[b-admike]

@bajtos @kjdelisle @raymondfeng thank you for your valuable feedback. I went back and revisited my proposal. I've talked to @rmg as well and we have good support for automating doc updates from other repositories (aligns with @kjdelisle's suggestion) . However, it cannot make the PR for us with the doc updates automatically. It would commit the doc changes whenever there are open PRs against gh-pages on loopback.io. We can fill this gap by leveraging scripts we have that do similar things. Another option is to make use of Git submodules, although I have not tried it out, to make the changes. From the web page:

The simplest model of using submodules in a project would be if you were simply consuming a subproject and wanted to get updates from it from time to time but were not actually modifying anything in your checkout.

@bajtos to answer your question:

how are we going to trigger propagation of docs updates from loopback-next to loopback.io repository? I understand get-md-docs can do the job of pulling changes, but how are we going to execute that script? What conditions are we going to use - will we update our docs whenever loopback-next@master branch changes, or wait until the changes are published to npmjs.org? Where are we going to run get-md-docs script - do we have a machine provisioned in cloud that can run the script for us? IIRC, we have a Jenkins pipeline configured for loopback.io right now, are we going to keep using it? Are there any changes needed in that pipeline to make it able to pick changes made to multiple branches of loopback-next (master, eventually also v4.x, v5.x, etc.).

Propagation of docs would have to be triggered via the build periodically setting for the Jenkins job responsible for updating the docs (https://ci.sl.strongloop.com/job/sl-org/job/loopback.io/job/gh-pages/). I discussed it with Ryan, and he suggested that running it in an hourly interval wouldn't hurt. As of using get-md-docs, Ryan provided a script that does the same thing in shell, so it can run as part of the doc update pipeline on Jenkins. It should be able to support picking up changes from multiple branches of loopback-next with minor modifications.

[b-admike]

@kjdelisle @raymondfeng @virkt25 @bajtos @dhmlau We held a meeting with @jannyHou and @shimks where I went over my proposal in detail. @jannyHou had another proposal which aims to see if Jekyll/Liquid/GitHub pages support sourcing content from remote locations instead of on disk files. This would essentially eliminate the need to sync between loopback-next and loopback.io. I did not take that into account when I was doing my spike. How should we move forward in this case? What are your thoughts on the current proposal and do you think we should explore the remote sourcing option? Follow up task if we are to choose the current proposal is at #1114.

[raymondfeng]

I don't think how to replicate files into loopback.io is a blocker. At least we can run a script as part of the Jenkins pipeline to pull versions from @loopback/docs (assuming that we publish docs as a npm module).

[raymondfeng]

FYI: https://github.com/strongloop-internal/apidocs.strongloop.com/tree/master/lib

We can mimic how apidocs works:

1. Get all npm versions for @loopback/docs to build a pull-down menu so that we can switch between versions

2. Download a given version from npm into the directory

3. Rebuild Jekyll site

[b-admike]

As for @jannyHou's proposal, Jekyll does not have the ability to source its content from remote locations according to its configuration page. @raymondfeng how would the versioning work for @loopback/docs? As in, what do we call a minor, patch, or major bump for the module? Is the current proposal sufficient in your opinion or should we look into doing what apidocs does? What benefits do we get from mimicking apidocs?

[raymondfeng]

The versioning scheme for @loopback/docs probably doesn't matter so much here as long as new versions will be published to npm when there are changes.

I expect that we create a script to pull the latest version(s) from npm @loopback/docs to update loopback.io.

[virkt25]

I'm a +1 for ensuring loopback.io contains docs for latest released version and isn't ahead of the release. I just don't know if we need a new package to accomplish that.

AFAIK, Travis can check master on merge to see if the commit was a release commit (based on the publish commit message) and based on that we can update loopback.io.

Creating a package for @loopback/docs has some CONS:

• Users might expect to be able to install this package to get a local copy of the docs (in site form)
• It's not intuitive to look for docs in /packages/docs. (I think it's better for docs to be a top-level folder and that way it's obvious looking at the Repo what to expect in that folder).

[raymondfeng]

It's not intuitive to look for docs in /packages/docs. (I think it's better for docs to be a top-level folder and that way it's obvious looking at the Repo what to expect in that folder).

IMO, it's fine to have packages/docs as long as we link to it from the top-level README,

[dhmlau]

From the users' perspective,

• I'm not sure if there's any benefit of having different interim versions (e.g. 0.3.0, 0.3.1, 0.4.0, etc) of docs. If there are contents got removed in the latest version, that means it's not relevant and therefore, no point of viewing the older interim version.
• If @loopback/docs is really needed, can we make it private? If not, we can put some text on the usage of this package and not meant for serving up your own docs server.

[raymondfeng]

See #1122. It allows loopback-next/docs to be configured as a npm module so that lerna can publish it.

@dhmlau We'll start with latest version from npm first. As the code base evolves, we might want to maintain multiple branches/versions such as 4.1 and 4.2. It makes sense to allow loopback.io to serve multiple versions of docs.

I'm not sure why you are concerned that @loopback/docs being a public npm module. It's actually a good thing. I even think about adding strong-docs to preview the md files.

[dhmlau]

@dhmlau We'll start with latest version from npm first. As the code base evolves, we might want to maintain multiple branches/versions such as 4.1 and 4.2. It makes sense to allow loopback.io to serve multiple versions of docs.

I agree that ideally, it makes sense to server multiple versions of docs, when the code had changed significantly (like what we have for LB2 vs LB3). So, my next question is whether the plan is to have 4.1 of docs maps to 4.1 of @loopback/core? I'm just afraid that if we introduce too many branches, it puts burden on us to keep things up to date.
i.e. if the current version is 4.2 and someone found a bug in docs for 4.1 and it's applicable to the 4.2 as well. That means we are supposed to update both branches.

I'm not sure why you are concerned that @loopback/docs being a public npm module. It's actually a good thing. I even think about adding strong-docs to preview the md files.

My bad! I thought loopback-next/docs contains scripts to pull contents from different docs folders in other packages and push it to loopback.io.

[virkt25]

I'm not sure why you are concerned that @loopback/docs being a public npm module. It's actually a good thing. I even think about adding strong-docs to preview the md files.

+1

---

For versioning, I would (again) like to propose NOT using independent mode so all versions are locked and users have less ambiguity between version compatibility of modules. Plus a version of the @loopback/docs package would be reflective of the docs for that version across the board (all published packages).

[b-admike]

@raymondfeng I was just talking to @kjdelisle and he raised some concerns about top level docs folder being published as an npm module. Are we going to keep using the readme update script on loopback.io to fetch readmes? How can we capture other docs like the tutorial steps in example-getting-started?

[raymondfeng]

There are a few scripts in loopback.io repo:

1. The script to copy README files from other git repos. It will take care of example-getting-started unless we decide to move the tutorial into docs too.

2. The script to import docs from @loopback/docs.

Those two scripts are independent.

BTW, what are @kjdelisle's concerns?

[b-admike]

Yeah that's true. The README copy script wouldn't get https://github.com/strongloop/loopback-next/tree/master/packages/example-getting-started/docs though would it? But if we decide to move them to the top level docs then that's fine. It'd have been nice to get the docs as they are structured in the monorepo in loopback.io though.

[b-admike]

oh his concerns are basically what I asked :).

[b-admike]

Thank you all for chiming in. After all the discussion and the discoveries made from loopbackio/loopback.io#643, my proposal is as follows:

Assumptions/considerations

• @loopback/docs to house static pages from loopback.io pertaining to
  LoopBack4 content.
• source of truth to be @loopback/docs, so documentation updates should not be
  made in loopback.io. That is, updates go only one way; from @loopback/docs
  to loopback.io.
• Pull in the latest released version of @loopback/docs for copying content to loopback.io. This should also handle next major release(s) to loopback-next. @loopback/docs will be bumped to a new major version and we can modify the script to copy over the docs to create a new dir for e.g. lb5 under pages/en in loopback.io.

Proposal

• EDIT Move docs over to monorepo (done in docs: move documentation into monorepo #1100 and Docs/finish migration from loopback.io #1141)
• Create a new @loopback/docs package in loopback-next from top docs dir in loopback-next (done in chore: add docs as a package for loopback-next #1122)
  • top level -> same as
    pages/en/lb4
    in loopback.io
• imgs to contain content that will be copied over to pages/images/lb4 in loopback.io
• continue to use update-v4-readmes.sh script to copy over README and other .md files outside of docs dir in top level of loopback-next.
• Create a script (or modify existing ones) to pull changes from
  @loopback/docs into loopback.io (done in [WIP] Pull LoopBack 4 doc updates from loopback-next loopback.io#643)
• Use Travis' capability to deploy to GitHub Pages (see https://docs.travis-ci.com/user/deployment/pages/)

Spike Questions

1. Where will it live?
   A new package @loopback/docs as part of loopback-next monorepo.
2. What technologies will it use?
   Current stack used at loopback.io (Jekyll, Liquid, etc.), and Travis.
3. How will we update it?
   We will update it as part of our feature, fix, etc. PR in loopback-next. The changes are picked up by Travis builds and commited to gh-pages in loopback.io if successful.
4. Can we make it a self-contained testable site? (like the current
   loopback.io's local jekyll run)
   Yes, but since changes are reviewed in loopback-next, this is a nice to have. Travis won't commit changes to loopback.io if the build fails, so that's another fail-safe for us. If we see issues in loopback.io after deployment, we can always fix them in loopback-next.

If we all agree, then I can close this spike, and put any outstanding work in #1114.

[b-admike]

Closing as done. Follow up work in #1114.