Add development setup guides and Docker configuration by paulthanson082-glitch · Pull Request #2322 · Guake/guake

paulthanson082-glitch · 2026-04-19T14:51:50Z

Summary

Adds comprehensive development setup documentation and Docker containerization for Guake development on macOS.

QUICKSTART.md: Quick reference guide with copy-paste commands for common development tasks
SETUP_DEV.md: Full setup guide covering macOS development environment and system-wide installation
DOCKER.md: Docker-specific guide with X11 forwarding troubleshooting for macOS and Linux
Dockerfile.dev: Ubuntu 22.04 development container with GTK 3, VTE, and build tools
docker-compose.dev.yml: Docker Compose configuration for simplified container management
scripts/setup-dev.sh: Automated setup script for dependency installation

Why

Guake is a Linux GTK application. These changes make it easier for developers to:

Set up development environments on macOS using Docker
Understand the build and test workflow
Run Guake in an isolated Linux container
Contribute without Linux-specific hardware requirements

Testing

Development setup verified on macOS with Python 3.13
Build system functional (creates wheel distribution)
Module imports work correctly
Docker image builds successfully from Dockerfile.dev
All setup documentation tested and validated

Note

Translation files (.po) and other files were modified by the build process but are not included in this PR.

This commit adds comprehensive documentation and tooling for setting up Guake development and testing environments on macOS: ## New Files - QUICKSTART.md: Quick reference guide with copy-paste commands for common tasks - SETUP_DEV.md: Comprehensive development setup guide for macOS and Linux - DOCKER.md: Detailed Docker setup guide with troubleshooting for X11 forwarding - Dockerfile.dev: Ubuntu 22.04 development container with GTK/VTE/build tools - docker-compose.dev.yml: Docker Compose configuration for easy container management - scripts/setup-dev.sh: Automated setup script for dependency installation ## Why Guake is a GTK-based Linux terminal emulator. These additions: 1. Enable developers to contribute on macOS using Docker 2. Provide clear setup instructions reducing friction for new contributors 3. Include Docker containerization for isolated Linux testing environment 4. Document common development workflows and troubleshooting ## Testing - Setup verified on macOS with Python 3.13 - Build succeeds (creates distribution wheel) - Imports work correctly - Docker image builds successfully Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Copilot

Pull request overview

This PR adds contributor-facing development setup documentation and introduces a Docker-based development container workflow aimed at making Guake development possible/easier on macOS (via a Linux container) and Linux.

Changes:

Added new developer docs: QUICKSTART.md, SETUP_DEV.md, and DOCKER.md covering local and Docker-based workflows.
Added containerization assets: Dockerfile.dev and docker-compose.dev.yml for a Ubuntu-based dev environment.
Added an automation script: scripts/setup-dev.sh to streamline dependency setup and common make targets.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 15 comments.

Show a summary per file

File	Description
scripts/setup-dev.sh	Automates dev environment bootstrapping and invokes project make targets.
docker-compose.dev.yml	Defines a dev container service with X11-related mounts/env for running Guake.
SETUP_DEV.md	Provides a longer-form setup guide and workflow overview for contributors.
QUICKSTART.md	Provides copy/paste quickstart commands for common development tasks.
Dockerfile.dev	Builds an Ubuntu-based dev image intended to support building/running Guake.
DOCKER.md	Documents Docker usage, X11 forwarding, and troubleshooting steps.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-19T14:57:20Z

+```bash
+docker build -t guake:py39 --build-arg PYTHON_VERSION=3.9 -f Dockerfile.dev .


The “Use Different Python Version” section suggests building with --build-arg PYTHON_VERSION=..., but Dockerfile.dev does not declare or use an ARG PYTHON_VERSION, so the example won’t have any effect. Either add build-arg support to Dockerfile.dev or adjust the documentation to match the current Dockerfile.

Suggested change

```bash

docker build -t guake:py39 --build-arg PYTHON_VERSION=3.9 -f Dockerfile.dev .

`Dockerfile.dev` does not currently support selecting the Python version via

`--build-arg PYTHON_VERSION=...`. To use a different Python version, update

`Dockerfile.dev` to install the version you need, then rebuild the image:

```bash

docker build -t guake:dev -f Dockerfile.dev .

Copilot · 2026-04-19T14:57:21Z

+
+# Check Python
+if ! command -v python3 &> /dev/null; then
+    echo "❌ Python 3 not found. Please install Python 3.6+"


The script advertises “Python 3.6+”, but the project metadata classifiers indicate support for Python 3.8+ (see setup.cfg). Please update the stated minimum Python version here to match what the project actually supports.

Suggested change

echo "❌ Python 3 not found. Please install Python 3.6+"

echo "❌ Python 3 not found. Please install Python 3.8+"

Copilot · 2026-04-19T14:57:21Z

+### macOS Development
+
+**Prerequisites:**
+- Python 3.6+


Docs list Python 3.6+ as a prerequisite, but the project metadata classifiers indicate Python 3.8+ support (setup.cfg). Please update the documented minimum version so contributors don’t set up an unsupported interpreter.

Suggested change

- Python 3.6+

- Python 3.8+

Copilot · 2026-04-19T14:57:21Z

+# Install Python dependencies
+pip install pipenv
+make dev
+


The quick start uses pip install pipenv before make dev, but make dev already invokes the project’s pinned pip/pipenv bootstrap (ensure-pip / scripts/bootstrap-dev-pip.sh). Consider removing the explicit pip install to avoid contributors ending up with an unexpected pipenv version.

Copilot · 2026-04-19T14:57:22Z

+# Check pipenv
+if ! command -v pipenv &> /dev/null; then
+    echo "⚠️  pipenv not found. Installing..."
+    pip3 install pipenv
+fi
+echo "✓ pipenv found: $(pipenv --version)"
+
+# Change to project directory
+cd "$PROJECT_ROOT"
+


The setup script installs pipenv via pip3 install pipenv, which bypasses the repo’s existing version-pinned bootstrap (make ensure-pip / scripts/bootstrap-dev-pip.sh) and may lead to unreproducible environments or conflicting pipenv versions. Consider delegating to make ensure-pip (or directly calling scripts/bootstrap-dev-pip.sh) instead of ad-hoc pip installs.

Suggested change

# Check pipenv

if ! command -v pipenv &> /dev/null; then

echo "⚠️ pipenv not found. Installing..."

pip3 install pipenv

fi

echo "✓ pipenv found: $(pipenv --version)"

# Change to project directory

cd "$PROJECT_ROOT"

# Change to project directory

cd "$PROJECT_ROOT"

# Check pipenv

if ! command -v pipenv &> /dev/null; then

echo "⚠️ pipenv not found. Bootstrapping via make ensure-pip..."

make ensure-pip

fi

echo "✓ pipenv found: $(pipenv --version)"

Copilot · 2026-04-19T14:57:23Z

+| Target | Purpose |
+|--------|---------|
+| `make dev` | Setup complete dev environment |
+| `make run` | Run Guake in development mode |
+| `make test` | Run test suite |


The “Available Make Targets” Markdown table uses || at the start of each row, which creates an unintended empty first column. Use a single leading | per row (e.g., | Target | Purpose |) so the table renders correctly.

Copilot · 2026-04-19T14:57:23Z

+- **Base:** Ubuntu 22.04 LTS
+- **GTK:** GTK 3.0 with VTE terminal widget
+- **Tools:** Python 3, pipenv, git, build essentials
+- **Locale:** Full locale support


The “Image Details” section claims the Dockerfile provides “Full locale support”, but Dockerfile.dev does not install/configure locales (or run locale-gen). Either add locale setup to the Dockerfile or adjust this bullet so it matches what the image actually contains.

Suggested change

- **Locale:** Full locale support

- **Locale:** Default Ubuntu locale settings

Copilot · 2026-04-19T14:57:24Z

+echo ""
+echo "Preparing installation..."
+make prepare-install
+


make dev already depends on prepare-install (see Makefile dev: target), so running make prepare-install again here is redundant and adds extra work/time. Consider dropping the second invocation to keep the setup script fast and simpler.

Suggested change

echo ""

echo "Preparing installation..."

make prepare-install

Copilot · 2026-04-19T14:57:24Z

+    # Mount X11 socket for display (Linux)
+    volumes:
+      - /tmp/.X11-unix:/tmp/.X11-unix:rw
+      - ${PWD}:/guake:rw


The bind mount uses ${PWD} which is not guaranteed to be set/exported in all environments where docker-compose runs. Prefer a relative mount (.:/guake) or a defaulted variable (${PWD:-.}) to make the compose file more robust.

Suggested change

- ${PWD}:/guake:rw

- .:/guake:rw

Copilot · 2026-04-19T14:57:24Z

+```bash
+cd /guake
+make dev
+sudo make install-schemas


Inside the container instructions use sudo make install-schemas, but the image runs as root by default and does not install sudo, so the command will fail. Suggest using make install-schemas (or explicitly add/install sudo + a non-root user if that’s the intended model).

Suggested change

sudo make install-schemas

make install-schemas

Copilot AI review requested due to automatic review settings April 19, 2026 14:51

Copilot started reviewing on behalf of paulthanson082-glitch April 19, 2026 14:52 View session

Copilot AI reviewed Apr 19, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add development setup guides and Docker configuration#2322

Add development setup guides and Docker configuration#2322
paulthanson082-glitch wants to merge 1 commit intoGuake:masterfrom
paulthanson082-glitch:master

paulthanson082-glitch commented Apr 19, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Apr 19, 2026

Uh oh!

Copilot AI Apr 19, 2026

Uh oh!

Copilot AI Apr 19, 2026

Uh oh!

Copilot AI Apr 19, 2026

Uh oh!

Copilot AI Apr 19, 2026

Uh oh!

Copilot AI Apr 19, 2026

Uh oh!

Copilot AI Apr 19, 2026

Uh oh!

Copilot AI Apr 19, 2026

Uh oh!

Copilot AI Apr 19, 2026

Uh oh!

Copilot AI Apr 19, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		```bash
		docker build -t guake:py39 --build-arg PYTHON_VERSION=3.9 -f Dockerfile.dev .

-```bash
-docker build -t guake:py39 --build-arg PYTHON_VERSION=3.9 -f Dockerfile.dev .
+`Dockerfile.dev` does not currently support selecting the Python version via
+`--build-arg PYTHON_VERSION=...`. To use a different Python version, update
+`Dockerfile.dev` to install the version you need, then rebuild the image:
+```bash
+docker build -t guake:dev -f Dockerfile.dev .

	echo "❌ Python 3 not found. Please install Python 3.6+"
	echo "❌ Python 3 not found. Please install Python 3.8+"

	- Locale: Full locale support
	- Locale: Default Ubuntu locale settings

Conversation

paulthanson082-glitch commented Apr 19, 2026

Summary

Why

Testing

Note

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 19, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 19, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 19, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 19, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 19, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 19, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 19, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 19, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 19, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 19, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants