CONTRIBUTING.md

Contributing to Lux

Thank you for your interest in contributing to Lux! This document will help answer any outstanding questions you may have about the contribution process.

Please read the Code of Conduct before you participate in community.

Contents

• Ways to Contribute
• Reporting a Bug
• Requesting a Feature
• Development Workflow
• Writing Documentation
• Submitting a Pull Request
• Helpful Links and Information

Ways to Contribute

There are many ways you can contribute to the Lux community. We value each type of contribution and appreciate your help.

Here are a few examples of what we consider a contribution:

• Updates to source code
• Answering questions and chatting with the community in the Gitter room
• Filing, organizing, and commenting on issues in the issue tracker
• Teaching others how to use Lux
• Community building and outreach

Reporting a Bug

While bugs are unfortunate, they're a reality in software. We can't fix what we don't know about, so please report liberally. If you're not sure if something is a bug or not, feel free to file a bug anyway.

If you have the chance, before reporting a bug, please search existing issues, as it's possible that someone else has already reported your error. This doesn't always work, and sometimes it's hard to know what to search for, so consider this extra credit. We won't mind if you accidentally file a duplicate report.

Opening an issue is as easy as following this link and filling out the fields.

Security

If you find a security bug in Lux, send an email with a descriptive subject line to lux+security@postlight.com. If you think you’ve found a serious vulnerability, please do not file a public issue or share in the Lux Gitter room.

Your report will go to Lux's core development team. You will receive acknowledgement of the report in 24-48 hours, and what our next steps will be to release a fix. If you don’t get a report acknowledgement in 48 hours, contact Zachary Golba directly.

A working list of public, known security-related issues can be found in the issue tracker.

Requesting a Feature

To request a change to the way that Lux works, please open an issue in the RFCs repository rather than this one. New features and other significant API changes must go through the RFC process. For more information about the RFC process, head over to the lux-rfcs repository.

Development Workflow

This section of the document outlines how to build, run, and test Lux locally.

Building

When a project that is built with Lux executes a command like lux serve it goes through a build process. During this build process, Lux core is also being built. The output of this build process is a bundled JavaScript file that includes only the parts of Lux core and your application that you actually use. This is known as tree shaking. Although saving bytes may not be necessary for server side applications, tree shaking can still help optimize application start time amongst other things. Technically speaking, Lux is not built until a project that uses Lux is built—so why build in development at all? Well, some parts of Lux core are required to be built and executable in the targeted Node.js version(s).

To build the required modules for local development, execute the following commands:

# Clone this repository from GitHub.
git clone https://github.com/postlight/lux.git

# Navigate into the root of this repository.
cd lux

# Install local dependencies.
npm install

# Clean any build artifacts remaining from prior builds. This step is optional
# and only makes sense if a build has already occurred.
npm run clean

# Run the build tools.
npm run build

# Symlink the lux-framework to the global node_modules directory. This ensures
# that the "lux" command will use the files we just built instead of another
# install.
npm link

For general debugging and sanity checking code changes to Lux core, you can use the test app. To run the test app for the first time, execute the following commands:

# Navigate to the test/test-app directory from the root of this repository.
cd test/test-app

# Create the database schema.
lux db:create

# Run any pending database migrations.
lux db:migrate

# Seed the database with fixtures.
lux db:seed

# Run the application server.
lux serve

Testing

First make sure you have built lux locally and it is symlinked to your global node_modules directory. Once you have completed the build steps, execute the following command:

# Run the test suite from the root of this repository.
NODE_ENV="test" npm test

NOTE:

Subsequent executions of the test suite can run without going through the build steps again.

Code Style

Flow

The Lux codebase is statically typed with Flow. This helps prevent many common bugs including ones caused by unexpected type coercions.

If you have never written JavaScript with Flow or TypeScript before, you may have a bit of a learning curve. If you get stuck on something, feel free to ask a question in the postlight/lux and/or facebook/flow Gitter room. We recommend installing an editor plugin with autocompletion and realtime error checking. Below you will find a few example plugins for many common editors.

• flow-for-emacs (Emacs)
• flow-for-vscode (Visual Studio Code)
• FlowIDE (Sublime Text)
• Nuclide (Atom)
• vim-flow (Vim)
• Webstorm

You can find more information about Flow and how to use it in the Flow documentation.

JavaScript

We use a slightly modified version of the Airbnb JavaScript Style Guide. To enforce this, all pull requests must pass ESLint before they can merge.

Markdown

In addition to enforcing a JavaScript style guide, we also require that markdown files pass remarklint with the recommended preset. This helps keep our markdown tidy, consistent, and compatible with a range of markdown parsers used for generating documentation.

Node.js Version Requirements

Lux is built against Node >= v6. Since this is the latest LTS release and the version we run in our CI environments, we recommend you use it when working on the Lux codebase.

If you use nvm to manage Node.js versions and zsh (like Oh-My-ZSH), you can have nvm switch to the correct Node.js version automatically when you cd into this repository. To do so, add the following to your ~/.zshrc file:

# place this after nvm initialization!
autoload -U add-zsh-hook
load-nvmrc() {
  local node_version="$(nvm version)"
  local nvmrc_path="$(nvm_find_nvmrc)"

  if [ -n "$nvmrc_path" ]; then
    local nvmrc_node_version=$(nvm version "$(cat "${nvmrc_path}")")

    if [ "$nvmrc_node_version" != "N/A" ] && [ "$nvmrc_node_version" != "$node_version" ]; then
      nvm install
    fi
  elif [ "$node_version" != "$(nvm version default)" ]; then
    echo "Reverting to nvm default version"
    nvm use default
  fi
}
add-zsh-hook chpwd load-nvmrc
load-nvmrc

Writing Documentation

Improvements to documentation are a great way to start contributing to Lux. The sources for the official documentation are generated from source code comments and markdown files that live in this repository.

The Guide section of the official documentation is generated from markdown files found in files within the./guide directory of this repository.

The API reference section of the official documentation is generated from source code comments found in files within the ./src directory of this repository.

Submitting a Pull Request

Want to make a change to Lux? Submit a pull request! We use the "fork and pull" model described here.

Before submitting a pull request, please make sure:

• You have added tests for modifications you made to the codebase.
• You have updated any documentation in the source code comments for APIs that you may have changed.
• You have no linter errors to correct after running npm run lint.
• You have no type errors to correct after running npm run flow.
• You have run the test suite via npm test and it passed.

Commit Style

Commit messages should follow the format outlined below:

prefix: message in present tense

Prefix	Description

   chore | does not effect the production version of the app in any way.
    deps | add, update, or remove a dependency.
    docs | add, update, or remove documentation. no code changes.
      dx | improve the development experience of lux core.
    feat | a feature or enhancement. can be incredibly small.
     fix | a bug fix for something that was broken.
    perf | add, update, or fix a test.
refactor | change code, but not functionality.
   style | change code style, like removing whitespace. no functional code changes.
    test | add, update, or fix a test.

Code Reviews

Once you have submitted a pull request, a member of the core team must review it before it is merged. We try to review pull requests within 3 days but sometimes fall behind. Feel free to reach out to someone in the postlight/lux room on Gitter if you have not received a review after 3 days.

Helpful Links and Information

Some useful places to look for information are:

• The postlight/lux room on Gitter
• The official guides and documentation
• Example applications in this repository

Adapted from Contributing to Node.js , Contributing to Rust, and ThinkUp Security and Data Privacy.