From 09291a484aa16873c2b8b0d3cba71c388935d0e6 Mon Sep 17 00:00:00 2001 From: Oleksii Date: Wed, 14 Aug 2019 07:56:45 +0000 Subject: [PATCH] add workspace loader flow for code contribution Signed-off-by: Oleksii --- CONTRIBUTING.md | 121 +++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 103 insertions(+), 18 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3688af8e3f..2f00a3ebef 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -12,39 +12,45 @@ Che is composed of multiple sub projects. For each projects we provide a *CONTRIBUTE.md* file describing how to setup the development environment to start your contribution. Most of the time, we encourage you to use Che to contribute to Che. - [eclipse/che](https://github.com/eclipse/che) (this repository) is the main project repository that contains: - - Che master: orchestrates the che workspaces with devfiles on Kubernetes - - Che dashboard: UI to manage workspaces, devfiles, etc. - - Che main container images: source code, dockerfiles to build our main docker images. Note that Che-theia related dockerfiles are located in che-theia repo. - - End2end test: source code of our integration tests. + - Che master: orchestrates the Che workspaces with devfiles on Kubernetes + - Che dashboard: UI to manage workspaces, devfiles, etc. + - Che main container images: source code, dockerfiles to build our main docker images. Note that Che-theia related dockerfiles are located in che-theia repo. + - End2end test: source code of our integration tests. - [che-theia](https://github.com/eclipse/che-theia): Theia IDE integrated in Che. - [chectl](https://github.com/che-incubator/chectl): The CLI to install Che, create and start workspaces and devfiles -- [che-plugin-registry](https://github.com/eclipse/che-plugin-registry): The default set of che plugins (vscode extension + containers) or editors that could be installed on any Che workspaces. +- [che-plugin-registry](https://github.com/eclipse/che-plugin-registry): The default set of Che plugins (vscode extension + containers) or editors that could be installed on any Che workspaces. - [che-devfile-registry](https://github.com/eclipse/che-devfile-registry): The default set of devfiles that would be made available on the Che dashboard stacks. -- [redhat-developer/devfile](https://github.com/redhat-developer/devfile): Contribute to the devfile documentation: https://redhat-developer.github.io/devfile/ +- [redhat-developer/devfile](https://github.com/redhat-developer/devfile): Contribute to the devfile documentation: `https://redhat-developer.github.io/devfile/` - [che-plugin-broker](https://github.com/eclipse/che-plugin-broker): The workspace microservice that is in charge of analyzing, preparing and installing the workspace components defined in a Devfile. - [che-operator](https://github.com/eclipse/che-operator): Che operator to deploy, update and manage K8S/OpenShift resources of Che. -- [che-docs](https://github.com/eclipse/che-docs): Eclipse Che documentation https://www.eclipse.org/che/docs/ source code. -- [che-website](https://github.com/eclipse/che-website): https://eclipse.org/che website source code. +- [che-docs](https://github.com/eclipse/che-docs): Eclipse Che documentation `https://www.eclipse.org/che/docs/` source code. +- [che-website](https://github.com/eclipse/che-website): `https://eclipse.org/che` website source code. - [che-workspace-client](https://github.com/eclipse/che-workspace-client): JS library to interact with a che-server. - [che-machine-exec](https://github.com/eclipse/che-machine-exec): Interface to execute tasks and terminals on other containers within a workspace. ## Devfile to contribute + We are trying to provide a devfile for each areas where you could contribute. Each devfile could be run on any Che instances to setup a *ready-to-code* developer environment. Beware that each of them may need a certain amount of memory. Devfile could be launched through a factory or [chectl](https://github.com/che-incubator/chectl) cli. ```bash $ chectl workspace:start -f devfiles/che-theia-all.devfile.yaml ``` + or + ```bash $ chectl workspace:start -f https://raw.githubusercontent.com/eclipse/che-theia/master/devfiles/che-theia-all.devfile.yaml ``` + or `https:///f?url=https://raw.githubusercontent.com/eclipse/che-theia/master/devfiles/che-theia-all.devfile.yaml` ## Contribute to ... + Let's cover the developer flow for theses projects: ### Dashboard + Dashboard source code is located in [/dashboard](./dashboard/) folder. It is an AngularJS application. Here is the developer workflow if you want to contribute to it: @@ -52,14 +58,13 @@ It is an AngularJS application. Here is the developer workflow if you want to co The devfile: [/dashboard/devfile.yaml](./dashboard/devfile.yaml) -In this section, we show how to setup a Che 7 environment to work on the che dashboard, and how to use it. +In this section, we show how to setup a Che environment to work on the Che dashboard, and how to use it. For the whole workflows, we will need a workspace with such containers: - Dashboard Dev container (a.k.a dash-dev): Dashdev is a all in one container for running commands such as build, test or start the dashboard server. All containers have `/projects` folder mounted, which is shared among them. - Developer workflow: 1. Start the workspace with the devfile, it is cloning Che repo. @@ -68,51 +73,131 @@ Developer workflow: 4. Run unit test 5. Start dashboard server and preview - #### Step 1: Start the workspace with the devfile, it is cloning Che repo. + In this section we are going to start a new workspace to work on che-theia. The new workspace will have few projects cloned: `theia` and `che-theia`. It will also setup the containers and commands in the `My workspace` view. We will use these commands in the next steps. The devfile could be started using `chectl`: +```bash +$ chectl workspace:start -f https://raw.githubusercontent.com/eclipse/che/master/dashboard/devfile.yaml ``` -chectl workspace:start -f https://raw.githubusercontent.com/eclipse/che/master/dashboard/devfile.yaml -``` + At workspace start, Che will clone Che source code (including the dashboard) - - #### Step 2: Build In this section we are going to build the dashboard project. -You can use the che command `dashboard_build` (command pallette > Run task > … or containers view) +You can use the Che command `dashboard_build` (command pallette > Run task > … or containers view) Basically, this command will run ```bash # [dash-dev] $ yarn ``` + #### Step 3: Code ... #### Step 4: Run unit test (optional) + In this step, we will run the Dashboard unit tests: -You can use the che command `dashboard_test` (command pallette > Run task > … or containers view) +You can use the Che command `dashboard_test` (command pallette > Run task > … or containers view) Basically, this command will run ```bash # [dash-dev] $ yarn test ``` + #### Step 5: Start dashboard server and preview + In this step, we will run the dashboard server and see the live reloadable preview. -You can use the che command `dashboard_dev_server` (command pallette > Run task > … or containers view) +You can use the Che command `dashboard_dev_server` (command pallette > Run task > … or containers view) + ```bash # [dashboard_dev_server] $ node_modules/.bin/gulp serve --server= ``` +### Workspace Loader + +Workspace loader source code is located in [/workspace-loader](./workspace-loader/) folder. +Here is the developer workflow if you want to contribute to it: + +#### Devfile for workspace loader development + +The devfile: [/workspace-loader/devfile.yaml](./workspace-loader/devfile.yaml) + +This section shows you how to setup a Che environment to work on the Che Workspace Loader, and how to use it. +For the whole workflows, we will need a workspace with Workspace Loader Dev container (a.k.a ws-loader-dev). Dev container is all in one container for running commands such as build, test or start the workspace loader server. + +Developer workflow: + +#### Step 1: Start the workspace with the workspace-loader devfile + +In this section we are going to start a new workspace to work on workspace loader. The new workspace will clone the `Eclipse Che` project. Containers and commands could be found in the `My workspace` view. We will use these commands in the next steps. + +The workspace could be created and started from a devfile using `chectl`: + +```bash +$ chectl workspace:start --devfile=https://raw.githubusercontent.com/eclipse/che/master/workspace-loader/devfile.yaml +``` + +or as a factory `https:///f?url=https://raw.githubusercontent.com/eclipse/che/master/workspace-loader/devfile.yaml` + +At workspace start, Che will clone Che source code (including the workspace-loader) + +#### Step 2: Install workspace-loader dependencies + +Use the command `[workspace loader] install dependencies` + +or + +```bash +# [ws-loader-dev] +$ yarn +``` + +#### Step 3: Code workspace-loader + +Now you can make changes in Workspace Loader + +#### Step 4: Build workspace-loader + +Use the command `[workspace loader] run build` + +or + +```bash +# [ws-loader-dev] +$ yarn build +``` + +#### Step 5: Run workspace-loader unit tests (optional) + +Use the command `[workspace loader] run tests` + +or + +```bash +# [ws-loader-dev] +$ yarn test +``` + +#### Step 6: Start workspace loader server and preview + +Use the command `[workspace loader] start dev server` + +or + +```bash +# [ws-loader-dev] +$ yarn start --disable-host-check --public=$(echo ${server.dev-server} | sed -e s/https:\\/\\/// -e s/http:\\/\\/// -e s/\\///) --host="0.0.0.0" --env.target=${CHE_API_EXTERNAL%????} +``` ### Che server a.k.a WS master + To be provided soon.