Improve Makefile documentation and add caching for notebooks repository (#150)

- Use shorter commit hash (7 chars) in frontend/COMMIT for consistency
- Add consistent annotations across all Makefiles about
kubeflow/notebooks repo
- Add intelligent caching to frontend Makefile setup:
  * Skip git fetch/checkout if already at target commit
  * Skip library rebuild if already built
  * Skip npm install if dependencies exist
  * Skip symlink recreation if already correct
  * Skip asset copying if already present
- Add automatic CSS and assets copying during setup
- Add fallback for short hash resolution with git rev-parse

Resolves issues with fresh setup and improves developer experience with
faster repeated setup runs.

---------

Signed-off-by: Harshit Nayan <harshitacademia@gmail.com>
Signed-off-by: Julius von Kohout <45896133+juliusvonkohout@users.noreply.github.com>
Co-authored-by: Julius von Kohout <45896133+juliusvonkohout@users.noreply.github.com>

Author: LogicalGuy77

.github/workflows/linting_bash_python_yaml_files.yaml

@@ -39,7 +39,7 @@ jobs:
         fetch-depth: 0
 
     - name: Install yamllint
-      run: python3 -m venv myenv && source myenv/bin/activate && pip install yamllint
+      run: pip install yamllint
 
     - name: YAML Formatting Guidelines
       run: |
@@ -88,7 +88,6 @@ jobs:
     - name: Run yamllint on changed files
       id: lint
       run: |
-        source myenv/bin/activate
         if grep -q 'No YAML files have changed in this PR.' changed_files_in_PR.txt; then
           echo "No YAML files have changed in this PR."
         else
@@ -132,7 +131,7 @@ jobs:
         fi
 
     - name: Display changed files
-      if: always() # Always run this step
+      if: always()  # Always run this step
       run: cat changed_files_in_PR.txt || echo "No bash files have changed in this PR."
 
     - name: Run ShellCheck on changed files

.github/workflows/stale.yaml

@@ -7,7 +7,7 @@ name: Mark stale issues and pull requests
 
 on:
   schedule:
-  - cron: '0 0 * * *' # Run every day at midnight
+  - cron: '0 0 * * *'  # Run every day at midnight
   workflow_dispatch:
 
 jobs:

Makefile

@@ -1,3 +1,8 @@
+# Local path to kubeflow/notebooks repo for common backend code.
+# Clone https://github.com/kubeflow/notebooks to develop locally.
+# Set KUBEFLOW_REPOSITORY env var or use default /tmp/notebooks.
+KUBEFLOW_REPOSITORY ?= /tmp/notebooks
+
 # Default to kserve if not specified, but allow override via environment variable
 GITHUB_REPOSITORY_OWNER ?= kserve
 IMG ?= ghcr.io/$(shell echo $(GITHUB_REPOSITORY_OWNER) | tr '[:upper:]' '[:lower:]')/models-web-app

backend/Makefile

@@ -1,8 +1,8 @@
 SHELL=bash
 
-# In order to develop locally you will need to use common python code
-# from the kubeflow/notebooks repo. You can clone the repo in a specific
-# folder and use the following ENV Var to configure it.
+# Local path to kubeflow/notebooks repository for common backend code.
+# Clone https://github.com/kubeflow/notebooks to develop locally.
+# Set KUBEFLOW_REPOSITORY environment variable or use the default /tmp/notebooks.
 KUBEFLOW_REPO ?= $(or $(KUBEFLOW_REPOSITORY),/tmp/notebooks)
 COMMON_BACKEND_DIR ?= ${KUBEFLOW_REPO}/components/crud-web-apps/common/backend
 

frontend/COMMIT

@@ -1 +1 @@
-0b835a7848ddcadf2c920a8e14aeae121ac982d9
+0b835a7

frontend/Makefile

@@ -4,7 +4,10 @@
 #   make setup KUBEFLOW_REPOSITORY=/path/to/kubeflow
 #   make setup KF_REPO=/path/to/kubeflow
 
-KUBEFLOW_REPOSITORY ?= $(or $(KF_REPO),../../notebooks)
+# Local path to kubeflow/notebooks repoSITORY for THE common frontend library.
+# Clone https://github.com/kubeflow/notebooks to develop locally.
+# Set KUBEFLOW_REPOSITORY ennvironment variable, or use the default ../../notebooks.
+KUBEFLOW_REPOSITORY ?= $(../../notebooks)
 KUBEFLOW_REMOTE ?= https://github.com/kubeflow/notebooks
 
 COMMIT_FILE := ./COMMIT
@@ -22,25 +25,50 @@ setup:
 	    echo "Cloning $(KUBEFLOW_REMOTE) into $(KUBEFLOW_REPOSITORY)"; \
 	    git clone "$(KUBEFLOW_REMOTE)" "$(KUBEFLOW_REPOSITORY)"; \
 	fi
-	@echo ">> Checking repository status"
 	@TARGET_COMMIT=$$(cat "$(COMMIT_FILE)"); \
-	cd "$(KUBEFLOW_REPOSITORY)" && \
-	git fetch "$(KUBEFLOW_REMOTE)" notebooks-v1 && \
-	git checkout "$$TARGET_COMMIT"
+	CURRENT_COMMIT=$$(cd "$(KUBEFLOW_REPOSITORY)" 2>/dev/null && git rev-parse --short=8 HEAD 2>/dev/null || echo ""); \
+	if [ "$$CURRENT_COMMIT" != "$$TARGET_COMMIT" ]; then \
+	    echo ">> Checking out target commit $$TARGET_COMMIT"; \
+	    cd "$(KUBEFLOW_REPOSITORY)" && \
+	    git fetch "$(KUBEFLOW_REMOTE)" notebooks-v1 && \
+	    git checkout "$$TARGET_COMMIT" || git checkout "$$(git rev-parse $$TARGET_COMMIT)"; \
+	else \
+	    echo ">> Already at target commit $$TARGET_COMMIT"; \
+	fi
 	@if [ ! -d "$(COMMON_LIBRARY_DIRECTORY)" ]; then \
-	    echo "Expected common lib at: $(COMMON_LIBRARY_DIRECTORY)"; \
+	    echo "Expected common library at: $(COMMON_LIBRARY_DIRECTORY)"; \
 	    echo "Verify KUBEFLOW_REPOSITORY is correct."; \
 	    exit 1; \
 	fi
-	@echo ">> Building kubeflow-common-library"
-	@cd "$(COMMON_LIBRARY_DIRECTORY)" && \
-	npm install && \
-	npm run build
-	@echo ">> Installing frontend dependencies and linking kubeflow-common-library"
-	@npm install
-	@rm -rf node_modules/kubeflow
-	@ln -s "$$(readlink -f $(COMMON_LIBRARY_DISTRIBUTION))" node_modules/kubeflow
-	@echo "✔ Setup complete. Now run: npm run build:watch"
+	@if [ ! -d "$(COMMON_LIBRARY_DISTRIBUTION)" ]; then \
+	    echo ">> Building kubeflow-common-library"; \
+	    cd "$(COMMON_LIBRARY_DIRECTORY)" && \
+	    npm install && \
+	    npm run build; \
+	else \
+	    echo ">> Kubeflow library already built"; \
+	fi
+	@if [ ! -d "node_modules" ]; then \
+	    echo ">> Installing frontend dependencies"; \
+	    npm install; \
+	else \
+	    echo ">> Frontend dependencies already installed"; \
+	fi
+	@if [ ! -L "node_modules/kubeflow" ] || [ "$$(readlink node_modules/kubeflow)" != "$$(readlink -f $(COMMON_LIBRARY_DISTRIBUTION))" ]; then \
+	    echo ">> Linking kubeflow-common-library"; \
+	    rm -rf node_modules/kubeflow; \
+	    ln -s "$$(readlink -f $(COMMON_LIBRARY_DISTRIBUTION))" node_modules/kubeflow; \
+	else \
+	    echo ">> Kubeflow library already linked"; \
+	fi
+	@if [ ! -d "src/styles" ] || [ ! -d "src/assets" ]; then \
+	    echo ">> Copying kubeflow styles and assets"; \
+	    npm run copyCSS; \
+	    npm run copyLibAssets; \
+	else \
+	    echo ">> Styles and assets already copied"; \
+	fi
+	@echo "✔ Setup complete. Now run: npm run serve:simple or npm run build:watch"
 
 clean:
 	@echo ">> Cleaning frontend node_modules"