Skip to content

Latest commit

 

History

History
192 lines (130 loc) · 7.8 KB

CONTRIBUTING.md

File metadata and controls

192 lines (130 loc) · 7.8 KB
Raw

Contributing

🎉 Thanks for taking the time to contribute to Dockta! 🎉

Table of Contents

General contribution guidelines

Development

General contribution guidelines

Stencila is an open-source community-driven project. We encourage and welcome contributions from all community members.

These are mostly guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in a pull request.

If you are comfortable with Git and GitHub, you can submit a pull request (PR). In Stencila we follow a commonly used workflow for contributing to open source projects (see also GitHub instructions).

If you have specific suggestions or have found a bug, please create an issue.

If you don't want to use GitHub, please tell us what you think on our chat on Gitter or have your say on our our Community Forum.

Licensing and code of conduct

By contributing, you agree that we may redistribute your work under our license. Everyone involved with Stencila agrees to abide by our code of conduct.

Get in touch!

You can chat with the team at our [community forum][community-forum], on Twitter @Stencila, Gitter, or email to [email protected]

Development

Getting started

Development environment

Dockta is implemented as a Node.js package in order to make it easier to integrate with other Stencila components written also in this language. Therefore, in order to develop Dockta you need to have Node.js installed on your machine, along with npm. The core of the source code of Dockta is written using TypeScript which is then compiled into JavaScript.

To get started,

git clone https://github.com/stencila/dockta
cd dockta
npm install

To run the CLI during development use, npm run cli -- <args> e.g.

npm run cli -- compile tests/fixtures/dockerfile-date/Dockerfile

This uses ts-node to compile and run Typescript on the fly so that you don't need to do a build step first.

You might also want to create an alias for convieience during development:

alias dockta="npm run cli --"

Architecture

Dockta implements a compiler design pattern. Source files are parsed into a SoftwareEnvironment instance (the equivalent of an AST (Abstract Syntax Tree) in other programming language compilers) which is then used to generate a Dockerfile which is then built into a Docker image.

The parser classes e.g. PythonParser, RParser scan for relevant source files and generate SoftwareEnvironment instances. The generator classes e.g. PythonGenerator, RGenerator generates a Dockerfile for a given SoftwareEnvironment. DockerGenerator is a super-generator which combines the other generators. DockerBuilder class builds DockerCompiler links all of these together.

For example, if a folder has single file in it code.py, PythonParser will parse that file and create a SoftwareEnvironment instance, which DockerGenerator uses to generate a Dockerfile, which DockerBuilder uses to build a Docker image.

Linting and testing

Please check that your changes pass linting and unit tests,

npm run lint # or, make lint
npm test # or, make text

Use npm test -- <test file path> to run a single test file.

You can setup a Git pre-commit hook to perform these checks automatically before each commit using make hooks.

You can check that any changes you've made are covered 🏅 by unit tests using,

npm run cover # or, make cover
open coverage/lcov-report/index.html

Documentation generation

If you've been working on in-code documentation 🙏 you can check that by building and viewing the docs,

npm run docs # or, make docs
open docs/index.html

Contributors list

This project follows the all-contributors specification. Please add contribuors, including yourself, using,

# Add new contributor <username>, who made a contribution of type <contribution>
npm run contributors:add <username> <contribution>
# Example:
npm run contributors:add octocat code,doc
# Regenerate the readme table
npm run contributors:generate

See the list of contribution codes here.

Commit messages

Please use conventional changelog style commit messages e.g. docs(readme): fixed spelling mistake. See the specifications for full details. This help with automated semantic versioning. To make this easier, Commitzen is a development dependency and can be used via npm or make:

npm run commit # or, make commit

Continuous integration

Linting, test coverage, binary builds, package builds, and documentation generation are done on Travis CI. semantic-release is enabled to automate version management: minor version releases are done if any feat(...) commits are pushed, patch version releases are done if any fix(...) commits are pushed. Releases are made to NPM and Github Releases.

Python System Dependencies

We maintain a list of system packages (e.g deb/rpm) that a Python packages installed through pip might need to include. These are in the file PythonSystemDependencies.json. If you find a Python package that relies on a system library you can add the lookup to this file; the mapping is in the format lookup[pythonPackageName][pythonVersion(str)][packagingType][osVersion]. The "default" can be used as a fallback at any level. For example:

  • ["pypackage"]["2"]["deb"]["trusty"] = ["some-deb-package"]
  • ["otherpypackage"]["3"]["rpm"]["default"] = ["some-rpm-package"]
  • ["thirdpypackage"]["default"]["default"]["default"] = ["some-consistent-package", "some-other-package"]

Using the router and server

The Express router provides PUT /compile and PUT /execute endpoints (which do the same thing as the corresponding CLI commands). You can serve them using,

npm start

Or, during development using,

npm run server

A minimal example of how to integrate the router into your own Express server,

const app = require('express')()
const { docker } = require('@stencila/dockta')

const app = express()
app.use('/docker', docker)
app.listen(3000)