n8n/CONTRIBUTING.md

203 lines
5.6 KiB
Markdown
Raw Normal View History

# Contributing to n8n
Great that you are here and you want to contribute to n8n
2019-08-21 14:18:09 -07:00
## Contents
- [Code of Conduct](#code-of-conduct)
- [Directory Structure](#directory-structure)
- [Development Setup](#development-setup)
- [Development Cycle](#development-cycle)
- [Create Custom Nodes](#create-custom-nodes)
- [Create a new node to contribute to n8n](#create-a-new-node-to-contribute-to-n8n)
2020-04-28 02:58:17 -07:00
- [Checklist before submitting a new node](#checklist-before-submitting-a-new-node)
- [Extend Documentation](#extend-documentation)
2020-04-28 02:58:17 -07:00
- [Contributor License Agreement](#contributor-license-agreement)
2019-08-21 14:18:09 -07:00
## Code of Conduct
This project and everyone participating in it are governed by the Code of
Conduct which can be found in the file [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
By participating, you are expected to uphold this code. Please report
unacceptable behavior to jan@n8n.io.
## Directory Structure
n8n is split up in different modules which are all in a single mono repository.
The most important directories:
2020-09-02 00:23:26 -07:00
- [/docker/image](/docker/images) - Dockerfiles to create n8n containers
- [/docker/compose](/docker/compose) - Examples Docker Setups
- [/packages](/packages) - The different n8n modules
- [/packages/cli](/packages/cli) - CLI code to run front- & backend
- [/packages/core](/packages/core) - Core code which handles workflow
execution, active webhooks and
workflows
:sparkles: Implement design system (#2050) * split up main, sass imports, import new nds * migrate most buttons * update sizes based on feedback * update copy buttons * update executions list * fix issues * force message box buttons * update warning color * update more buttons * wrap message box buttons * update last component * lint fixes * add build report step * breakout imports * set package.json * fix notification bug * clean up imports * use build directories directly * update imports * remove xl size * update number inputs * fix input width * update line height, fix icon bug * fix up editor * fix spacing between buttons * Reset line height * revert changes to this * revert changes * clean up button sizes * change to outline * update select height * update tooltip * remove build report step * clean up impl * remove regenerator runtime * add design system repo * apply editorconfig * apply editor config prettier * lint issue * switch to tabs * switch to single space * update eslintrc * remove git modules * update sass package * support dart sass * add build * update dependency * update contributing.md * set repo * update versions * add tslint step * update spacing to spaces, add dev step * add test step * add test step * update browser lint rc * remove .github * delete .gitignore * set comment for icons * remove preview link * update button interface * update types * set types * clean up intro * update intro * remove assets * move into preview * remove headline comment * reduce theme build * loading executions * match deps versions * match deps versions * fix lint issues * fix lint issues * update callback * disable codacy for docs.css * fix storybook issues * add design system to docker image * update spacing around delete sort button * set line height to stop juggling headline * update sizes * clean up vars * fix scss issues * update button vars * add shade color * fix button without click * fix buttons bug * fix bug with executions list * clean up theme * update link styling * fix typo * run prettier * :art: code format * :art: code format * 🔥 remove empty files * :sparkles: N8n 2284 new inputs (#2075) * implement inputs * prettier fixes * revert unnessary change * move input components and tooltip * remove form elements * move select * update input placements * update sizes * update credentails * clean up select size * fix caret issue * update inputs * clean up select * fix tags dropdown border * clean up tags input * fix workflow name bug * clean up select here * add sizes template * fix option caret * fix input sizes * update date input size * remove tags input override * update prop * update input size * center run data inputs * update disabled colors * update execution header * update scrollbar * update text area spacing * fix items in header * update run data tooltip * remove popover * update prefix positions * add filterable demo * address design issues * fix input issues, flip boolean input to text * update input sufffix colors * remove override * speed up switch, fix toggle spacing issue * update icon * remove icon classes * clean up inputs * clean up inputs with icons * update input spacing again * update suffix position * build * Add support for xlarge inputs * fix input issues * fix input issue * update listeners * update number inputs for settings * update append/prepend spacing * clean up inputs, set expression input as text * fix type errors * fix workflow number input * fix tags dropdown bug * fix bugs * fix menu item bug * remove font weight from link element * remove default * fix select option * fix contrast issues * allow overflow x for multi selects * fix icon * update options select * fix issue that resolves expression to null * update how actions are centered * fix up selects * update selects to support limiting size * update option styles * :zap: Apply suggestions BHesseldieck Co-authored-by: Ben Hesseldieck <1849459+BHesseldieck@users.noreply.github.com> * :art: code format Co-authored-by: Jan <janober@users.noreply.github.com> Co-authored-by: Ben Hesseldieck <1849459+BHesseldieck@users.noreply.github.com> Co-authored-by: Ben Hesseldieck <b.hesseldieck@gmail.com> * ⏪ Revert "🔥 remove empty files" This reverts commit e91ace4e52403f4a6b00b7be68b86fc48b7d8fef. * :zap: Remove private from n8n-design-system package * :art: Change to spaces to stay consistent with editorconfig & others package files * :zap: Fix year in license Co-authored-by: Ben Hesseldieck <1849459+BHesseldieck@users.noreply.github.com> Co-authored-by: Ben Hesseldieck <b.hesseldieck@gmail.com> Co-authored-by: Jan <janober@users.noreply.github.com> Co-authored-by: Jan Oberhauser <jan.oberhauser@gmail.com>
2021-08-29 04:36:17 -07:00
- [/packages/design-system](/packages/design-system) - Vue frontend components
- [/packages/editor-ui](/packages/editor-ui) - Vue frontend workflow editor
- [/packages/node-dev](/packages/node-dev) - CLI to create new n8n-nodes
- [/packages/nodes-base](/packages/nodes-base) - Base n8n nodes
2019-11-16 11:18:52 -08:00
- [/packages/workflow](/packages/workflow) - Workflow code with interfaces which
get used by front- & backend
## Development Setup
If you want to change or extend n8n you have to make sure that all needed
dependencies are installed and the packages get linked correctly. Here a short guide on how that can be done:
### Requirements
#### Build Tools
The packages which n8n uses depend on a few build tools:
Debian/Ubuntu:
```
apt-get install -y build-essential python
```
CentOS:
```
yum install gcc gcc-c++ make
```
Windows:
```
npm install -g windows-build-tools
```
#### lerna
n8n is split up in different modules which are all in a single mono repository.
To facilitate those modules management, [lerna](https://lerna.js.org) gets
used. It automatically sets up file-links between modules which depend on each
2019-08-14 00:14:24 -07:00
other.
So for the setup to work correctly lerna has to be installed globally like this:
```
npm install -g lerna
```
### Actual n8n setup
> **IMPORTANT**: All the steps bellow have to get executed at least once to get the development setup up and running!
Now that everything n8n requires to run is installed the actual n8n code can be
checked out and set up:
1. Clone the repository
```
git clone https://github.com/n8n-io/n8n.git
```
1. Go into repository folder
```
cd n8n
```
1. Install all dependencies of all modules and link them together:
```
lerna bootstrap --hoist
```
1. Build all the code:
```
npm run build
```
### Start
To start n8n execute:
```
npm run start
```
2019-08-14 00:14:24 -07:00
To start n8n with tunnel:
```
./packages/cli/bin/n8n start --tunnel
```
2019-08-14 00:14:24 -07:00
## Development Cycle
While iterating on n8n modules code, you can run `npm run dev`. It will then
automatically build your code, restart the backend and refresh the frontend
(editor-ui) on every change you make.
2019-08-14 00:14:24 -07:00
1. Start n8n in development mode:
```
npm run dev
```
1. Hack, hack, hack
1. Check if everything still runs in production mode
```
npm run build
npm run start
```
1. Create tests
1. Run all tests
```
npm run test
```
1. Commit code and create pull request
2019-08-14 00:14:24 -07:00
### Test suite
The tests can be started via:
```
npm run test
```
If that gets executed in one of the package folders it will only run the tests
of this package. If it gets executed in the n8n-root folder it will run all
tests of all packages.
2019-08-21 14:15:22 -07:00
## Create Custom Nodes
Learn about [using the node dev CLI](https://docs.n8n.io/nodes/creating-nodes/node-dev-cli.html) to create custom nodes for n8n.
2019-08-21 14:15:22 -07:00
More information can
be found in the documentation of [n8n-node-dev](https://github.com/n8n-io/n8n/tree/master/packages/node-dev), which is a small CLI which
helps with n8n-node-development.
2019-08-21 14:15:22 -07:00
## Create a new node to contribute to n8n
Follow this tutorial on [creating your first node](https://docs.n8n.io/nodes/creating-nodes/create-node.html) for n8n.
2020-04-28 02:58:17 -07:00
## Checklist before submitting a new node
There are several things to keep in mind when creating a node. To help you, we prepared a [checklist](https://docs.n8n.io/nodes/creating-nodes/node-review-checklist.html) that covers the requirements for creating nodes, from preparation to submission. This will help us be quicker to review and merge your PR.
## Extend Documentation
The repository for the n8n documentation on [docs.n8n.io](https://docs.n8n.io) can be found [here](https://github.com/n8n-io/n8n-docs).
## Contributor License Agreement
That we do not have any potential problems later it is sadly necessary to sign a [Contributor License Agreement](CONTRIBUTOR_LICENSE_AGREEMENT.md). That can be done literally with the push of a button.
We used the most simple one that exists. It is from [Indie Open Source](https://indieopensource.com/forms/cla) which uses plain English and is literally only a few lines long.
A bot will automatically comment on the pull request once it got opened asking for the agreement to be signed. Before it did not get signed it is sadly not possible to merge it in.