Skip to main content
Thank you for your interest in contributing to Gentleman.Dots! This guide will help you get started with contributing code, documentation, or ideas to the project.

​
Ways to Contribute

There are many ways to contribute to Gentleman.Dots:

Report Bugs

Found an issue? Let us know by creating a bug report

Suggest Features

Have an idea for improvement? Share it with the community

Submit Code

Fix bugs, add features, or improve existing functionality

Improve Documentation

Help make the docs clearer and more comprehensive

​
Getting Started

​
Fork and Clone the Repository

1

Fork the repository

Visit the Gentleman.Dots repository and click the “Fork” button in the top right.
2

Clone your fork

git clone [email protected]:YOUR_USERNAME/Gentleman.Dots.git
cd Gentleman.Dots
3

Add upstream remote

git remote add upstream [email protected]:Gentleman-Programming/Gentleman.Dots.git
4

Create a feature branch

git checkout -b feature/your-feature-name
Use descriptive branch names:
  • feature/add-zellij-theme
  • fix/tmux-navigation
  • docs/improve-installation

​
Development Workflow

​
Testing Your Changes

Always test your changes in a safe environment before submitting. Consider using a VM or container to avoid breaking your main system.
Before submitting changes:
1

Test the installation script (if modified)

# Create a test environment
docker run -it ubuntu:latest bash

# Or use a VM
# Then run the modified install script
bash install-linux-mac.sh
2

Test configuration changes

If you modified configs (Neovim, shell, terminal):
  • Back up your existing config: 
    cp -r ~/.config/nvim ~/.config/nvim.backup
  • Test the new config: 
    cp -r GentlemanNvim/nvim/* ~/.config/nvim/
nvim  # Test thoroughly
  • Verify there are no errors: 
    :checkhealth
:Lazy sync
3

Test on multiple platforms (if applicable)

If your changes affect multiple platforms:
  • macOS
  • Linux (Ubuntu/Debian)
  • Arch Linux
  • WSL
Test on as many as you have access to.

​
Code Style and Standards

​
Shell Scripts (Bash)

#!/bin/bash
set -e  # Exit on error

# Use meaningful variable names
install_homebrew() {
  if ! command -v brew &>/dev/null; then
    echo "Installing Homebrew..."
    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
  else
    echo "Homebrew already installed"
  fi
}

# Use color variables defined at the top
echo -e "${GREEN}Success!${NC}"
Shell Script Standards:
  • Use #!/bin/bash shebang
  • Always use set -e for error handling
  • Use meaningful function and variable names
  • Add comments explaining complex logic
  • Use the color variables defined in the script ($GREEN, $RED, etc.)
  • Follow the existing code structure and indentation

​
Lua Configuration (Neovim)

-- Clear description of plugin purpose
return {
  "username/plugin-name",
  dependencies = {
    "required-plugin",
  },
  opts = {
    -- Organized options with comments
    enable_feature = true,  -- Enable X feature
    timeout = 1000,         -- Timeout in ms
  },
  keys = {
    { "<leader>key", "<cmd>Command<cr>", desc = "Clear description" },
  },
}
Lua Configuration Standards:
  • Use 2-space indentation
  • Add clear comments for non-obvious configurations
  • Include desc field for all keymaps
  • Group related options together
  • Follow LazyVim’s plugin structure
  • Use lazy-loading when appropriate

​
TOML/Config Files

starship.toml
# Group related settings
[character]
success_symbol = "[󱗞 ](fg:green)"
error_symbol = "[󱗞 ](fg:red)"

# Use comments to explain custom values
[cmd_duration]
min_time = 500  # Show duration for commands > 500ms
format = " took [ $duration]($style) "
Config File Standards:
  • Use comments to explain non-obvious settings
  • Group related configurations
  • Keep formatting consistent with existing files
  • Use meaningful variable/key names

​
Commit Message Guidelines

Use clear, descriptive commit messages following this format: 
type(scope): brief description

Detailed explanation of what changed and why.

Fixes #issue-number
Types:
  • feat: New feature
  • fix: Bug fix
  • docs: Documentation changes
  • style: Code style changes (formatting, no logic change)
  • refactor: Code refactoring
  • test: Adding or updating tests
  • chore: Maintenance tasks
Examples: 
feat(nvim): add support for Claude Code AI assistant

Added claudecode.nvim plugin configuration with proper keybindings
and integration with existing AI plugin management.

feat(shell): add Zellij configuration for Fish shell

Implemented automatic Zellij startup for Fish users with proper
environment variable handling.

fix(install): correct Homebrew path detection on Linux

Fixed issue where Linux Homebrew path was incorrectly set,
causing installation failures.

Fixes #123

docs(readme): improve WSL installation instructions

Clarified step-by-step process for Windows users, added
troubleshooting section for common WSL issues.

​
Submitting Your Contribution

​
Creating a Pull Request

1

Commit your changes

git add .
git commit -m "feat(scope): descriptive message"
2

Push to your fork

git push origin feature/your-feature-name
3

Create Pull Request

  1. Go to the original Gentleman.Dots repository
  2. Click “New Pull Request”
  3. Click “compare across forks”
  4. Select your fork and branch
  5. Fill out the PR template

​
Pull Request Template

When creating a PR, include: 
## Description
Brief description of what this PR does.

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Checklist
- [ ] I have tested these changes locally
- [ ] I have updated documentation (if needed)
- [ ] My code follows the project's style guidelines
- [ ] I have added comments for complex logic
- [ ] I have tested on relevant platforms (macOS/Linux/WSL)

## Testing
Describe how you tested these changes:
- Platform: macOS 14 / Ubuntu 22.04 / Arch Linux / WSL2
- Shell: Zsh / Fish / Nushell
- Terminal: Alacritty / WezTerm / Kitty

## Screenshots (if applicable)
Add screenshots showing the changes.

## Related Issues
Fixes #issue-number
Related to #issue-number
The more detail you provide in your PR description, the faster it can be reviewed and merged!

​
Areas for Contribution

Here are some areas where contributions are especially welcome:

​
High Priority

  • Test and improve WSL compatibility
  • Add support for NixOS
  • Improve Arch Linux installation
  • Add FreeBSD support
  • Add configurations for new terminals
  • Improve existing terminal themes
  • Add theme variants (light mode, other color schemes)
  • Add support for other shells (bash, xonsh)
  • Improve Nushell completions
  • Add more Fish shell functions
  • Optimize shell startup time
  • Add support for new AI assistants
  • Improve LSP configurations
  • Add language-specific configurations
  • Create custom Neovim plugins
  • Add error recovery mechanisms
  • Improve progress indicators
  • Add rollback functionality
  • Better platform detection

​
Documentation

  • Add more troubleshooting guides
  • Create video tutorials
  • Translate documentation to other languages
  • Add more code examples
  • Improve README with better screenshots

​
Community

  • Answer questions in GitHub issues
  • Help review pull requests
  • Share your custom configurations
  • Create blog posts or tutorials

​
Testing Checklist

Before submitting, ensure:
1

Functionality

  • New features work as expected
  • Existing features are not broken
  • Edge cases are handled
2

Code Quality

  • Code follows style guidelines
  • Comments explain complex logic
  • No unnecessary code or debug statements
  • Error handling is appropriate
3

Platform Testing

Test on all relevant platforms:
  • macOS (Intel and Apple Silicon if possible)
  • Ubuntu/Debian Linux
  • Arch Linux
  • WSL2 (if applicable)
4

Documentation

  • README updated (if needed)
  • Code comments added
  • Documentation site updated (if applicable)
  • CHANGELOG updated

​
Code Review Process

​
What to Expect

  1. Initial Review (1-3 days)
    • Maintainers will review your PR
    • May request changes or ask questions
  2. Revision Phase
    • Address feedback
    • Push updates to your branch
    • PR will be re-reviewed
  3. Approval and Merge
    • Once approved, PR will be merged
    • Your contribution will be in the next release!

​
Responding to Feedback

Be patient and receptive to feedback. Code review is a collaborative process to improve the codebase.
When responding to review comments: 
# Make requested changes
git add .
git commit -m "fix: address review comments"
git push origin feature/your-feature-name
The PR will automatically update.

​
Project Structure

Understanding the project structure helps with contributions: 
Gentleman.Dots/
├── install-linux-mac.sh       # Main installation script
├── README.md                  # Project documentation
├── alacritty.toml            # Alacritty terminal config
├── .wezterm.lua              # WezTerm config
├── starship.toml             # Starship prompt config
├── GentlemanNvim/
│   └── nvim/
│       ├── init.lua          # Neovim entry point
│       └── lua/
│           ├── config/       # Core Neovim config
│           │   ├── keymaps.lua
│           │   ├── options.lua
│           │   └── autocmds.lua
│           └── plugins/      # Plugin configurations
│               ├── disabled.lua
│               ├── opencode.lua
│               └── ...
├── GentlemanFish/
│   └── fish/                 # Fish shell config
├── GentlemanZsh/
│   ├── .zshrc               # Zsh configuration
│   └── .p10k.zsh            # Powerlevel10k theme
├── GentlemanNushell/
│   ├── config.nu            # Nushell config
│   └── env.nu               # Nushell environment
├── GentlemanTmux/
│   └── tmux.conf            # Tmux configuration
├── GentlemanZellij/
│   └── zellij/              # Zellij configs
├── GentlemanKitty/          # Kitty terminal
└── GentlemanGhostty/        # Ghostty terminal

​
Experimental Features

Want to work on bleeding-edge features? Check out the nix-migration branch for experimental Nix-based configurations (macOS only).
git checkout nix-migration
This branch contains:
  • Nix package manager integration
  • Declarative system configuration
  • Experimental features before they hit main

​
License

By contributing to Gentleman.Dots, you agree that your contributions will be licensed under the same license as the project.

​
Getting Help

If you need help with your contribution:

GitHub Discussions

Ask questions and discuss ideas

GitHub Issues

Report bugs or check existing issues

​
Recognition

Contributors are recognized in:
  • GitHub Contributors page
  • Project README
  • Release notes for significant contributions
Thank you for contributing to Gentleman.Dots! Your contributions help make this project better for everyone.

Build docs developers (and LLMs) love

Get started for freeTalk to us