This document outlines the commit message conventions for the Docker Simple Panel project.
- Write clear, concise commit messages that explain what changed and why
- Use the imperative mood in the subject line (e.g., "Add feature" not "Added feature")
- Keep the subject line under 72 characters
- Separate subject from body with a blank line
- Use the body to explain what and why vs. how
<type>: <subject>
[optional body]
[optional footer]
The subject line should be structured as follows:
Format: <type>: <description>
Use one of the following types to categorize your commit:
- feat: A new feature for the user
- fix: A bug fix
- docs: Documentation only changes
- style: Changes that do not affect the meaning of the code (formatting, missing semi-colons, etc.)
- refactor: Code change that neither fixes a bug nor adds a feature
- perf: Performance improvements
- test: Adding missing tests or correcting existing tests
- build: Changes to build system or external dependencies
- ci: Changes to CI configuration files and scripts
- chore: Other changes that don't modify src or test files
- revert: Reverts a previous commit
- Use imperative, present tense: "change" not "changed" nor "changes"
- Don't capitalize the first letter
- No period (.) at the end
- Be specific and descriptive
Examples:
- ✅
feat: add container restart endpoint - ✅
fix: resolve JWT token expiration issue - ✅
docs: update API documentation for volumes endpoint - ❌
Added new feature(uses past tense, not imperative) - ❌
Fix bug(not descriptive enough) - ❌
Updates(too vague, not imperative)
- Use the body to explain what and why, not how
- Wrap lines at 72 characters
- Can include multiple paragraphs separated by blank lines
- Can use bullet points (use
-or*)
Example:
fix: prevent race condition in container status updates
The container status polling was causing race conditions when multiple
requests were made simultaneously. This fix:
- Adds mutex locks around container state reads
- Implements read/write lock pattern for better concurrency
- Ensures atomic updates to container status cache
This resolves intermittent 500 errors when rapidly refreshing the UI.
Use the footer for:
- Breaking changes: Start with
BREAKING CHANGE:followed by description - Issue references: Use
Fixes #123,Closes #123, orRefs #123 - Co-authors: Use
Co-authored-by: Name <email>
Example:
feat: change authentication to use JWT refresh tokens
BREAKING CHANGE: The login endpoint now returns both access and refresh
tokens. Clients must be updated to handle the new response format.
Fixes #45
Co-authored-by: John Doe <john@example.com>
feat: add volume deletion endpoint
Implements DELETE /api/volumes/{name} endpoint with proper
authentication and error handling.
fix: correct container health status display
Health status was showing as "unknown" for healthy containers due to
incorrect field mapping in the Docker API response.
Fixes #67
docs: add WebSocket log streaming examples
Added JavaScript and curl examples for connecting to the container
log streaming endpoint.
refactor: extract Docker client initialization into factory
Moves Docker client setup logic into a dedicated factory function to
improve testability and reduce code duplication across handlers.
feat: migrate to Svelte 5 runes syntax
BREAKING CHANGE: The frontend now requires Svelte 5. All components
have been updated to use runes ($state, $derived, $effect) instead of
the old reactivity system.
Refs #89
fix: resolve WebSocket connection timeout on slow networks
The WebSocket upgrade was failing on networks with >500ms latency due
to overly aggressive timeout settings.
Changes:
- Increase WebSocket handshake timeout from 5s to 30s
- Add retry logic with exponential backoff
- Improve error messages for connection failures
This should improve reliability for users on slower connections or
behind corporate proxies.
Fixes #102
- ✅ Use the imperative mood ("add" not "added")
- ✅ Be specific and descriptive
- ✅ Reference issues when applicable
- ✅ Explain the "why" in the body for non-trivial changes
- ✅ Keep commits focused on a single logical change
- ✅ Add Co-authored-by for pair programming or collaborated work
- ❌ Write vague messages like "fix bug" or "update code"
- ❌ Include multiple unrelated changes in one commit
- ❌ Use past tense or gerunds ("fixed", "fixing")
- ❌ End subject line with a period
- ❌ Exceed 72 characters in the subject line
- ❌ Leave the commit message empty or use placeholders like "WIP"
chore: initial commit
For merge commits, GitHub will auto-generate messages. If writing manually:
Merge pull request #123 from user/feature-branch
feat: add container grouping by labels
revert: feat: add experimental caching layer
This reverts commit abc123def456.
The caching layer was causing data inconsistencies in production.
You can optionally configure a commit message template to help remind you of the format:
git config commit.template .gitmessageThen create a .gitmessage file in your home directory or project root:
<type>: <subject>
# Why is this change needed?
#
# How does it address the issue?
#
# What are the side effects?
#
# Fixes #
Consider using tools like commitlint to enforce these conventions automatically.
These guidelines are inspired by:
If you're unsure about how to format a commit message, look at recent commits in the repository for examples or ask in the pull request discussion.