Contributing to DotRun

Thank you for your interest in contributing to DotRun! We appreciate your time and effort in helping make this unified script management framework better for everyone. Whether you're fixing a bug, improving documentation, or proposing a new feature, your contributions are valuable and welcomed.

Code of Conduct
Ways to Contribute
Development Setup
Code Style Guidelines
Testing Your Changes
Pull Request Process
Commit Message Format
Getting Help

Code of Conduct

By participating in this project, you agree to maintain a respectful, inclusive, and collaborative environment. We expect all contributors to:

Be respectful and considerate in communication
Accept constructive criticism gracefully
Focus on what is best for the community
Show empathy towards other community members

Ways to Contribute

There are many ways you can contribute to DotRun:

Reporting Bugs

Found a bug? Help us fix it:

Check the issue tracker to see if it's already reported
If not, open a new issue with:
- A clear, descriptive title
- Steps to reproduce the issue
- Expected behavior vs actual behavior
- Your environment (OS, shell type, DotRun version)
- Any relevant error messages or logs

Suggesting Features

Have an idea for a new feature?

Check existing issues and discussions first
Open a new issue with the "enhancement" label
Clearly describe the feature and its benefits
Explain your use case and why it would be valuable
Consider implementation approaches if you have ideas

Improving Documentation

Documentation improvements are always welcome:

Fix typos or clarify existing documentation
Add examples and use cases
Improve the Wiki
Write tutorials or guides
Translate documentation (future support)

Contributing Code

Ready to contribute code? Here's how:

Start with "good first issue" or "help wanted" labels
Comment on the issue to let others know you're working on it
Follow the development setup and guidelines below
Submit a pull request when ready

Development Setup

Prerequisites

Git: For version control
Bash 4.0+: Primary development shell
ShellCheck: For linting (optional but recommended)
A Unix-like environment (Linux, macOS, or WSL on Windows)

Quick Setup

Fork the repository on GitHub

Clone your fork:

git clone https://github.com/YOUR_USERNAME/dotrun.git
cd dotrun

Set up the development environment:
```
./dev.sh
```
This script:
- Creates symlinks from ~/.local/share/dotrun to your repo's core/shared/dotrun directory
- Allows you to test changes immediately without reinstallation
- Preserves your existing DotRun installation and data

Add the upstream remote:

git remote add upstream https://github.com/jvPalma/dotrun.git

Create a branch for your changes:

git checkout -b feature/your-feature-name

Project Structure

dotrun/
├── core/
│   ├── shared/dotrun/          # Core DotRun files
│   │   ├── dr                  # Main executable
│   │   ├── core/               # Core functionality modules
│   │   │   ├── *.sh            # Feature modules
│   │   │   └── templates/      # Script templates
│   │   ├── helpers/            # Shared helper functions
│   │   ├── shell/              # Shell integration
│   │   │   ├── bash/           # Bash-specific code
│   │   │   ├── zsh/            # Zsh-specific code
│   │   │   └── fish/           # Fish-specific code
│   │   └── VERSION             # Version file
│   └── config/dotrun/          # Example scripts and configs
├── install.sh                  # Installation script
├── dev.sh                      # Development setup script
└── README.md                   # Project documentation

Development Workflow

Make your changes in the appropriate files
Test locally using dr commands (changes are live via symlinks)
Run ShellCheck on modified files (see Testing section)
Commit your changes with clear messages
Push to your fork and create a pull request

Code Style Guidelines

Shell Script Best Practices

DotRun follows industry-standard shell scripting conventions:

General Guidelines

Use ShellCheck: All shell scripts must pass ShellCheck linting
POSIX Compatibility: Write portable code when possible, but Bash 4.0+ features are allowed
Error Handling: Use set -euo pipefail at the start of scripts
Quoting: Always quote variables: "$variable" not $variable
Functions: Use lowercase with underscores for function names: my_function()
Constants: Use UPPERCASE for constants: TOOL_DIR, VERSION

Code Structure

#!/usr/bin/env bash
# Brief description of what this script does

set -euo pipefail

# Constants at the top
readonly CONSTANT_NAME="value"

# Function definitions
function_name() {
  local local_var="$1"
  # Function implementation
}

# Main execution
main() {
  # Main logic here
}

# Call main with all arguments
main "$@"

Naming Conventions

Variables: lowercase_with_underscores or UPPERCASE_CONSTANTS
Functions: lowercase_with_underscores()
Files: lowercase with hyphens for multi-word names (my-script.sh)

Comments and Documentation

Add comments for non-obvious logic
Use ### DOC blocks for script documentation
Explain "why" not "what" when the code is self-explanatory
Keep comments up-to-date with code changes

Example documentation block:

### DOC
# Description: Brief description of what the script does
#
# Usage: dr scriptname [options] [arguments]
#
# Examples:
#   dr scriptname --option value
#   dr scriptname argument
#
# Options:
#   --help    Show this help message
### DOC

Error Handling

# Check for required commands
if ! command -v required_command &>/dev/null; then
  echo "Error: required_command not found" >&2
  exit 1
fi

# Validate inputs
if [[ $# -lt 1 ]]; then
  echo "Error: Missing required argument" >&2
  return 1
fi

# Handle errors gracefully
if ! some_command; then
  echo "Warning: some_command failed, continuing..." >&2
fi

ShellCheck Compliance

Before submitting code, run ShellCheck:

# Check a single file
shellcheck path/to/script.sh

# Check all shell scripts in core
find core/shared/dotrun -name "*.sh" -exec shellcheck {} +

# Check the main dr executable
shellcheck core/shared/dotrun/dr

Common ShellCheck warnings to avoid:

SC2086: Quote variables to prevent word splitting
SC2181: Check exit code directly with if my_command; then
SC2155: Declare and assign separately to avoid masking return values
SC2164: Use cd foo || exit to handle cd failures

Testing Your Changes

Manual Testing

Run ./dev.sh to set up the development environment

Test your changes using real DotRun commands:

# Test script management
dr set test-script
dr test-script
dr list

# Test alias management
dr -a set test-aliases
dr -a list

# Test collection features
dr -col list

Test across different shells if modifying shell integration:

# Test in bash
bash -c "source ~/.bashrc && dr <your-command>"

# Test in zsh (if available)
zsh -c "source ~/.zshrc && dr <your-command>"

Test edge cases:
- Empty inputs
- Special characters in names
- Non-existent resources
- Permission issues

Automated Testing

While we don't have a comprehensive test suite yet, you should:

Run ShellCheck on all modified files
Verify your changes don't break existing functionality
Test installation on a clean system if modifying install.sh

Regression Testing

Before submitting:

Test core workflows:
- Creating, editing, and running scripts
- Managing aliases and configs
- Collection operations (add, update, sync)
- Tab completion functionality
Verify help and documentation:
- dr --help shows correct information
- dr help <command> works for affected commands
- Documentation is accurate

Pull Request Process

Before Submitting

Ensure your code follows the style guidelines
Run ShellCheck on all modified shell scripts
Test your changes thoroughly (see Testing section)
Update documentation if needed
Keep commits focused and atomic

Rebase on latest master branch:

git fetch upstream
git rebase upstream/master

Creating the Pull Request

Push your branch to your fork:

git push origin feature/your-feature-name

Open a pull request on GitHub with:
- Clear title: Summarize the change in one line
- Description: Explain what changed and why
- Related issues: Link related issues with "Fixes #123" or "Relates to #456"
- Testing: Describe how you tested the changes
- Screenshots: Include if relevant (especially for UI changes)

PR Template Example

## Description

Brief description of what this PR does and why.

## Related Issues

Fixes #123
Relates to #456

## Changes

- List of changes made
- Another change
- One more change

## Testing

- [ ] Ran ShellCheck on modified files
- [ ] Tested manually with `dr` commands
- [ ] Tested across different shells (if applicable)
- [ ] Verified documentation is accurate

## Checklist

- [ ] Code follows project style guidelines
- [ ] Comments added for non-obvious logic
- [ ] Documentation updated (README, Wiki, etc.)
- [ ] No breaking changes (or documented if unavoidable)

Review Process

A maintainer will review your PR
Address any feedback or requested changes
Once approved, a maintainer will merge your PR
Your contribution will be included in the next release

After Your PR is Merged

Delete your feature branch:

git branch -d feature/your-feature-name
git push origin --delete feature/your-feature-name

Update your fork:

git checkout master
git fetch upstream
git merge upstream/master
git push origin master

Commit Message Format

We follow the Conventional Commits specification for clear, standardized commit messages.

Format

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Types

feat: A new feature
fix: A bug fix
docs: Documentation only changes
style: Code style changes (formatting, missing semicolons, etc.)
refactor: Code changes that neither fix a bug nor add a feature
perf: Performance improvements
test: Adding or updating tests
chore: Changes to build process, tools, or dependencies

Examples

# Simple feature
feat: add fuzzy search for script names

# Bug fix with scope
fix(completion): resolve tab completion in fish shell

# Breaking change
feat!: redesign alias management to use file-based approach

BREAKING CHANGE: Aliases are now managed in files rather than individual entries.
Users need to migrate existing aliases using the provided migration script.

# Documentation
docs: update installation guide with WSL instructions

# Refactoring
refactor(core): extract duplicate code into shared helper

# Multiple changes
feat: add collection sync command

- Add sync command to check for updates
- Show modified files in collections
- Add --dry-run flag for preview

Guidelines

Use present tense: "add feature" not "added feature"
Use imperative mood: "move cursor to" not "moves cursor to"
Keep the first line under 72 characters
Separate subject from body with a blank line
Wrap body at 72 characters
Use body to explain what and why, not how

Getting Help

Need help with your contribution?

Resources

Documentation: Check the Wiki for detailed guides
FAQ: See frequently asked questions
Examples: Browse the core/config/dotrun directory for examples

Ask Questions

Issues: Open an issue with the "question" label
Discussions: Use GitHub Discussions for general questions
Pull Request: Ask questions directly in your PR if stuck

Contact

GitHub Issues: https://github.com/jvPalma/dotrun/issues
Project Maintainer: João Vieira Palma (@jvPalma)

License

By contributing to DotRun, you agree that your contributions will be licensed under the MIT License.

Thank you for contributing to DotRun! Your efforts help make script management better for developers everywhere.

Uh oh!

FilesExpand file tree

CONTRIBUTING.md

Latest commit

History