seg_yinzy
/
che-server
mirror of https://github.com/eclipse-che/che-server.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

chore: Updating README.md and CONTRIBUTING.md for che 7 (#13839) 

Updating README.md and CONTRIBUTING.md for che 7

Signed-off-by: Sun Tan <sutan@redhat.com>
7.20.x
Sun Seng David TAN 2019-08-02 14:49:25 +02:00 committed by GitHub
parent e6a3f0eea1
commit 840d154626
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 171 additions and 104 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

136
CONTRIBUTING.md
View File

@ -1,28 +1,118 @@
Filing Issues for Eclipse Che
=====================
Before Submitting an Issue
--------------------------
Check that [our issue database](https://github.com/eclipse/che/issues)
doesn't already include that problem or suggestion before submitting an issue.
If you find a match, you can use the "subscribe" button to get notified on
updates. You can leave a Thubms Up reaction to the original issue description to indicate that you have the same problem. Please Do not leave a "+1" or "I have this too" comment unless you are also adding material new information, as they
clutter the discussion.
# Contributing to Che
Writing Good Bug Reports and Feature Requests
---------------------------------------------
Please file a single issue per problem or feature request. Do not file issues that combine problems and feature requests. Please include all the environmental information and reproduction steps so that an engineer can reproduce it.
- [Other Che repositories](#other-che-repositories)
- [Devfile to contribute](#devfile-to-contribute)
- [Contribute to ...](#contribute-to-...)
- [Dashboard](#dashboard)
- [Che Server a.k.a WS master](#che-server-a.k.a-ws-master)
The community wants to help you find a solution to your problem, but every problem is unique. In order for an engineer to help resolve your issue, they need to be able to reproduce it. Reproducing your specific error may require significant information about your system and environment. Help us in advance by providing a complete assessment of your system and the steps necessary to reproduce the issue.
## Other Che repositories
Therefore:
* The details of your environment including OS version, container configuration, and the steps how you configure & run Che.
* Provide reproducible steps, what the result of the steps was, and what you would have expected.
* When providing reproduction steps, start with launching Che providing its configuration and every step taken to create the problem.
* A detailed description of the behavior that you expect.
* Animated GIFs are very helpful to show the problems for engineers.
* If there are UI issues or errors, please run the steps with the browser dev console open and send those logs with your report.
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.
Contributing Improvements
-------------------------
If you are interested in fixing issues and contributing directly to the code base, [please see our wiki](https://github.com/eclipse/che/wiki/How-To-Contribute).
- [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-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-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/
- [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-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://<CheInstance>/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 [<this.repo>/dashboard](./dashboard/) folder.
It is an AngularJS application. Here is the developer workflow if you want to contribute to it:
#### Devfile for dashboard development
The devfile: [<this.repo>/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.
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.
2. Build
3. Code ...
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`:
```
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)
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)
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)
```bash
# [dashboard_dev_server]
$ node_modules/.bin/gulp serve --server=<che_api_url>
```
### Che server a.k.a WS master
To be provided soon.

46
CUSTOMIZING.md
View File

@ -1,46 +0,0 @@
Eclipse Che is a platform for creating distributed developer tooling. There are numerous ways to extend, modify, and customize Eclipse Che. This document itemizes all of the resources available for customizing Che. We have documentation pages, tutorials, and specifications.
#### Stacks
A stack is the configuration of a runtime that can be used to power a workspace. Users choose the stack that powers a workspace within the user dashboard. Stacks have a recipe that defines how the container should be created and also meta data that defines the tags associated with the stack.
* [How to Use and Modify Stacks](https://www.eclipse.org/che/docs/stacks.html)
#### Recipes
A recipe defines the runtime of a workspace environment. Workspaces can have multiple environments, each with their own runtime. Che supports different kinds of runtimes, but the default is Docker letting us make use of [Dockerfiles](https://docs.docker.com/engine/reference/builder/) or [Compose](https://docs.docker.com/compose/compose-file/#build) as recipes.
* [Recipes](https://www.eclipse.org/che/docs/recipes.html)
* [Che Included Recipes](https://github.com/eclipse/che-dockerfiles)
#### Project Samples
A project sample is a code template cloned into the workspace when a user creates a new project. Users can select from a sample while using the user dashboard. Samples have both sample code and a default set of commands associated with them. Samples are loaded based upon the type of stack selected. You can add your own samples to the default Che distribution.
* [Samples](https://github.com/eclipse/che/blob/master/ide/che-core-ide-templates/src/main/resources/samples.json)
#### Commands
A command is a process that is injected into your workspace. It's outputs are streamed into the console. Commands have type and you can create, save, update and delete commands from within the IDE. You can create templates that have sample projects with default commands that are pre-populated in the IDE. Commands can reference macros that intelligently navigate the project tree or current selections.
* [Commands](https://www.eclipse.org/che/docs/commands-ide-macro.html)
#### Extension Development
An extension is a set of code and resources that are packaged into a plugin that alter the behavior of the system. Extensions can be IDE extensions, workspace extensions (they are injected into the workspace agent running within each workspace), or Che extensions (injected into the Che server). Extensions are authored in Java and maven, and then packaged into JAR / ZIP files for deployment into Eclipse Che.
* [Extension Intro](https://www.eclipse.org/che/docs/framework-overview.html)
#### IDE Extensions
IDE extensions are compiled into JavaScript with other extensions to create a single, JavaScript application. You can package many extensions together into a single JavaScript application. The JavaScript application is cross-browser optimized. You can debug extensions and perform execution traces from within the browser of extension code. IDE extensions can invoke REST services that are running within the Che server or within a workspace. Che provides default workspace REST APIs or you can provide your own with workspace extensions.
* [Invoking Workspace REST APIs](https://www.eclipse.org/che/docs/rest-api.html)
* [Project Type](https://www.eclipse.org/che/docs/project-types.html)
* [Actions](https://www.eclipse.org/che/docs/actions.html)
* [Parts](https://www.eclipse.org/che/docs/parts.html)
#### Server-Side Extensions and Agents
Server-side extensions are libraries that are deployed into the workspace agent when the workspace is activated. Che deploys some standard server-side extensions that expose the Workspace REST API to the outside world. You can author extensions that modify or extend this API with your own services. New workspace APIs are exposed as JAX-RS services and you use dependency injection to define the API interfaces.
Agents are scripts that are executed after a [runtime machine](https://www.eclipse.org/che/docs/devops/runtime-machines/index.html) is created. They add additional capabilities to the machines they’re injected in - for example to allow terminal access or enhanced language services (using the Language Server Protocol). Agents allow these services to be injected into machines built from stock Dockerfiles or Compose files.
* [Language Server Protocol](https://www.eclipse.org/che/docs/language-servers.html)
* [Agents Packaged With Che](https://github.com/eclipse/che/tree/master/agents)
#### Workspace REST API
IDE extensions have access to a default set of workspace APIs that are deployed within each workspace. These APIs are available through a Swagger configuration.
* [Swagger](https://www.eclipse.org/che/docs/rest-api.html)
* [Security Model](https://www.eclipse.org/che/docs/authentication.html)
* [Workspaces](https://www.eclipse.org/che/docs/workspace-data-model.html)

93
README.md
View File

@ -1,55 +1,78 @@
# Eclipse Che - Eclipse Next-Generation IDE
<div id="header" align="center">
[![Eclipse Che - Eclipse Next-Generation IDE](https://raw.githubusercontent.com/eclipse/che/assets/eclipseche.png)](
https://www.eclipse.org/che/)
**Next-generation container development platform, developer workspace server and cloud IDE**
[![Eclipse License](https://img.shields.io/badge/license-Eclipse-brightgreen.svg)](https://github.com/codenvy/che/blob/master/LICENSE)
[![Build Status](https://ci.codenvycorp.com/buildStatus/icon?job=che-master-ci)](https://ci.codenvycorp.com/job/che-master-ci)
<a href="https://sonarcloud.io/dashboard?id=org.eclipse.che%3Ache-parent%3Amaster">
<img src="https://sonarcloud.io/images/project_badges/sonarcloud-black.svg" width="94" height="20" href="" />
</a>
*Che is Kubernetes-native and places everything the developer needs into containers in Kube pods including dependencies, embedded containerized runtimes, a web IDE, and project code. This makes workspaces distributed, collaborative, and portable to run anywhere Kubernetes runs ... [Read More](https://www.eclipse.org/che/features/)*
https://www.eclipse.org/che/. Next-generation container development platform, developer workspace server and cloud IDE. Che is Kubernetes-native and places everything the developer needs into containers in Kube pods including dependencies, embedded containerized runtimes, a web IDE, and project code. This makes workspaces distributed, collaborative, and portable to run anywhere Kubernetes runs ... [Read More](https://www.eclipse.org/che/features/)
</div>
![Eclipse Che](https://www.eclipse.org/che/images/hero-technology-v2@2x.png "Eclipse Che")
![Eclipse Che](https://raw.githubusercontent.com/eclipse/che/assets/screenshoft_che7-quarkus-demo.png)
---
**Visit website at: https://www.eclipse.org/che/** and documentation at: https://www.eclipse.org/che/docs
- [**Getting Started**](#getting-started)
- [**Using Eclipse Che**](#using-eclipse-che)
- [**Feedback and Community**](#feedback-and-community)
- [**Contributing**](#contributing)
- [**Roadmap**](#roadmap)
- [**License**](#license)
---
### Getting Started
You can run Che wherever Kubernetes runs - in the public cloud, a private cloud, or install it locally. The [step by step guide](https://eclipse.org/che/getting-started/) will get you going along with [our docs](https://www.eclipse.org/che/docs/).
Here you can find links on how to get started with Eclipse Che:
- [Use Eclipse Che online](https://www.eclipse.org/che/getting-started/cloud/)
- [Run Eclipse Che on your own K8S cluster](https://www.eclipse.org/che/docs/che-7/che-quick-starts.html#running-che-locally_che-quick-starts)
The `che` repository is where we do development and there are many ways you can participate, for example:
- [Submit bugs and feature requests](https://github.com/eclipse/che/issues) and help us verify them
- Review [source code changes](https://github.com/eclipse/che/pulls)
- [Improve docs](https://github.com/codenvy/che-docs)
### Using Eclipse Che
Here you can find references to useful documentation and hands-on guides to learn how to get the most of Eclipse Che:
- [Customize Che workspaces for your projects](https://www.eclipse.org/che/docs/che-7/using-developer-environments-workspaces.html#configuring-a-che-workspace-using-a-devfile_using-developer-environments-workspaces)
- [Run VSCode Extensions in Che workspaces](https://www.eclipse.org/che/docs/che-7/extending-che.html#using-a-visual-studio-code-extension-in-che_extending-che)
- [Configure Che for your teams](https://www.eclipse.org/che/docs/che-7/customizing-registries.html)
### Customizing
There are many ways to customize Che out-of-the-box including [stacks, templates, commands, IDE extensions, server-side extensions plugins, assemblies, RESTful APIs, and editors](https://github.com/eclipse/che/blob/master/CUSTOMIZING.md).
### Contributing
If you are interested in fixing issues and contributing directly to the code base, please see [How to Contribute](https://github.com/eclipse/che/wiki/How-To-Contribute). It covers:
- [Submitting bugs](https://github.com/eclipse/che/wiki/Submitting-Bugs-and-Suggestions)
- [Development workflow](https://github.com/eclipse/che/wiki/Development-Workflow)
- [Coding guidelines](https://github.com/eclipse/che/wiki/Coding-Guidelines)
- [Contributor license agreement](https://github.com/eclipse/che/wiki/Contributor-License-Agreement)
### Ecosystem
The next generation of Eclipse Che is going to be built from multiple components and plugins (learn more in [the roadmap](https://github.com/eclipse/che/wiki/Roadmap) on the wiki). This list provides links to those components and plugins.
| Project | Description |
| ----------- |-----|
| [Theia-IDE](https://github.com/theia-ide/theia) | Theia IDE integrated in Che. |
| [GitHub Plugin](https://github.com/eclipse/che-theia-github-plugin) | GitHub VCS support. |
| [Java Plugin](https://github.com/eclipse/che-theia-java-plugin) | Java language support. |
| [SSH Plugin](https://github.com/eclipse/che-theia-ssh-plugin) | SSH public/private key pairs management. |
| [Terminal Plugin](https://github.com/eclipse/che-theia-terminal-plugin) | Terminal plugin. |
| [Machines Plugin](https://github.com/eclipse/che-theia-machines-plugin)| Workspace's containers controller plugin. |
| [Hosted plugin manager](https://github.com/eclipse/che-theia-hosted-plugin-manager-extension)| IDE hosting handler for url changing and port forwarding. |
### Feedback
### Feedback and Community
We love to hear from users and developers. Here are the various ways to get in touch with us:
* **Support:** You can ask questions, report bugs, and request features using [GitHub issues](https://github.com/eclipse/che/issues).
* **Public Chat:** Join the public [eclipse-che](https://mattermost.eclipse.org/eclipse/channels/eclipse-che) Mattermost channel to discuss with community and contributors.
* **Roadmap:** We maintain [the roadmap](https://github.com/eclipse/che/wiki/Roadmap) on the wiki.
* **Twitter:** [@eclipse_che](https://twitter.com/eclipse_che)
* **Mailing List:** [che-dev@eclipse.org](https://accounts.eclipse.org/mailing-list/che-dev)
* **Weekly Meetings:** Join us in our [Che community meeting](https://github.com/eclipse/che/wiki/Che-Dev-Meetings) every second monday.
### Contributing
If you are interested in fixing issues and contributing directly to the code base:
- :bug: [Submitting bugs](https://github.com/eclipse/che/wiki/Submitting-Bugs-and-Suggestions)
- :page_facing_up: [Contributor license agreement](https://github.com/eclipse/che/wiki/Eclipse-Contributor-Agreement)
- :checkered_flag: [Development workflows](./CONTRIBUTING.md)
- :ok_hand: Review [source code changes](https://github.com/eclipse/che/pulls)
- :pencil: [Improve docs](https://github.com/eclipse/che-docs)
- :building_construction: [Che architecture](https://www.eclipse.org/che/docs/che-7/che-architecture.html)
- :octocat: [Che repositories](https://github.com/eclipse/che/blob/readme-che-wip/CONTRIBUTING.md#other-che-repositories)
- :sparkles: [Good first issue for new contributors](https://github.com/eclipse/che/wiki/Labels#new-contributors)
#### Extending Eclipse Che
- [Add a new language support. (to be provided soon)]()
- [Package your favorite VSCode extensions and make them available in Che.](https://www.eclipse.org/che/docs/che-7/extending-che.html#publishing-a-vs-code-extension-into-the-che-plug-in-registry_using-a-visual-studio-code-extension-in-che)
- [Write your own VSCode extension that runs on a dedicated side car container.](https://www.eclipse.org/che/docs/che-7/extending-che.html#che-theia-plug-in-lifecycle_what-is-a-che-theia-plug-in)
- [Build and package your custom Che-Theia editor with your extensions and plugins.](https://www.eclipse.org/che/docs/che-7/extending-che.html#using-alternative-ides-in-che_extending-che)
### Roadmap
We maintain the [Che roadmap](https://github.com/eclipse/che/wiki/Roadmap) in the open way. We welcome anyone to ask question and contribute to the roadmap by joining our [community meetings](https://github.com/eclipse/che/wiki/Che-Dev-Meetings).
### License
Che is open sourced under the Eclipse Public License 2.0.
### Roadmap and Community Meetings
We publish the [Che roadmap](https://github.com/eclipse/che/wiki/Roadmap) in the open and welcome anyone to join our [community meetings](https://github.com/eclipse/che/wiki/Che-Dev-Meetings). We love to hear from users and developers!