Contributing to AUP Learning Cloud¶

Thank you for your interest in contributing to AUP Learning Cloud! This document provides guidelines and setup instructions for developers.

Development Setup¶

Prerequisites¶

Python: 3.10+
Node.js: 20+
pnpm: 9+
Git: 2.30+

Initial Setup¶

Clone the repository

git clone https://github.com/AMDResearch/aup-learning-cloud-dev.git
cd aup-learning-cloud-dev

Install Python dependencies
```
pip install ruff pre-commit yamllint
```

Install frontend dependencies

cd runtime/admin/frontend/admin-frontend
pnpm install
cd -

Install pre-commit hooks (optional but recommended)
```
pre-commit install
```
This will automatically run lint checks before each commit.

Code Quality Tools¶

We use the following tools to maintain code quality:

Python (Ruff)¶

Linter: Checks code style and potential bugs
Formatter: Auto-formats code to match project style
Config: pyproject.toml

Run checks:

# Lint check
ruff check .

# Format check
ruff format --check .

# Auto-fix issues
ruff check --fix .
ruff format .

Frontend (ESLint + Prettier)¶

ESLint: JavaScript/TypeScript/Vue linter
Prettier: Code formatter
TypeScript: Type checking
Config: runtime/admin/frontend/admin-frontend/eslint.config.js, .prettierrc

Run checks:

cd runtime/admin/frontend/admin-frontend

# Lint
pnpm run lint

# Format check
pnpm run format:check

# Type check
pnpm run type-check

# Auto-fix
pnpm run lint:fix
pnpm run format

YAML (yamllint)¶

Config: .yamllint.yaml

Run checks:

yamllint .

Shell (ShellCheck)¶

Config: .shellcheckrc

Run checks:

# Install on Ubuntu/Debian
sudo apt-get install shellcheck

# Run
find . -name "*.sh" -o -name "*.bash" | \
  grep -v node_modules | \
  grep -v .git | \
  xargs -r shellcheck

Editor Configuration¶

VSCode (Recommended)¶

Install recommended extensions (prompt will appear automatically):
- Ruff
- Python
- Prettier
- ESLint
- Vue - Official (Volar)
- YAML
- ShellCheck
- EditorConfig
- GitLens
Settings are pre-configured in .vscode/settings.json:
- Format on save enabled
- Auto-organize imports
- Use project-specific formatters

Other Editors¶

EditorConfig configuration: .editorconfig
Use plugins for Ruff, ESLint, and Prettier in your editor

Before Submitting a PR¶

Run all lint checks locally:

# Python
ruff check .
ruff format --check .

# YAML
yamllint .

# Frontend (from runtime/admin/frontend/admin-frontend)
pnpm run lint
pnpm run format:check
pnpm run type-check

Ensure all checks pass:
- CI will automatically run these checks on your PR
- PRs with failing lint checks cannot be merged
Commit message format:
- Use clear, descriptive commit messages
- Start with a verb (Add, Fix, Update, Refactor, etc.)
- Keep the first line under 72 characters

Jupyter Notebooks¶

Teaching notebooks in projects/ have relaxed lint rules:

Imports don’t need to be at the top
import * is allowed for teaching purposes
Single-letter variables (e.g., x, y, l) are permitted
Unused variables are allowed (exploratory code)
Lambda assignments are acceptable (teaching patterns)

Standard production code rules apply to:

runtime/jupyterhub/files/hub/jupyterhub_config.py
scripts/
All other Python files

Line Endings¶

All files use LF (Unix-style) line endings
All files must end with a newline
Git is configured to automatically normalize line endings (.gitattributes)

If you’re on Windows, configure Git:

git config --global core.autocrlf input

Branch Naming Example¶

Prefix	Use Case	Example
feature/	Developing new features or enhancements	`feature/user-login`
bugfix/	Fixing bugs in development or staging	`bugfix/sidebar-display`
hotfix/	Urgent fixes for critical issues in Production	`hotfix/payment-gateway-crash`
refactor/	Code restructuring without changing functionality	`refactor/api-response-handler`
docs/	Documentation updates only	`docs/update-readme`
chore/	Routine tasks, dependency updates, build config	`chore/update-dependencies`
test/	Adding or correcting test cases	`test/add-unit-tests`
perf/	Performance optimizations	`perf/database-query-tuning`
style/	Code formatting, linting (no logic change)	`style/fix-lint-errors`
ci/	CI/CD configuration and scripts	`ci/github-actions-setup`

Questions?¶

Open an issue for bugs or feature requests
Check existing documentation in docs/

Thank you for contributing!