Contributing to LoopBack documentation

We welcome contributions to LoopBack documentation!

Page Contents

How LoopBack documentation works

LoopBack documentation is sourced in both the strongloop/loopback.io and strongloop/loopback-next GitHub repositories, and this site is generated using Jekyll and GitHub pages. Some pages are copied from the loopback-next repository’s master branch into loopback.io’s gh-pages branch, where this site is published from. Don’t use the master branch in the loopback.io repository.

When contributing documentation to the loopback-next repository, a new version of @loopback/docs must be published to npm before the changes appear live. There is a script that runs automatically at 3pm EST to propogate the changes to the loopback.io site.

All the pages from the loopback.io repo are in the pages directory and the pages from the loopback-next are stored in the docs/site directory, which are then copied to pages/en/lb4 in loopback.io. Every page also has an Edit this page button at the bottom that links to the page in the GitHub repo.

For information on contributing to translations in languages other than English, see Translation.

To contribute a change

Follow these steps:

Click on Edit this page (top of page) to fork the repo.
Edit the page or pages as needed.
Commit to your fork/branch.
Open a PR for your changes. If there is an associated issue, please reference it in your PR. Check out Submitting a pull request to LoopBack 4 for detailed instructions.

Important: When you submit your PR, be sure to agree to the contributor license agreement; see below.

We attempt to review and merge PRs as soon as possible; in general, we’ll try to do so within 24 hours during the business week. Please allow longer over weekends or holidays.

Contribution Methods

To simplify the contribution process and encourage community contribution, we are gradually switching the contribution method from Contributor License Agreement (CLA) to Developer Certificate of Origin (DCO). See our blog about switching to DCO.

Over time, most of the LoopBack repositories will be using DCO. The best way to find out is to check the Contributing section of the README in the repository that you want to contribute.

Developer Certificate of Origin (DCO)

As an alternative to CLA, a Developer Ceritifcate of Origin (DCO) is a more lightweight contribution method. According to Wikipedia:

Instead a signed legal contract, a DCO is an affirmation that the source code being submitted originated from the developer, or that the developer has permission to submit the code.

The full text of DCO:

Developer Certificate of Origin
Version 1.1

Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
1 Letterman Drive
Suite D4700
San Francisco, CA, 94129

Everyone is permitted to copy and distribute verbatim copies of this
license document, but changing it is not allowed.


Developer's Certificate of Origin 1.1

By making a contribution to this project, I certify that:

(a) The contribution was created in whole or in part by me and I
    have the right to submit it under the open source license
    indicated in the file; or

(b) The contribution is based upon previous work that, to the best
    of my knowledge, is covered under an appropriate open source
    license and I have the right under that license to submit that
    work with modifications, whether created in whole or in part
    by me, under the same open source license (unless I am
    permitted to submit under a different license), as indicated
    in the file; or

(c) The contribution was provided directly to me by some other
    person who certified (a), (b) or (c) and I have not modified
    it.

(d) I understand and agree that this project and the contribution
    are public and that a record of the contribution (including all
    personal information I submit with it, including my sign-off) is
    maintained indefinitely and may be redistributed consistent with
    this project or the open source license(s) involved.

It can also be found: https://developercertificate.org/.

Signing off commits using DCO

For GitHub repositories using DCO, you need to sign off each commit. To sign off, you can use the -s flag or adding Signed-off-By: Name<Email> in the commit message. For example,

git commit -s -m "feat: my commit message"

You can also set up alias in .gitconfig to sign off automatically. To do that, you can:

Open the file ~/.gitconfig
Add the following:
```
  [alias]
  cm = commit -s -m
```
When committing a change, instead of using git commit command, use git cm.

To amend the commit message to include the sign off, you can run:

git commit --amend -s

Contributor License Agreement (CLA)

Note: Some repositories were not migrated from CLA to DCO yet, the information below applies only to those repositories that are still using CLA.

Like many open source projects, you must agree to the contributor license agreement (CLA) before we can accept (merge) your changes. See the loopback-connector CLA.

In summary, by submitting your code or doc contributions, you are granting us a right to use that code/content under the terms of this agreement, including providing it to others. You are also certifying that you wrote it, and that you are allowed to license it to us. You are not giving up your copyright in your work. The license does not change your rights to use your own contributions for any other purpose.

Contributor License Agreements are important because they define the chain of ownership of a piece of software. Some companies won’t allow the use of free software without clear agreements around code ownership. That’s why many open source projects collect similar agreements from contributors. The LoopBack CLA is based on the Apache CLA.

What to work on

We use GitHub issues to track tasks and bugs. In general:

For issues around documentation content (that is the actual information), open an issue in the relevant repository, such as loopback, loopback-datasource-juggler, loopback-connector-xxx, and so on.
- Under loopback-next, use the Docs label.
For issue around the documentation site, layout, or UX, open an issue in the loopback.io repository.

For general guidelines on creating issues, see Reporting issues.

It is best practice to search first to make sure someone else hasn’t already logged your issue. Run these helpful GitHub queries to see open documentation issues:

Open documentation issues in any strongloop repository.
Open issues labeled “needs doc”: these are typically code issues that need to be documented, as opposed to specific doc tasks/problems.

References

The site theme is derived from Tom Johnson’s Documentation Theme for Jekyll. We’ve modified and extended it substantially to suit our needs. For more information, see the other pages in this section.

Other technical references:

Tags: community contributing getting_started