This article explains the process and guidelines for contributing code to the LoopBack project.
Page Contents

How to contribute to the code

You can contribute in a number of ways:

  • Report an issue. Reporting it first will ensure that it is in fact an issue, and there is not already a fix in the works.
  • After reporting a bug, go one step further and fix it.
  • Ensure that your effort is aligned with the project’s roadmap by talking to the maintainers, especially if you are going to spend a lot of time on it.
  • Adhere to code style outlined in the style guide.
  • Agree to the Contributor License Agreement.
  • Submit a pull request through Github.
  • Run tests; see Running tests.

Where to start

If you are looking to contribute, but aren’t sure where to start, review open pull requests for the module. For example, LoopBack open pull requests for 2.x and 3.x and that for 4.x.

Also, please read the source code before contributing. If something is confusing, poorly documented, poorly commented, or could otherwise be improved: open a GitHub issue and link to the file and line of code with a useful description of what you would like to see or think is missing.

Another place to look is to find our issues on GitHub with good first issue tag. See good first issue in our repositories.

LoopBack versions

LoopBack maintains a current version, a long-term support (LTS) version, and a maintenance version. New features go into the current version; bug fixes can go into the active LTS and maintenance LTS versions, depending on the nature of the bug. For more information, see Long-term support.

Note that we are no longer accepting features for LoopBack versions that are in either LTS versions. If you are in doubt, please open an issue to discuss first with the maintainers before spending too much time on implementation.

Submitting a pull request

Follow the GitHub Flow. If you are new to GitHub, it is recommended to take a look at this Getting into open source for the first time article.

  1. Create a GitHub issue for large changes and discuss the change there before coding. You can skip this step and submit the pull request for minor changes.
  2. Fork the repository on GitHub.
  3. Create a branch for you change/feature off of the master branch.
  4. Make your change. Remember to update tests as well as code! Always run all the tests to assure nothing else was accidentally broken. For bugs, adding a failing test and submitting a pull request usually leads to the bug being fixed quickly. For features, include tests that cover the entire feature. For remote / client facing features, include integration tests in the [loopback-example-app](](https://github.com/strongloop/loopback-example-app).
  5. Check for unnecessary whitespace with git diff --check before committing.
  6. Make commits of logical units and push them to Github.
  7. Use a descriptive commit message, and follow 50/72 format.
  8. Use GitHub’s pull requests to submit the patch. Feel free to issue the pull request as soon as you have something partial to show and get reviewed. You can add more commits to your pull request as you are progressing on the implementation. The title of the pull request should start with “WIP” for “work in progress” when the pull request is not complete yet.
  9. Request a code review. Add a specific committer to speed up this process. (for example, @bajtos, @raymondfeng).
  10. Make any requested changes and push to your fork. Make sure your changes are still based on the latest code (use git rebase upstream/master).

How to rebase your branch

Our code base is always getting updated and being able to successfully rebase your PR is very important. Here are some simple steps to rebase your code:

  • Checkout your branch which you are submitting the pull request against git checkout <my_branch>
  • Add an upstream remote from your fork git remote add upstream <upstream_repo>
  • Fetch the latest from the upstream remote git fetch upstream
  • Rebase your code using the interactive mode git rebase -i upstream/master
  • If you are happy with the changes and there are no merge conflicts, push the code to your remote branch git push --force-with-lease origin <my_branch>

Running tests

All LoopBack projects follow the same convention for running tests. To run a projects test suite, change to the project’s directory and run:

npm test

Create example repositories

If you create an example repository for any usage demo, the name of repository should follow the following convention:

loopback{major_version}-example-{example_name}

Usually the {major_version} is the latest major version under development. If the example aims at a specific version of LoopBack, then use that number as the {major_version}. The {example_name} is a few words which briefly describes the functionality of the example, and joined with -.

For example, we build an example app for LoopBack 4 and name it as loopback4-example-shopping.

If a test is failing, open an issue on the appropriate repositories GitHub issues page.

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.

Additional information

Since LoopBack 2.x and 3.x have different codebase as LoopBack 4, there are some information that are specific to those versions. Please see:

Tags: community contributing getting_started