-
Notifications
You must be signed in to change notification settings - Fork 52
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
* chore: add CONTRIBUTING.md * fixup! chore: add CONTRIBUTING.md * fixup! fixup! chore: add CONTRIBUTING.md * Update CONTRIBUTING.md Co-authored-by: David Kwon <dakwon@redhat.com> * Update CONTRIBUTING.md Co-authored-by: David Kwon <dakwon@redhat.com> * Update CONTRIBUTING.md Co-authored-by: David Kwon <dakwon@redhat.com> * Update CONTRIBUTING.md Co-authored-by: David Kwon <dakwon@redhat.com> * Update CONTRIBUTING.md Co-authored-by: David Kwon <dakwon@redhat.com> * Update CONTRIBUTING.md Co-authored-by: David Kwon <dakwon@redhat.com> * fix: remove outdated --------- Co-authored-by: David Kwon <dakwon@redhat.com>
- Loading branch information
Showing
2 changed files
with
281 additions
and
204 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,279 @@ | ||
| # Table of Contents | ||
|
|
||
| - [Contributing Guidelines](#contributing-guidelines) | ||
| - [Code of Conduct](#code-of-conduct) | ||
| - [Reporting Issues](#reporting-issues) | ||
| - [Opening Pull Requests](#opening-pull-requests) | ||
| - [Additional PR Requirements](#additional-pr-requirements) | ||
| - [Approval of Project Dependencies](#approval-of-project-dependencies) | ||
| - [Developing within Eclipse Che](#developing-within-eclipse-che) | ||
| - [Starting a Workspace within Eclipse Che](#starting-a-workspace-within-eclipse-che) | ||
| - [Running Devfile Tasks for Downloading Dependencies and Building the Project](#running-devfile-tasks-for-downloading-dependencies-and-building-the-project) | ||
| - [Analyzing Bundles within Eclipse Che](#analyzing-bundles-within-eclipse-che) | ||
| - [Measuring Build Speed within Eclipse Che](#measuring-build-speed-within-eclipse-che) | ||
| - [Running the Project Locally Against a Remote Eclipse Che Installation on a Seperate Cluster](#running-the-project-locally-against-a-remote-eclipse-che-installation-on-a-seperate-cluster) | ||
| - [Debugging](#debugging) | ||
| - [Pushing to GitHub and Creating a Pull Request](#pushing-to-github-and-creating-a-pull-request) | ||
| - [Building an Image](#building-an-image) | ||
| - [Building a New Image and Applying it to the CheCluster in the Current Context](#building-a-new-image-and-applying-it-to-the-checluster-in-the-current-context) | ||
| - [Updating Dashboard on Remote Cluster Using skaffold.dev](#updating-dashboard-on-remote-cluster-using-skaffolddev) | ||
| - [Developing Locally Against Remote Che Cluster](#developing-locally-against-remote-che-cluster) | ||
| - [Running the Project Locally](#running-the-project-locally) | ||
| - [Building Changes Incrementally](#building-changes-incrementally) | ||
| - [Analyzing Bundles](#analyzing-bundles) | ||
| - [Measuring Build Speed](#measuring-build-speed) | ||
| - [Checking Dependencies for Intellectual Property (IP) Compliance](#checking-dependencies-for-intellectual-property-ip-compliance) | ||
|
|
||
| --- | ||
|
|
||
| # Contributing Guidelines | ||
|
|
||
| The Eclipse Che Dashboard is an integral component of the [Eclipse Che](link-to-eclipse-che-readme.md) project. As such, this project adheres to the identical set of contributing guidelines as Eclipse Che. | ||
|
|
||
| ## Code of Conduct | ||
|
|
||
| Prior to beginning your contributions, we kindly request that you review our [Code of Conduct](https://github.com/eclipse/che/blob/main/CODE_OF_CONDUCT.md). | ||
|
|
||
| ## Reporting Issues | ||
|
|
||
| If you encounter a bug, please begin by searching for an existing open issue [here (area/dashboard)](https://github.com/eclipse/che/issues?q=is%3Aopen+is%3Aissue+label%3Aarea%2Fdashboard). If you do not find a relevant open issue, feel free to create a new one using one of our provided [issue templates](https://github.com/eclipse/che/issues/new/choose). | ||
|
|
||
| ## Opening Pull Requests | ||
|
|
||
| You can explore information about pull request templates and the necessary requirements for PR approval [at this location](https://github.com/eclipse/che/blob/main/CONTRIBUTING.md#pull-request-template-and-its-checklist). | ||
|
|
||
| ### Additional PR Requirements | ||
|
|
||
| #### Approval of Project Dependencies | ||
|
|
||
| The author has to ensure that all dependencies satisfy Eclipse [Intellectual Property](https://www.eclipse.org/projects/handbook/#ip). | ||
|
|
||
| ## Developing within Eclipse Che | ||
|
|
||
| This project features a [devfile v2](https://github.com/eclipse-che/che-dashboard/blob/main/devfile.yaml) located in the project's root directory. This devfile outlines the development dependencies and necessary commands required for Eclipse Che Dashboard development. | ||
|
|
||
| Within Eclipse Che, you can perform the following tasks: | ||
|
|
||
| - Download Yarn dependencies and build the project. | ||
| - Work within a rich development environment like VS Code. | ||
| - Test your changes by launching a dashboard instance on a cluster (e.g., your personal cluster). | ||
| - Debug the project directly within your editor. | ||
| - Push your changes to GitHub. | ||
|
|
||
| ### Starting a Workspace within Eclipse Che | ||
|
|
||
| To start a new workspace within Eclipse Che, navigate to the following URL: | ||
|
|
||
| ```sh | ||
| {CHE-HOST}/#https://github.com/eclipse-che/che-dashboard | ||
| ``` | ||
|
|
||
| ### Running Devfile Tasks for Downloading Dependencies and Building the Project | ||
|
|
||
| For VS Code, execute tasks defined in the devfile with these steps: | ||
|
|
||
| 1. Open the command palette (Ctrl/Cmd + Shift + P). | ||
| 2. Execute the `Tasks: Run Task` command. | ||
| 3. Select the `devfile` folder and select the `[UD] install dependencies` task to install project dependencies. | ||
| 4. Follow steps 1 and 2 again, select the `[UD] build` task to build the project. | ||
|
|
||
| ### Analyzing Bundles within Eclipse Che | ||
|
|
||
| To create visualizations illustrating the contents of your webpack bundle for either dashboard-backend or dashboard-frontend, you can use the following procedure: | ||
|
|
||
| 1. Execute the task named `[UD] backend bundle analyzer` (or the `[UD] frontend bundle analyzer`) as specified in the devfile. | ||
| 2. Wait for the VS Code notification indicating that local server has been started. Click on `Open in New Tab` to access the bundle analyzer in a new tab. | ||
|
|
||
| ### Measuring Build Speed within Eclipse Che | ||
|
|
||
| To determine the build speed of either the dashboard-backend or dashboard-frontend, you can initiate the task labeled `[UD] backend build` speed (or `[UD] frontend build speed`). | ||
|
|
||
| ### Running the Project Locally Against a Remote Eclipse Che Installation on a Seperate Cluster | ||
|
|
||
| To run the Dashboard against a remote Eclipse Che installation, provide your cluster credentials to the `tools` development container. | ||
|
|
||
| **NOTE**: You must have permissions to get/patch resources in the namespace in which the CheCluster CR was created. | ||
|
|
||
| 1. Open the `tools` container within the editor. | ||
| 2. For an OpenShift cluster, execute the `oc login` command with your cluster credentials. For a Kubernetes cluster, configure the `~/.kube/config` file. | ||
| 3. Execute the `[UD] start` task defined in the devfile by following the steps 1 and 2 from [Running Devfile Tasks for Downloading Dependencies and Building the Project](#running-devfile-tasks-for-downloading-dependencies-and-building-the-project) to start the dashboard instance. | ||
| 4. Wait for the VS Code notification confirming that local server is now listening on port 8080. Click on `Open in New Tab` to open a new tab running the latest Dashboard changes. | ||
|
|
||
| ### Debugging | ||
|
|
||
| To start the Dashboard for debugging, run the `[UD] build` and `[UD] start` tasks by following the steps 1 and 2 from [Running Devfile Tasks for Downloading Dependencies and Building the Project](#running-devfile-tasks-for-downloading-dependencies-and-building-the-project). | ||
|
|
||
| Debugging the dashboard-frontend and dashboard-backend can be done with your browser developer tools. For Chrome DevTools, this can be done from the `Sources` tab. For debugging the backend, open the dedicated Chrome DevTools for Node.js. | ||
|
|
||
| To debug the backend within the editor, after running the `[UD] build` and `[UD] start` tasks, run the `Attach to Remote` debug launch configuration defined in `.vscode/launch.json`. | ||
|
|
||
| ### Pushing to GitHub and Creating a Pull Request | ||
|
|
||
| For PRs targeting the `eclipse-che/che-dashboard` repository, the PR source branch should also be located in `eclipse-che/che-dashboard` to allow all PR checks to run. | ||
| Therefore, if your Che instance has the GitHub oAuth app set up, follow [these steps to request access](https://github.com/eclipse/che/issues/21627#issuecomment-1216592765) for pushing to `eclipse-che/che-dashboard`. | ||
|
|
||
| To commit and push changes to the remote repository, open a terminal within the `tools` container and run Git commands such as `git add` and `git push`. | ||
| You may opt to add a remote with `git add remote` and push to a personal fork rather than the upstream `eclipse-che/che-dashboard` repository. | ||
|
|
||
| ### Building an Image | ||
|
|
||
| To build an image within a Che workspace on an OpenShift cluster, the cluster and OpenShift user must be configured to allow rootless builds. | ||
|
|
||
| To build the image, run: | ||
|
|
||
| ```sh | ||
| podman build . -f build/dockerfiles/Dockerfile -t quay.io/eclipse/che-dashboard:next | ||
| ``` | ||
|
|
||
| ### Building a New Image and Applying it to the CheCluster in the Current Context | ||
|
|
||
| First, export environment variables globally: | ||
|
|
||
| ```sh | ||
| export IMAGE_REGISTRY_USER_NAME=<IMAGE_REGISTRY_USER_NAME> && \ | ||
| export IMAGE_REGISTRY_HOST=<IMAGE_REGISTRY_HOST> | ||
| ``` | ||
|
|
||
| To build a new image and apply it to the CheCluster, execute: | ||
|
|
||
| ```sh | ||
| yarn build-and-patch | ||
| ``` | ||
|
|
||
| ### Updating Dashboard on Remote Cluster Using `skaffold.dev` | ||
|
|
||
| To update the dashboard deployment you need access to the Kubernetes cluster (see [Running the Project Locally](#running-the-project-locally)) | ||
|
|
||
| Then proceed with the following steps: | ||
|
|
||
| ```sh | ||
| # Export an environment variable to define a repository for image pushes, e.g.: | ||
| export DEFAULT_REPO="${IMAGE_REGISTRY_HOST}/${IMAGE_REGISTRY_USER_NAME}" | ||
| ``` | ||
|
|
||
| ```sh | ||
| # Log in to the repository: | ||
| podman login quay.io | ||
| ``` | ||
|
|
||
| Now you can build the project and update the dashboard on the remote cluster: | ||
|
|
||
| ```sh | ||
| # Build the dashboard: | ||
| yarn build | ||
|
|
||
| # Update the dashboard deployment once: | ||
| skaffold run --cleanup=false --default-repo=$DEFAULT_REPO | ||
|
|
||
| # Or, run in development mode to watch for changes: | ||
| skaffold dev --cleanup=false --default-repo=$DEFAULT_REPO | ||
| ``` | ||
|
|
||
| ## Developing Locally Against Remote Che Cluster | ||
|
|
||
| ### Running the Project Locally | ||
|
|
||
| To run the Dashboard, you need to establish a connection to the Kubernetes cluster where Che is deployed. You can verify the current cluster in your kubeconfig file, typically located at $KUBECONFIG (or ~/.kube/config if $KUBECONFIG is not set). If the current cluster is not the one you want, you may need to use `oc login` (for OpenShift) or edit the file manually (for Kubernetes). | ||
|
|
||
| After that, you can follow these steps: | ||
|
|
||
| ```sh | ||
| # 1. Install all the necessary dependencies: | ||
| yarn | ||
|
|
||
| # 2. (Optional) Apply a patch to the minikube cluster to enable local development: | ||
| yarn start:prepare | ||
|
|
||
| # 3. Export the Che certificate | ||
| chectl cacert:export --destination=$TMPDIR | ||
|
|
||
| # 4. Set CHE_SELF_SIGNED_MOUNT_PATH variable | ||
| export CHE_SELF_SIGNED_MOUNT_PATH=$TMPDIR | ||
|
|
||
| # 5. Run the development server locally: | ||
| yarn start | ||
|
|
||
| # 6. (Optional) Undo the patch to the minikube cluster: | ||
| yarn start:cleanup | ||
|
|
||
| # If you want to ensure that you're using the latest codebase, include the --force-build flag: | ||
| # yarn start --force-build | ||
|
|
||
| # Additionally, you may need to specify the CHE_NAMESPACE variable to indicate the namespace where the CheCluster custom resource is located. | ||
| # The default value is `eclipse-che`` | ||
| # export CHE_NAMESPACE="my-custom-che" | ||
| ``` | ||
|
|
||
| The development server will run both the dashboard-frontend and dashboard-backend on [http://localhost:8080](http://localhost:8080). | ||
|
|
||
| **Native Auth**: | ||
| With Native Auth, routes are secured with OpenShift OAuth which we can't deal with easily. | ||
| So, instead when you do `yarn start` we bypass OpenShift OAuth proxy while requesting Che Server by doing `kubectl port-forward`. So, no additional configuration is needed but note that your Dashboard will be authentication with the user from the current KUBECONFIG. | ||
|
|
||
| ### Building Changes Incrementally | ||
|
|
||
| If you want to automatically detect and build changes incrementally, follow these steps: | ||
|
|
||
| ```sh | ||
| # Watch and build changes for the backend: | ||
| yarn --cwd packages/dashboard-backend build:watch | ||
| ``` | ||
|
|
||
| ```sh | ||
| # Watch and build changes for the frontend: | ||
| yarn --cwd packages/dashboard-frontend build:watch | ||
| ``` | ||
|
|
||
| Local backend is a prerequisite for the development server. You can run the dev server using the following command: | ||
|
|
||
| ```sh | ||
| yarn start | ||
| ``` | ||
|
|
||
| To avoid memory issues and the process being killed, more memory is possible through the following command in the frontend package directory: | ||
|
|
||
| ```sh | ||
| NODE_OPTIONS="--max_old_space_size=6500" && yarn start | ||
| ``` | ||
|
|
||
| ### Analyzing Bundles | ||
|
|
||
| To generate visualizations that display the contents of your webpack bundle for dashboard-backend, execute the following command: | ||
|
|
||
| ```sh | ||
| yarn --cwd packages/dashboard-backend build --env bundleAnalyzer=true | ||
| ``` | ||
|
|
||
| For dashboard-frontend, use the following command to visualize the webpack bundle: | ||
|
|
||
| ```sh | ||
| yarn --cwd packages/dashboard-frontend build --env bundleAnalyzer=true | ||
| ``` | ||
|
|
||
| ### Measuring Build Speed | ||
|
|
||
| If you want to gauge the build speed for dashboard-backend, you can run the following command: | ||
|
|
||
| ```sh | ||
| yarn --cwd packages/dashboard-backend build:dev --env speedMeasure=true | ||
| ``` | ||
|
|
||
| Similarly, to measure the build speed for dashboard-frontend, execute the following command: | ||
|
|
||
| ```sh | ||
| yarn --cwd packages/dashboard-frontend build:dev --env speedMeasure=true | ||
| ``` | ||
|
|
||
| ### Checking Dependencies for Intellectual Property (IP) Compliance | ||
|
|
||
| To ensure that all dependencies adhere to Eclipse's [Intellectual Property](https://www.eclipse.org/projects/handbook/#ip) guidelines, this repository relies on a tool called [dash-licenses](https://github.com/che-incubator/dash-licenses), which serves as a wrapper for [eclipse/dash-licenses](https://github.com/eclipse/dash-licenses). | ||
|
|
||
| For an overview of the dependencies included in the production build, please refer to [.deps/prod.md](https://github.com/eclipse-che/che-dashboard/blob/main/.deps/prod.md). Additionally, you can check [.deps/dev.md](https://github.com/eclipse-che/che-dashboard/blob/main/.deps/dev.md) to view dependencies used exclusively during the build process. | ||
|
|
||
| To generate information about these dependencies, you can use the following command: | ||
|
|
||
| ```sh | ||
| yarn license:generate | ||
| ``` | ||
|
|
||
| This command will provide you with details about the dependencies and their compliance with intellectual property standards. |
Oops, something went wrong.