diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..7a4ad7d2d --- /dev/null +++ b/CONTRIBUTING.md @@ -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= && \ + export 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. diff --git a/README.md b/README.md index 41917f3d1..b0e1753e2 100644 --- a/README.md +++ b/README.md @@ -19,211 +19,9 @@ Below you can find installation instructions - [Node.js](https://docs.npmjs.com/getting-started/installing-node) - [yarn](https://yarnpkg.com/getting-started/install) -## Quick start +## Contributing -```sh -docker build . -f build/dockerfiles/Dockerfile -t quay.io/eclipse/che-dashboard:next -``` - -## Running locally against remote Che Cluster (Node.js 18) - -To run Dashboard against Che Cluster you need access to Kubernetes cluster where it lives. -So, make sure kubeconfig from $KUBECONFIG (or if unset ~/.kube/config) has the target cluster as current. -If no - you may need to do `oc login` (if it's OpenShift) or modify it manually if it's Kubernetes. - -Then you can proceed to the following steps: - -```sh -# 1. Install all dependencies: -yarn -# 2. (Optional) Patch minikube cluster to enable local development flow: -yarn start:prepare -# 3. Export Che certificate -chectl cacert:export --destination=$TMPDIR -# 4. Set CHE_SELF_SIGNED_MOUNT_PATH -export CHE_SELF_SIGNED_MOUNT_PATH=$TMPDIR -# 5. Run server locally: -yarn start -# 6. (optional) Patch cluster to revert it to initial state: -yarn start:cleanup -# If you want to make sure the latest bits are used, add flag to recompile -# yarn start --force-build -# Optionally you may need to set CHE_NAMESPACE where CheCluster CR live -# which is eclipse-che by default -# export CHE_NAMESPACE="my-custom-che" -``` - -The development server serves 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. - -### Incremental builds - -You may would like to watch changes and recompile them incrementally: -```sh -yarn --cwd packages/dashboard-backend build:watch -yarn --cwd packages/dashboard-frontend build:watch -``` - -As an alternative to build:watch for frontend, you can run Dev Server. - -Local backend is prerequisite for Dev Server and then the command to run Dev Server is - -```sh -yarn frontend: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 frontend:start -``` - -### Bundle analyzer - -To get visualizations of what’s in your webpack bundle for dashboard-backend: -```sh -yarn --cwd packages/dashboard-backend build --env bundleAnalyzer=true -``` - -To get visualizations of what’s in your webpack bundle for dashboard-frontend: -```sh -yarn --cwd packages/dashboard-frontend build --env bundleAnalyzer=true -``` - -### Measure build speed - -To measure build speed for dashboard-backend: -```sh -yarn --cwd packages/dashboard-backend build:dev --env speedMeasure=true -``` - -To measure build speed for dashboard-frontend: -```sh -yarn --cwd packages/dashboard-frontend build:dev --env speedMeasure=true -``` - -### Dependencies IP - -To make sure all the dependencies satisfy Eclipse [Intellectual Property](https://www.eclipse.org/projects/handbook/#ip), -this repo uses https://github.com/che-incubator/dash-licenses which is a wrapper for https://github.com/eclipse/dash-licenses. - -So, check [.deps/prod.md](https://github.com/eclipse-che/che-dashboard/blob/main/.deps/prod.md) for dependencies we package and [.deps/dev.md](https://github.com/eclipse-che/che-dashboard/blob/main/.deps/dev.md) for ones we use at build time only. - -To generate dependencies info: - -```sh -yarn license:generate -``` - -## Developing within Eclipse Che - -This project contains a [devfile v2](https://github.com/eclipse-che/che-dashboard/blob/main/devfile.yaml) in the root of the project which specifies development dependencies and commands needed to develop the Eclipse Che Dashboard. - -Within Eclipse Che, you are able to: -* download yarn dependencies and build the project -* work within a rich development environment like VS Code -* test your changes by starting a dashboard instance on a cluster (ex. your personal cluster) -* debug the project within the editor -* push changes to GitHub - -### Starting a workspace within Eclipse Che - -Navigate to the following URL to start a new workspace within Eclipse Che: -``` -{CHE-HOST}/#https://github.com/eclipse-che/che-dashboard -``` - -### Running devfile tasks to download yarn dependencies and build the project - -For Che-theia and VS Code, tasks defined in the devfile can be ran by following these steps: -1. Open the command palette (Ctrl/Cmd + Shift + P) -2. Run the `Tasks: Run Tasks` command -3. Select the `installdependencies` task to install dependencies -4. Follow steps 1-2 again and select the `build` task to build the project - -### Running the project locally against a remote Eclipse Che installation in 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, run the `oc login` command with the cluster credentials. For a Kubernetes cluster, configure the `~/.kube/config` file. -3. Run the `start` task defined in the devfile by following the steps 1 and 2 from [Running devfile tasks to download yarn dependencies and build the project](#running-devfile-tasks-to-download-yarn-dependencies-and-build-the-project) to start the dashboard instance. -4. Wait for the Che-Theia / VS Code notification stating that local-server is now listening on port 8080. Click on `Open in New Tab`. This opens a new tab running the latest Dashboard changes. - -### Debugging - -To start the Dashboard for debugging, run the `build` and `start` tasks by following the steps 1 and 2 from [Running devfile tasks to download yarn dependencies and build the project](#running-devfile-tasks-to-download-yarn-dependencies-and-build-the-project). - -Debugging the dashboard-frontend and dashboard-backend can be done with your browser's 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 `build` and `start` tasks, run the `Attach to Remote` debug launch configuration defined in `.vscode/launch.json`. - -### Pushing to GitHub and making a PR - -For PRs against 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. -For this reason, if your Che instance has the GitHub oAuth app set up, you must follow [these steps to request access](https://github.com/eclipse/che/issues/21627#issuecomment-1216592765) to push to `eclipse-che/che-dashboard`. - -To make a commit and push to remote, open a terminal in the `tools` container and run Git commands such as `git add` and `git push`. -You may choose 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 - -For building an image within a Che workspace on an OpenShift cluster, the cluster and OpenShift user must be configured to allow with rootless builds. In addition, the following attribute must be added to the devfile: -``` -attributes: - controller.devfile.io/scc: container-build -``` - -To build, run: -``` -podman build . -f build/dockerfiles/Dockerfile -t quay.io/eclipse/che-dashboard:next -``` - -### Build a new image and apply it to the CheCluster in the current context - -Export globally environment variables first: -```sh -$ export IMAGE_REGISTRY_USER_NAME= && \ - export IMAGE_REGISTRY_HOST= -``` - -To a new image and apply it to the CheCluster, run: -```sh -yarn build-and-patch -``` - -### Update dashboard on remote cluster using `skaffold.dev` - -To update the dashboard deployment you need access to the Kubernetes cluster (see [Running locally against remote Che Cluster (Node.js v18)](#running-locally-against-remote-che-cluster-nodejs-v18)) - -Then proceed with the following steps: - -```sh -# export an environment variable to define a repository you want images to be pushed, e.g.: -export DEFAULT_REPO="${IMAGE_REGISTRY_HOST}/${IMAGE_REGISTRY_USER_NAME}" -``` - -```sh -# and log in to the repository: -podman login quay.io -``` - -Now you can build the project and get the dashboard on the remote cluster updated: - -```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 -``` +To report or address issues and actively contribute to the codebase, please refer to [CONTRIBUTING.md](./CONTRIBUTING.md) for comprehensive details on our requirements and instructions on getting started. ## Branding