lcp-compose Developer Guide

Installing lcp-compose from git

First, you will need to create a virtualenv:

mkvirtualenv lcp-compose

Clone the lcp-compose repo from github.

git clone https://github.com/Points/lcp-compose.git lcp-compose/

Then, in the lcp-compose directory, install dependencies and itself:

cd lcp-compose
make install-dev

After this, you should have lcp-compose command available to you. Along with development dependencies installed.

The next time you use lcp-compose, you just need to activate the virtualenv first (without recreating it):

workon lcp-compose

Install git commit hook

Every commit should be linked to a JIRA story. To help you faciliate this contract, a git commit hook is provided in githooks/ folder that you can install with:

cd githooks && ./install.sh

Afterwards, if you name your branch after a JIRA story id, suc as DBGTLCP-9999-make-lcpcompose-great-again, when you do git commit, the JIRA story id will automatically be prepended to your commit message.

FAQ

How do I build lcp-compose as a Python Package

Make sure you increment the version number in version_number.txt, and then run

make package

This will produce a source distribution as well as a wheel under dist/ folder.

How to send a PR

Secrets for Points on-premises services (such as docker registry and devpi) are encrypted using travis' environment variable encryption feature. The encrypted variables are not visible in the fork or the pull requests from the fork. As a result, devs cannot send a PR from their own fork to the lcp-compose project and have travis build it. All PRs must be from a branch on the lcp-compose repo.

How to encrypt secrets

Travis allows secrets to be encrypted and stored in the .travis.yml file and be version controlled. In order to add or change an encrypted variable, follow the following steps:

  1. Sign in travis using your Points github account credentials
  2. Install the travis cli tool locally: gem install travis
  3. Create a github personal token to be used by travis
    • In github, go to settings -> developer settings -> personal access tokens
    • Create a personal access token, and give the permissions: admin:repo_hook, repo, user
  4. Save the access token, and login travis cli using travis login --pro --github-token <TOKEN>
  5. Encrypt the values using the command: travis encrypt --pro ENV=value --add. This will encrypt and save it to .travis.yml
  6. Read the docs to understand how to correctly escaping on the command line.

Documentation

Documentation is available under /docs folder. Documentations should be written in Markdown format.

Preview docs

To preview documentation, first, install requirements for docs:

pip install -r requirements/docs.txt

Then, use make preview to preview the docs.

Publish docs

Use the following Makefile target to publish new docs:

make publish-docs

This will build the documentation, check out an orphaned branch called gh-pages, install the generated files to the root folder, commit all changes and push to the origin/gh-pages branch. This will trigger github to build the documentation and make it available at https://points.github.com/lcp-compose.

CLI Reference

CLI Reference documentation is auto generated from the docstrings of each invoke task configured in the program. The script scripts/api_docs.py is executed at doc build time to inspect the invoke program and retrieve the docstrings. It will then use the jinja2 template found at docs/cli.md.j2 to generate the final Markdown document.