loopbackio / loopbackio/loopback.io

Move vendored assets to Git Submodules and `.gitignore` built assets

Open
#2,052 0 comments 0 reactions 0 assignees View on GitHub
ci developer-experience
Dominant language
HTML
Stars
276
Forks
382
Avg merge
6h 17m
Merged PRs (30d)
18

Description

The website has scripts which pulls data from GitHub and NPM:

- [`update-blog.sh`](https://github.com/loopbackio/loopback.io/blob/dc08f345c51fcf85cef04ad55c2a56e5812f2451/update-blog.sh)
Clones `loopbackio/loopback-blog` into `/blog`
- [`update-readmes.sh`](https://github.com/loopbackio/loopback.io/blob/dc08f345c51fcf85cef04ad55c2a56e5812f2451/update-readmes.sh)
Downloads READMEs from GitHub "raw" or NPM Registry into `/doc/en/[lb3|lb4|community]/readmes`
- [`update-lb4-docs.js`](https://github.com/loopbackio/loopback.io/blob/dc08f345c51fcf85cef04ad55c2a56e5812f2451/update-lb4-docs.js)
Copies pre-generated markdown API Docs from `@loopback/docs` into `/doc/en/lb4`

They pose some issues:
- **Accidental manual editing:** Contributors may accidentally contribute changes to these assets, only to be overridden by the CI pipeline.
- **Rate-limitng:** Contributors running `npm run build` -> `update-readmes.sh` may inadvertently update the local copies with GitHub "rate limit reached" error pages.
- **Unclear provenance:** As the `.git` directory is not preserved, the provenance of where and when exactly the assets were vendored is no clear.
- **Updates are reactive:** The assets are only re-vendored when a PR is merged.

Git Submodules solve this problem. Updates would be handled by [Renovate](https://github.com/renovatebot/renovate) instead, which would open PRs.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start by reading update-blog.sh, update-readmes.sh, and update-lb4-docs.js, then inspect how npm run build invokes them and how CI handles the generated assets. Define the submodule locations and the built paths that should be ignored. Done means the vendored sources have clear Git provenance, builds no longer overwrite tracked generated copies, and the existing site build still works.

Written by the indexing model from the issue text.

Assessment

Tech stack
git, github, nodejs, shell
Domain
build-system, documentation
Issue type
Refactor
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.