Skip to content

Commit

Permalink
docs(CONTRIBUTING): Introduce the contributing guide
Browse files Browse the repository at this point in the history
Signed-off-by: Vitaliy Gulyy <[email protected]>
  • Loading branch information
vitaliy-guliy committed Aug 14, 2019
1 parent 5ab0061 commit e7f9584
Show file tree
Hide file tree
Showing 5 changed files with 216 additions and 55 deletions.
139 changes: 139 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,139 @@
# Contributing

The development flow includes:

- [create workspace, clone sources](#create-workspace-clone-sources)
- [build](#build)
- [run tests](#run-tests)
- [generate devfile](#generate-devfile)
- [create workspace](#create-workspace)
- [package binaries](#package-binaries)
- [push changes, provide pull request](#push-changes-provide-pull-request)

## Create workspace, clone sources

To create a workpace you can use [devfile](devfile.yaml):

```
$ chectl workspace:start -f https://raw.githubusercontent.com/che-incubator/chectl/master/devfile.yaml
```

> See more about [devfile](https://redhat-developer.github.io/devfile)
After starting the workspace Theia will clone sources of `chectl` to `/projects/chectl` directory. Sources will be accessible in `theia-dev` and `dev` containers.

#### 'theia-dev' container

This container is used only for running Theia editor and does not take part in the following flow.

#### 'dev' container

`chectl` is written in TypeScript. For that this container has preinstalled software to be able to build, test and launch `chectl`.

You workspace is initialized with a list of commands described in the [devfile](devfile.yaml) in `commands` section. Those command allow you to:
- build
- test
- generate devfile
- create workspace
- package binaries
- format sources

You can run commands in one of three ways.

1. It an easiest way is to use `My Workspace` panel at the left. You can launch commands by simple click.

2. `Terminal => Run Task...` menu. You can fin and pick a command in the appeared command palette.

3. Manually by opening a terminal in the `dev` container and running commands in `/projects/chectl` directory.

## Build

```bash
yarn
```

Open `My Workspace` panel at the left and launch `Build` command. It will run `yarn` command in `/projects/chectl` directory inside `dev` container. The command will install all necessary dependencies and compile the project. Upon successfull assembly, a new `bin` directory will appear in project directory and will have two files: `run` and `run.cmd`.


## Run tests

```bash
yarn test
```

Tests for `chectl` are written using `jest` framework.
To run tests, go to `My Workspace` panel, find and launch `Test` command. The command will run `yarn test` inside `dev` container.
Testing summary will be printed to the output.


## Run

```bash
./bin/run --help
```

To test ensure `chectl` is built successfully, launch `Run` command. It wil run `chectl` with `--help` directive.


## Generate Devfile

```bash
./bin/run devfile:generate \
--name="chectl-test" \
--language="typescript" \
--dockerimage="eclipse/che-theia-dev:next" \
--git-repo="https://github.com/che-incubator/chectl.git" \
--command="yarn" > /projects/sample.devfile
```

We added a command which generates a simple devfile `/projects/sample.devfile`. Workspace created from this devfile will have `chectl` project with running TypeScript language server. There will be a dev container for building, running and debugging `chectl`. It will be possible to easily build `chectl` by running `yarn` command from `My Workspace`.

## Create Workspace

> We still found a solution how to create a workspace by a command from container.
```bash
# upload devfile content to clbin, save link into a file
cat /projects/sample.devfile | curl -F 'clbin=<-' https://clbin.com > /projects/clbin

# run chectl, pass the given URI
uri=$(cat /projects/clbin); ./run workspace:start -f=$uri
```

To create a workspsace run `Create Workspace` command from `My Workspace`. The command will upload content of the generated `/projects/sample.devfile` devfile to https://clbin.com. And then will use given public URI to the devfile when running `chectl`.

> See more about [clbin](https://clbin.com/)
## Package binaries

For packaging binaries we use https://github.com/oclif/dev-cli. It generates packaged for Linux, Windows and MacOS operation systems and puts the result in `dist/channels/stable` directory.
To start packaging just run `Package Binaries` commands from `My Workspace`. It will run the following in `/projects/chectl` directory.

```bash
yarn oclif-dev pack
```

> Note: you need to build your `chectl` before by `yarn` command, or install all node packages by running `npm install` in `/projects/chectl` directory.
## Push changes, provide Pull Request

`chectl` is using several Pull Request checks
- [Conventional Commits](https://conventionalcommits.org) convention for the commit messages.
There is a required Pull Request check named `Semantic Pull Request` that is ensuring that all commits messages are correctly setup. In order to merge a Pull Request, it has to be green.

- Signed Commits. Each commit needs to have the `Signed-off` part
It needs to be added on the commit message:
```
feat(hello): This is my first commit message
Signed-off-by: John Doe <[email protected]>
```

Git even has a -s command line option to append this automatically to your commit message:
```
$ git commit -s -m 'feat(hello): This is my first commit message'
```

- Unit tests with Travis-CI. It will ensure that `yarn test` command is passing.

All these checks are mandatory in order to have the Pull Request merged.
41 changes: 0 additions & 41 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -361,44 +361,3 @@ git clone https://github.com/che-incubator/chectl.git
cd chectl
```

Build the source code and run `chectl`:

```bash
yarn
./bin/run --help
```

Run the tests:

```bash
yarn test
```

Package the binary

```bash
yarn pack
pkg . -t node10-linux-x64,node10-macos-x64,node10-win-x64 --out-path ./bin/
```

## Providing Pull Request
`chectl` is using several Pull Request checks
- [Conventional Commits](https://conventionalcommits.org) convention for the commit messages.
There is a required Pull Request check named `Semantic Pull Request` that is ensuring that all commits messages are correctly setup. In order to merge a Pull Request, it has to be green.

- Signed Commits. Each commit needs to have the `Signed-off` part
It needs to be added on the commit message:
```
feat(hello): This is my first commit message
Signed-off-by: John Doe <[email protected]>
```

Git even has a -s command line option to append this automatically to your commit message:
```
$ git commit -s -m 'feat(hello): This is my first commit message'
```

- Unit tests with Travis-CI. It will ensure that `yarn test` command is passing.

All these checks are mandatory in order to have the Pull Request merged.
66 changes: 54 additions & 12 deletions devfile.yaml
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
apiVersion: 1.0.0

metadata:
name: chectl
name: chectl-dev

projects:

Expand All @@ -12,17 +12,11 @@ projects:

components:

- alias: git
type: dockerimage
image: sunix/git-devtools
mountSources: true
memoryLimit: 256M

- alias: dev
type: dockerimage
image: eclipse/che-theia-dev:next
mountSources: true
memoryLimit: 1G
memoryLimit: 3G

- id: redhat/vscode-yaml/latest
type: chePlugin
Expand All @@ -33,17 +27,65 @@ components:

commands:

- name: yarn
- name: Build
actions:
- type: exec
component: dev
command: yarn
command: >
yarn
workdir: /projects/chectl

- name: yarn test
- name: Test
actions:
- type: exec
component: dev
command: yarn test
command: >
yarn test
workdir: /projects/chectl

- name: Run
actions:
- type: exec
component: dev
command: >
./run --help
workdir: /projects/chectl/bin

- name: Generate Devfile
actions:
- type: exec
component: dev
command: >
./run devfile:generate \
--name=chectl-test \
--language=typescript \
--dockerimage=eclipse/che-theia-dev:next \
--git-repo=https://github.com/che-incubator/chectl.git \
--command="yarn" > /projects/sample.devfile;
cat /projects/sample.devfile
workdir: /projects/chectl/bin

- name: Create Workspace
actions:
- type: exec
component: dev
command: >
cat /projects/sample.devfile | curl -F 'clbin=<-' https://clbin.com > /projects/clbin;
uri=$(cat /projects/clbin); ./run workspace:start -f=$uri
workdir: /projects/chectl/bin

- name: Package Binaries
actions:
- type: exec
component: dev
command: >
yarn pack-binaries
workdir: /projects/chectl

- name: Format Sources
actions:
- type: exec
component: dev
command: >
yarn format
workdir: /projects/chectl
7 changes: 5 additions & 2 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,8 @@
"ts-jest": "^24.0.2",
"ts-node": "^8",
"tslint": "^5",
"typescript": "^3.5"
"typescript": "^3.5",
"typescript-formatter": "7.2.2"
},
"engines": {
"node": ">=8.0.0"
Expand Down Expand Up @@ -127,9 +128,11 @@
"posttest": "tslint -p test -t stylish",
"tslint-fix": "tslint --fix -p test -t stylish",
"prepack": "rm -rf lib && rm -rf tsconfig.tsbuildinfo && tsc -b && oclif-dev manifest && oclif-dev readme",
"pack-binaries": "oclif-dev pack",
"test": "jest",
"test-watch": "jest --watchAll",
"version": "oclif-dev readme && git add README.md"
"version": "oclif-dev readme && git add README.md",
"format": "tsfmt -r --useTsfmt tsfmt.json"
},
"types": "lib/index.d.ts",
"jest": {
Expand Down
18 changes: 18 additions & 0 deletions tsfmt.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
{
"baseIndentSize": 0,
"newLineCharacter": "\n",
"indentSize": 4,
"tabSize": 4,
"indentStyle": 4,
"convertTabsToSpaces": true,
"insertSpaceAfterCommaDelimiter": true,
"insertSpaceAfterSemicolonInForStatements": true,
"insertSpaceBeforeAndAfterBinaryOperators": true,
"insertSpaceAfterKeywordsInControlFlowStatements": true,
"insertSpaceAfterFunctionKeywordForAnonymousFunctions": true,
"insertSpaceAfterOpeningAndBeforeClosingNonemptyParenthesis": false,
"insertSpaceAfterOpeningAndBeforeClosingNonemptyBrackets": false,
"insertSpaceAfterOpeningAndBeforeClosingTemplateStringBraces": false,
"placeOpenBraceOnNewLineForFunctions": false,
"placeOpenBraceOnNewLineForControlBlocks": false
}

0 comments on commit e7f9584

Please sign in to comment.