interlincx-guide.md

Contributing Guide

Welcome to Interlincx! Please review the following guidelines for contributing to Interlincx projects. Use your best judgment, and feel free to propose changes to this document.

Testing

Tests are run with npm test. We use Travis CI on our projects to run tests on all commits. Please make sure that npm test runs without errors or failures before pushing.

We use tape for testing. All test files should start by assigning NODE_ENV environment variable, like this: process.env.NODE_ENV = 'test', regardless of test discovery strategy.

Logging

All API requests are logged so that we can see how the app is being used and identify bad behavior.

Critical errors (anything we should be notified about) should be logged with console.error(err) where err is an Error object (strings do not have stacktraces). Attach the request id to the error so that it easy to see the context when diagnosing an issue.

Logging in production should be used only if it will be helpful in production. Do not leave development logging in your commits. If a certain type of logging is useful in development, but not production, and you would like to commit it, use debug.

For client-side code, never leave console.log() in a commit to production. However, you may use debug.

App Structure

(package.json scripts)

• npm start to run the app
• npm test to run the tests (e.g. node test/index.js)
• npm run dev to run the app with development helpers (reloading etc...)

(client-side specific)

• Anything public/static goes in /public (index.html, built JS, images, etc...)
• running npm run build should output bundle file into aforementioned /public directory

Code style

This repository uses standard to maintain code style and consistency and avoid style arguments. npm test should also run standard so that CI fails when style does not meet the requirements.

Other style points:

• Code should be simple and explicit.
• Callbacks are preferred over Promises.
• Functional style is preferred to OOP.
• Prefer small modules that do one thing well and avoid large frameworks.
• If a module exports a single function use module.exports = ... not module.exports.thing = ....
• When writing a module use this order:
  • External dependencies (e.g. require('http'))
  • Internal dependencies (e.g. require('./api'))
  • Any declarations or actions absolutely needed before module.exports
  • module.exports
  • Everything else should be ordered "high-level" to "low-level" and "first-use" to "last-use" -- low-level helper functions should be at the bottom.
• Use descriptive variable names.
• Code and comments should stay within 80 character line length.
• Prefer .forEach() over for loops.
• Default name for a callback is cb.
• Use single line conditionals when possible.
• Use early returns when possible.

function getAsyncThing (cb) {
    someAsyncWork(function (err, result) {
      if (err) return cb(err)
      if (!result) return cb(new Error('No result found.'))
      cb(null, result)
    })
}

Git

• Use ~/.gitignore to ignore files related to your environment / editor.
• Use present tense in commits "upgrade dependencies" or "introduce custom error object"
• Use Conventional Commits:

feat: add hat wobble (#227)
^--^  ^------------^ ^----^
|     |              |
|     |              +-> Issue number
|     |
|     +-> Summary in present tense.
|
+-------> Type: chore, docs, feat, fix, refactor, style, or test.

• Changes to projects are achieved through issues and pull requests (PRs).
• Issues are created first to describe the change that is needed (add a new endpoint to an API, fix a bug, refactor a module, cleanup, etc...).
• Next, a PR is opened to address the issue. Prefix the git branch name with the issue number (e.g. 197-add-get-publisher).
• Pull request title should state the goal of pull request clearly.
• Pull request description should describe how the PR will achieve that goal.
• In the description, use the phrase "Closes #XX" (where XX is the issue number). If done properly Github will automatically close the issue when the PR is merged.
• Each PR should be as small and simple as possible to prevent bugs and make code review as quick as possible. Do not include unrelated changes. Open a separate issue/PR for those.
• When you want specific persons to review your pull request, mention them using @ syntax in the end of the description (e.g. "@davidguttman, please review.")
• You may use as many commits as you would like while working on a pull request. However, before it can be merged it must be squashed to a single commit. This commit should have either the issue or PR number added to the end (e.g. "feat: add get publisher endpoint (#197)"). This way it is easy to find the context for a change in the git log.

Authentication and Authorization

Our projects use Authentic for authentication. Please review Intro to Authentic for a summary of how it works.

Reporting bugs

Make a bug report about any part of a project that didn't work as expected. Try also to give some context to a problem you are encountering, and give as much details as possible like steps to reproduce, and the manifestation on it, like logs screenshots or such.

Ideally bug report should contain following:

1. Any important context info that might matter to behavior/manifestation (like OS, node version, npm version, NODE_ENV)
2. Exact steps to reproduce
3. Expected behavior
4. Actual behavior
5. Manifestation record if possible (logs/screenshots)

• When writing about logs/code use markdown syntax.
• Open an issue for that particular project on github.

Suggesting Enhancements

Should you think that we could make a project work better, please feel free to suggest a way. We love feedback and we wish to keep things simple and improve them over time. We are building this bottom up and trying to evolve it and make more performant over time.