5.8 KiB
Contributing to Kitematic
Thanks for contributing and supporting the Kitematic project!
Before you file an issue or a pull request, read the following tips on how to keep development of the project awesome for all of the contributors:
Table of Contents
- Mac Prerequisites
- Windows Prerequisites
- Getting Started
- Architecture
- GitHub Issues
- Pull Requests
- Code Guidelines
- Testing
- License
Prerequisites for developing Kitematic on Mac
You will need to install:
- The Docker Toolbox
- Node.js
- Wine
brew install wine
(only if you want to generate a Windows release on OS X) - The latest Xcode from the Apple App Store.
Prerequisites for developing Kitematic on Windows
You will need to install:
- The Docker Toolbox
- Node.js
- Open a command prompt (
cmd
) and run the commandmkdir ~/AppData/Roaming/npm
- Visual Studio 2013 Community (or similar) - You do not need to install any optional packages during install.
- Python
Getting Started
npm install
To run the app in development:
npm start
Running npm start
will download and install the Docker client,
Docker Machine, Docker Compose
the Boot2Docker iso,
Electron.
Building & Release
npm run release
Unit Tests
npm test
Architecture
Overview
Note: This architecture is work in progress and doesn't reflect the current state of the app, yet!
Kitematic is an application built using electron and is powered by the Docker Engine. While it's work in progress, the goal is to make Kitematic a high-performance, portable Javascript ES6 application built with React and Flux (using alt. It adopts a single data flow pattern:
╔═════════╗ ╔════════╗ ╔═════════════════╗
║ Actions ║──────>║ Stores ║──────>║ View Components ║
╚═════════╝ ╚════════╝ ╚═════════════════╝
^ │
└──────────────────────────────────────┘
There are three primary types of objects:
- Actions: Interact with the system (Docker Engine, Docker Machine, Registries, Hub, etc)
- Views: Views make up the UI, and trigger available actions.
- Stores: Stores store the state of the application.
and since Kitematic has a large amount of interaction with outside systems, we've added utils:
- Utils: Utils interact with APIs, outside systems, CLI tools and generate. They are called by user-generated actions and in return, also create actions based on API return values, CLI output etc.
Guidelines
- Avoid asynchronous code in Actions, Stores or Views. Instead, put code involving callbacks, promises or generators in utils or actions.
GitHub Issues
Please try and label any issue as:
bug
: clearly a defect or unwanted behavior (errors, performance issues)enhancement
: making an existing, working feature better (UI improvements, better integration)feature
: an entirely new feature. Please work on roadmap features.
Before creating an issue, please:
-
Search the existing issues to see if an issue already exists (and if so, throw in a handy 👍)!
-
Make sure you're running the latest version of Kitematic. The bug may already be fixed!
-
Explain how to reproduce the bug. This will save maintainers tons of time!
Please be as detailed as possible. Include a description of your environment and steps on how to reproduce a bug.
Pull Requests
We're thrilled to receive pull requests of any kind. Anything from bug fix, tests or new features are welcome.
That said, please let us know what you're planning to do! For large changes always create a proposal. Maintainers will love to give you advice on building it and it keeps the app's design coherent.
Pull Request Requirements:
- Includes tests
- Signed Off
Testing
Please try to test any new code.
- Tests can be run using
npm test
- Kitematic uses the Jest framework by Facebook. To keep tests fast, please mock as much as possible.
Code Guidelines
Javascript
Kitematic is es6 ready. Please use es6 constructs where possible, they are powerful and make the code more succinct, understandable and fun.
- Semicolons
- 2 spaces (no tabs)
Checking Javascript code standards with ESlint
Run npm run lint
before committing to ensure your javascript is up to standard. Feel free to suggest changes to the lint spec in .eslintrc
.
We designed Kitematic to be easy to build, extend and distribute for developers.
License
By contributing your code, you agree to license your contribution under the Apache license.