LoopBack comprises dozens of GitHub repositories. Beyond the core repositories such as loopback, loopback-datasource-juggler, and loopback-boot, there are dozens of ancillary modules, that fall into three main categories:
- Connectors:
loopback-connector-rest,loopback-connector-mongodb,loopback-connector-soap, dozens of others; see LoopBack data source connectors. - Examples:
loopback-getting-started, many others; see Tutorials and examples. - Components:
loopback-component-oauth2,loopback-component-storage,loopback-component-passport, and so on.
NOTE: These READMEs are currently not being reused; rather the content is largely duplicated in the doc pages. Ultimately, though, these should be single-sourced, as priorities permit.
Each of these repositories has its own documentation in the repository README file. It makes sense to maintain the documentation there, close to the code, where it can be updated as part of related pull requests to that module. At the same time, it’s useful to aggregate all the documentation on this site. So, essentially we want to keep the module-specific documentation in the README as well as in this repo (loopback.io).
Instead of manually copying the README files from their “home” repositories, we use Bash scripts to automate the process. This enables each repository to maintain its own README and yet also provide the same information in the documentation, with a single source to avoid divergence or duplication of effort.
Important:
Due to this system of single-sourcing READMEs, to update one of the files in the readmes directory, you must open a PR in the corresponding repository, not here in the loopback.io repo. For example, to update the file pages/lb3/readmes/loopback-connector-mongodb.md, edit strongloop/loopback-connector-mongodb/README.md and open a PR in the loopback-connector-mongodb repository.
There are two Bash scripts:
update-readmes.sh- Gets example, connector, and component READMEs and puts them intopages/en/lb3/readmes.update-community-readmes.sh- Gets community READMEs and puts them intopages/en/community/readmes.
We have a Jenkins pipeline that runs the scripts whenever there is a commit to the loopback.io repository.
As for READMEs from loopback-next, they are always fetched together with other doc files. To add a new README to the docs, just create a new page with README layout in the loopback-next repository. For an example of the README layout, see here.