forked from che-incubator/chectl
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Updating CONTRIBUTING.md for eclipse-che/che#21363. Removed Generate …
…Devfile and Create Workspace sections and edited the command documentation to reflect how commands are currently run. Signed-off-by: Samantha Dawley <[email protected]>
- Loading branch information
Showing
1 changed file
with
34 additions
and
72 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 |
|---|---|---|
|
|
@@ -3,53 +3,45 @@ | |
| The development flow includes: | ||
|
|
||
| - [Contributing](#contributing) | ||
| - [Create workspace, clone sources](#create-workspace-clone-sources) | ||
| - [Start Workspace](#start-workspace) | ||
| - [Build](#build) | ||
| - [Run tests](#run-tests) | ||
| - [Run](#run) | ||
| - [Generate Devfile](#generate-devfile) | ||
| - [Create Workspace](#create-workspace) | ||
| - [Package binaries](#package-binaries) | ||
| - [Push changes, provide Pull Request](#push-changes-provide-pull-request) | ||
| - [Make Release](#make-release) | ||
|
|
||
| ## Create workspace, clone sources | ||
| ## Start Workspace | ||
|
|
||
| To create a workpace you can use [devfile](devfile.yaml): | ||
| To start a workpace from the [devfile](devfile.yaml) create a workspace URL by appending the chectl repo to the URL of your Che host: | ||
|
|
||
| ``` | ||
| $ chectl workspace:start -f https://raw.githubusercontent.com/che-incubator/chectl/main/devfile.yaml | ||
| https://<your-che-host>/f?url=https://github.com/che-incubator/chectl | ||
| ``` | ||
|
|
||
| > See more about [devfile](https://redhat-developer.github.io/devfile) | ||
| > See more about [devfile](https://devfile.io/docs/2.1.0/what-is-a-devfile) | ||
| > See more about [workspace URLs](https://www.eclipse.org/che/docs/stable/end-user-guide/starting-a-new-workspace-with-a-clone-of-a-git-repository/) | ||
| After starting the workspace Theia will clone sources of `chectl` to `/projects/chectl` directory. | ||
|
|
||
| `chectl` is written in TypeScript. For its development there is a dedicated `dev` container which has preinstalled software for comfortable development. That allows the developer to build, test and launch `chectl` inside the container. | ||
|
|
||
| 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 | ||
| Your workspace will be initialized with a list of commands described in the [devfile](devfile.yaml) `commands` section. The commands are: | ||
| - che: build | ||
| - che: test | ||
| - che: run | ||
| - che: package-binaries | ||
| - che: 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. | ||
| You can run commands through the Terminal menu by clicking `Terminal => Run Task...` then selecting the desired task in the che folder. | ||
|
|
||
| ## 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`. | ||
| Running the `che: build` command will run `yarn` in the `/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 | ||
|
|
@@ -59,7 +51,7 @@ 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. | ||
| To run tests, find and launch `che: test` command. The command will run `yarn test` inside `dev` container. | ||
| Testing summary will be printed to the output. | ||
|
|
||
|
|
||
|
|
@@ -69,41 +61,11 @@ Testing summary will be printed to the output. | |
| ./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/) | ||
| To test ensure `chectl` is built successfully, launch the `che: run` command. It wil run `chectl` with `--help` directive. | ||
|
|
||
| ## Package binaries | ||
| For packaging binaries, [oclif](https://github.com/oclif/dev-cli) is used. It generates packages 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. | ||
| For packaging binaries, [oclif](https://github.com/oclif/dev-cli) is used. It generates packages for Linux, Windows and MacOS operation systems and puts the result in the `dist/channels/stable` directory. | ||
| To start packaging just run the `che: package-binaries` command. It will run the following in `/projects/chectl` directory: | ||
|
|
||
| ```bash | ||
| yarn oclif-dev pack | ||
|
|
@@ -113,24 +75,24 @@ yarn oclif-dev pack | |
| ## 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. | ||
| `chectl` uses several Pull Request checks: | ||
| - The [Conventional Commits](https://conventionalcommits.org) convention for the commit messages. | ||
| There is a required Pull Request check named `Semantic Pull Request` that ensures 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]> | ||
| ``` | ||
| - Signed Commits. Each commit needs to be `Signed-off` in the commit message: | ||
| ``` | ||
| feat(hello): This is my first commit message | ||
| 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' | ||
| ``` | ||
| Signed-off-by: John Doe <[email protected]> | ||
| ``` | ||
|
|
||
| Use the git `-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. | ||
| - Unit tests with Travis-CI will ensure that the `yarn test` command passes. | ||
|
|
||
| All these checks are mandatory in order to have the Pull Request merged. | ||
|
|
||
|
|
@@ -147,4 +109,4 @@ To run the script with docker env | |
| $ ./run-script-in-docker.sh make-release.sh 7.0.0 | ||
| ``` | ||
|
|
||
| Commit the changes of the script and then, push release branch by overriding current remote release branch | ||
| Commit the changes of the script and then push the release branch by overriding current remote release branch. | ||