From e54faedda038d3c3825a279678006b2e2f5a94c7 Mon Sep 17 00:00:00 2001 From: Igor Date: Wed, 27 Sep 2023 10:15:07 +0300 Subject: [PATCH] Add CONTRIBUTING.md file --- CONTRIBUTING.md | 63 +++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 57 ++------------------------------------------ 2 files changed, 65 insertions(+), 55 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000000..686a646050 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,63 @@ +# Build requirements +- Apache Maven 3.9 or later +- JDK 11 +- Podman or Docker (required for running integration tests) +A Che workspace environment allows to build the image internaly, using the workspace terminal. + +# Sources build +Run `mvn clean install` to build. Activate a faster profile build by adding `-Pfast`. + +# Image build and push +1. Go to the `dockerfiles` directory. +2. Run `./build.sh`. +3. Tag the **che-server** image with your account: `docker tag quay.io/eclipse/che-server:next //che-server:next`. +4. Push the **che-server** image to your account: `docker push //che-server:next`. + +# Start and debug +1. Deploy Che to a [Red Hat OpenShift](https://www.eclipse.org/che/docs/stable/administration-guide/installing-che-on-openshift-using-cli/) or [Minikube](https://www.eclipse.org/che/docs/stable/administration-guide/installing-che-on-minikube/) cluster by using a previously built image: `chectl server:start --platform= --cheimage=//che-server:next`. +2. Enable local debugging of the Eclipse Che server: `chectl server:debug`. +3. In your IDE, create a new Remote JVM Debug configuration on `localhost:8000`. +4. Hit a breakpoint in the code and activate the debug configuration. + +# Contributing an SCM provider +An SCM provider support has to be provided by adding new maven modules to the wsmaster directory. + +## Implementing che-core-api-oauth- module +This module is responsible for Oauth requests to the SCM provider and contans next implementations: +1. `OAuthAuthenticator` contains specific implementation of Oauth token requestand authentication endpoint. +2. `OAuthAuthenticatorProvider` a provider of the `OAuthAuthenticator`. + +## Implementing coresponding che-core-api-factory- module +This module is responsible for API operations of the specific SCM provider. +1. `ApiClient` contains all necessary HTTP API calls like `getUser()`. +2. `AuthorisingFileContentProvider` overrides the common `AuthorisingFileContentProvider` to define the specific `isPublicRepository()` function. +3. `FactoryParameterResolver` validates SCM URL if it corresponds to the SCM provider. Also Provides specific Factory Parameters resolver for the SCM repository. +4. `PersonalAccessTokenFetcher` fetches Personal Access Token from the SCM provider by reqesting the OAuth API of the provider. Validates the token by comparing the token access scopes with the predefined scope list. +5. `FileResolver` Implementation of a resolver that can return particular file content from specified SCM repository. +6. `URLParser` Parses the string representation of the URL to an SCM specific object +7. `UserDataFetcher` Implementation of a resolver that can return particular file content from specified SCM repository. + +# CI +There are several [GitHub Actions](https://github.com/eclipse-che/che-server/actions) workflows implemented for this repository: + +- [![build-next](https://github.com/eclipse-che/che-server/actions/workflows/next-build.yml/badge.svg)](https://github.com/eclipse-che/che-server/actions/workflows/next-build.yml) +Builds Maven artifacts, builds container images and pushes them to [quay.io](https://quay.io/organization/eclipse) on each commit to [`main`](https://github.com/eclipse-che/che-server/tree/main) branch. +- [![Release Che Server](https://github.com/eclipse-che/che-server/actions/workflows/release.yml/badge.svg)](https://github.com/eclipse-che/che-server/actions/workflows/release.yml) +Builds Maven artifacts and container images. Images are public and pushed to [quay.io](https://quay.io/organization/eclipse). See [RELEASE.md](https://github.com/eclipse-che/che-server/blob/master/RELEASE.md) for more information about this workflow. +- [![Release Changelog](https://github.com/eclipse-che/che-server/actions/workflows/release-changelog.yml/badge.svg)](https://github.com/eclipse-che/che-server/actions/workflows/release-changelog.yml) +Creates a GitHub release which will include a generated changelog. +- [![Update Che docs variables](https://github.com/eclipse-che/che-server/actions/workflows/che-properties-docs-update.yml/badge.svg)](https://github.com/eclipse-che/che-server/actions/workflows/che-properties-docs-update.yml/badge.svg) +Runs on each commit to [`main`](https://github.com/eclipse-che/che-server/tree/main) branch. +- [![build-pr-check](https://github.com/eclipse-che/che-server/actions/workflows/build-pr-check.yml/badge.svg)](https://github.com/eclipse-che/che-server/actions/workflows/build-pr-check.yml) +Builds Maven artifacts and container images. This workflow is used as a check for all pull requests that are submitted to this project. +- [![Sonar](https://github.com/eclipse-che/che-server/actions/workflows/sonar.yaml/badge.svg)](https://github.com/eclipse-che/che-server/actions/workflows/sonar.yaml) +Runs Sonar against the main branch. The result can be seen [here](https://sonarcloud.io/dashboard?id=org.eclipse.che%3Ache-server). +- [![Try in Web IDE](https://github.com/eclipse-che/che-server/actions/workflows/try-in-web-ide.yaml/badge.svg)](https://github.com/eclipse-che/che-server/actions/workflows/try-in-web-ide.yaml) +Used as a check for pull requests that are submitted to this project. + +Downstream builds can be found at the link below, which is _internal to Red Hat_. Stable builds can be found by replacing the 3.x with a specific version like 3.2. + +- [server_3.x](https://main-jenkins-csb-crwqe.apps.ocp-c1.prod.psi.redhat.com/job/DS_CI/job/server_3.x/) + +# Report issues +Issues are tracked on the main Eclipse Che Repository: https://github.com/eclipse/che/issues diff --git a/README.md b/README.md index 23535e476f..fa53d3968a 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # What is Che server -Che Server provides an API for managing Kubernetes namespaces, and to retrieve devfile content from repositories, -hosted on GitHub, GitLab, Bitbucket, and Microsoft Azure Repos. +Che Server provides an API for managing Kubernetes namespaces and to retrieve devfile content from repositories, +hosted on GitHub, GitLab, Bitbucket and Microsoft Azure Repos. # Project structure Che Server is mostly a Java web application deployed on an Apache Tomcat server in a container. Che Server uses the following modules: @@ -24,55 +24,6 @@ Che Server is mostly a Java web application deployed on an Apache Tomcat server Other modules are deprecated and will be removed in the future. -# Build requirements -- Apache Maven 3.9 or later -- JDK 11 -- Podman or Docker (required for running integration tests) - -# Sources build -Run `mvn clean install` to build. Activate a faster profile build by adding `-Pfast`. - -You can skip enforcers, validators, and tests with: - -``` -mvn clean install -V -B -e -Pfast -DskipTests -Dskip-validate-sources -Denforcer.skip=true -Dmaven.repo.local=.repository/ -``` - -# Image build and push -1. Go to the `dockerfiles` directory. -2. Run `./build.sh`. -3. Tag the **che-server** image with your account: `docker tag quay.io/eclipse/che-server:next //che-server:next`. -4. Push the **che-server** image to your account: `docker push //che-server:next`. - -# Debug -1. Deploy Che to a [Red Hat OpenShift](https://www.eclipse.org/che/docs/stable/administration-guide/installing-che-on-openshift-using-cli/) or [Minikube](https://www.eclipse.org/che/docs/stable/administration-guide/installing-che-on-minikube/) cluster by using a previously built image: `chectl server:start --platform= --cheimage=//che-server:next`. -2. Enable local debugging of the Eclipse Che server: `chectl server:debug`. -3. In your IDE, create a new Remote JVM Debug configuration on `localhost:8000`. -4. Hit a breakpoint in the code and activate the debug configuration. - - -# CI -There are several [GitHub Actions](https://github.com/eclipse-che/che-server/actions) workflows implemented for this repository: - -- [![build-next](https://github.com/eclipse-che/che-server/actions/workflows/next-build.yml/badge.svg)](https://github.com/eclipse-che/che-server/actions/workflows/next-build.yml) -Builds Maven artifacts, builds container images and pushes them to [quay.io](https://quay.io/organization/eclipse) on each commit to [`main`](https://github.com/eclipse-che/che-server/tree/main) branch. -- [![Release Che Server](https://github.com/eclipse-che/che-server/actions/workflows/release.yml/badge.svg)](https://github.com/eclipse-che/che-server/actions/workflows/release.yml) -Builds Maven artifacts and container images. Images are public and pushed to [quay.io](https://quay.io/organization/eclipse). See [RELEASE.md](https://github.com/eclipse-che/che-server/blob/master/RELEASE.md) for more information about this workflow. -- [![Release Changelog](https://github.com/eclipse-che/che-server/actions/workflows/release-changelog.yml/badge.svg)](https://github.com/eclipse-che/che-server/actions/workflows/release-changelog.yml) -Creates a GitHub release which will include a generated changelog. -- [![Update Che docs variables](https://github.com/eclipse-che/che-server/actions/workflows/che-properties-docs-update.yml/badge.svg)](https://github.com/eclipse-che/che-server/actions/workflows/che-properties-docs-update.yml/badge.svg) -Runs on each commit to [`main`](https://github.com/eclipse-che/che-server/tree/main) branch. -- [![build-pr-check](https://github.com/eclipse-che/che-server/actions/workflows/build-pr-check.yml/badge.svg)](https://github.com/eclipse-che/che-server/actions/workflows/build-pr-check.yml) -Builds Maven artifacts and container images. This workflow is used as a check for all pull requests that are submitted to this project. -- [![Sonar](https://github.com/eclipse-che/che-server/actions/workflows/sonar.yaml/badge.svg)](https://github.com/eclipse-che/che-server/actions/workflows/sonar.yaml) -Runs Sonar against the main branch. The result can be seen [here](https://sonarcloud.io/dashboard?id=org.eclipse.che%3Ache-server). -- [![Try in Web IDE](https://github.com/eclipse-che/che-server/actions/workflows/try-in-web-ide.yaml/badge.svg)](https://github.com/eclipse-che/che-server/actions/workflows/try-in-web-ide.yaml) -Used as a check for pull requests that are submitted to this project. - -Downstream builds can be found at the link below, which is _internal to Red Hat_. Stable builds can be found by replacing the 3.x with a specific version like 3.2. - -- [server_3.x](https://main-jenkins-csb-crwqe.apps.ocp-c1.prod.psi.redhat.com/job/DS_CI/job/server_3.x/) - # License - [Eclipse Public License 2.0](LICENSE) @@ -81,7 +32,3 @@ Downstream builds can be found at the link below, which is _internal to Red Hat_ The Eclipse Che community is globally reachable through public chat rooms, mailing list and weekly calls. See the Eclipse Che Documentation about [how you can join our community](https://www.eclipse.org/che/docs/stable/overview/introduction-to-eclipse-che/#_joining_the_community). - -## Report issues - -Issues are tracked on the main Eclipse Che Repository: https://github.com/eclipse/che/issues