-
Notifications
You must be signed in to change notification settings - Fork 65
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs(CONTRIBUTING): Introduce the contributing guide
Signed-off-by: Vitaliy Gulyy <[email protected]>
- Loading branch information
1 parent
5ab0061
commit e7f9584
Showing
5 changed files
with
216 additions
and
55 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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 | ||
} |