mirror of
https://github.com/ivuorinen/phpenv.fish.git
synced 2026-01-26 03:04:01 +00:00
chore(deps): update pre-commit hooks and implement repository improvements (#38)
* Initial plan * Implement code refactoring, pre-commit enhancements, and documentation improvements Co-authored-by: ivuorinen <11024+ivuorinen@users.noreply.github.com> * chore(deps): update pre-commit hooks to latest versions Co-authored-by: ivuorinen <11024+ivuorinen@users.noreply.github.com> * docs: fix markdown linting issues in README and CONTRIBUTING Co-authored-by: ivuorinen <11024+ivuorinen@users.noreply.github.com> * feat(pre-commit): add editorconfig-checker for code style validation - Add editorconfig-checker hook to validate .editorconfig rules - Update .editorconfig to allow 200 char lines in markdown files (aligns with markdownlint config) - Fix .secrets.baseline to have proper final newline - All files now pass editorconfig validation Co-authored-by: ivuorinen <11024+ivuorinen@users.noreply.github.com> * chore: copilot cr fix in phpenv.fish Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: ivuorinen <11024+ivuorinen@users.noreply.github.com> Co-authored-by: Ismo Vuorinen <ismo@ivuorinen.net> Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
This commit is contained in:
Copilot
GitHub
313
CONTRIBUTING.md
Normal file
313
CONTRIBUTING.md
Normal file
@@ -0,0 +1,313 @@
|
||||
# Contributing to phpenv.fish
|
||||
|
||||
Thank you for your interest in contributing to phpenv.fish! This document provides guidelines and instructions for contributors.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Development Setup](#development-setup)
|
||||
- [Code Architecture](#code-architecture)
|
||||
- [Making Changes](#making-changes)
|
||||
- [Testing](#testing)
|
||||
- [Code Quality](#code-quality)
|
||||
- [Performance Guidelines](#performance-guidelines)
|
||||
- [Submitting Changes](#submitting-changes)
|
||||
|
||||
## Development Setup
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Fish Shell 3.0+
|
||||
- Homebrew (for PHP version management)
|
||||
- jq (JSON processor)
|
||||
- Git
|
||||
|
||||
### Installation for Development
|
||||
|
||||
1. Fork and clone the repository:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/YOUR-USERNAME/phpenv.fish.git
|
||||
cd phpenv.fish
|
||||
```
|
||||
|
||||
2. Link the development version to your Fish config:
|
||||
|
||||
```bash
|
||||
# Create backup of existing installation if any
|
||||
mv ~/.config/fish/functions/phpenv.fish ~/.config/fish/functions/phpenv.fish.backup 2>/dev/null || true
|
||||
|
||||
# Link development version
|
||||
ln -sf $PWD/functions/phpenv.fish ~/.config/fish/functions/phpenv.fish
|
||||
ln -sf $PWD/completions/phpenv.fish ~/.config/fish/completions/phpenv.fish
|
||||
ln -sf $PWD/conf.d/phpenv.fish ~/.config/fish/conf.d/phpenv.fish
|
||||
```
|
||||
|
||||
3. Install dependencies:
|
||||
|
||||
```bash
|
||||
brew install jq
|
||||
brew tap shivammathur/php
|
||||
brew tap shivammathur/extensions
|
||||
```
|
||||
|
||||
4. Set up pre-commit hooks:
|
||||
|
||||
```bash
|
||||
pip install pre-commit
|
||||
pre-commit install
|
||||
```
|
||||
|
||||
### Testing Changes
|
||||
|
||||
Since this is a Fish shell plugin, test changes by:
|
||||
|
||||
```bash
|
||||
# Reload the function after changes
|
||||
source functions/phpenv.fish
|
||||
|
||||
# Test basic commands
|
||||
phpenv help
|
||||
phpenv versions
|
||||
phpenv current
|
||||
phpenv doctor
|
||||
|
||||
# Test specific functionality
|
||||
phpenv install 8.3 # if not already installed
|
||||
phpenv use 8.3
|
||||
phpenv list
|
||||
```
|
||||
|
||||
## Code Architecture
|
||||
|
||||
### Core Components
|
||||
|
||||
1. **Main Dispatcher (`functions/phpenv.fish`)**
|
||||
- Entry point function that routes commands to internal functions
|
||||
- All subcommands are implemented as `__phpenv_*` functions
|
||||
- Version detection logic in `__phpenv_detect_version`
|
||||
|
||||
2. **Completions (`completions/phpenv.fish`)**
|
||||
- Provides tab completions for all commands
|
||||
- Fetches available versions dynamically from shivammathur/setup-php
|
||||
|
||||
3. **Configuration (`conf.d/phpenv.fish`)**
|
||||
- Sets up Fish universal variables on load
|
||||
- Handles PATH initialization
|
||||
|
||||
### Key Design Patterns
|
||||
|
||||
- **Performance Focus**: Direct directory checks instead of `brew list` (100-1000x faster)
|
||||
- **Fish Universal Variables**: Used for configuration persistence
|
||||
- **Homebrew Integration**: Uses shivammathur taps for PHP/extension installation
|
||||
- **Version File Priority**: `.php-version` > `.tool-version` > `composer.json` > global > system
|
||||
|
||||
### Version Detection Flow
|
||||
|
||||
1. Check for `.php-version` file (exact version)
|
||||
2. Check for `.tool-version` file (parse PHP line)
|
||||
3. Check `composer.json` for PHP constraints (semver resolution)
|
||||
4. Use global version from Fish universal variable
|
||||
5. Fall back to system PHP
|
||||
|
||||
## Making Changes
|
||||
|
||||
### Adding a New Command
|
||||
|
||||
1. Add case in main `phpenv` function switch statement
|
||||
2. Implement `__phpenv_<command>` function
|
||||
3. Add completions in `completions/phpenv.fish`
|
||||
4. Update help text in `__phpenv_help`
|
||||
|
||||
Example:
|
||||
|
||||
```fish
|
||||
# In main phpenv function
|
||||
case mynewcommand
|
||||
__phpenv_mynewcommand $phpenv_args
|
||||
|
||||
# New function implementation
|
||||
function __phpenv_mynewcommand
|
||||
# Implementation here
|
||||
end
|
||||
```
|
||||
|
||||
### Modifying Version Detection
|
||||
|
||||
- Edit `__phpenv_detect_version` function
|
||||
- Maintain priority order of version sources
|
||||
- Test with various project configurations
|
||||
|
||||
### Working with Homebrew Integration
|
||||
|
||||
- PHP versions: `shivammathur/php/php@<version>`
|
||||
- Extensions: `shivammathur/extensions/<extension>@<php-version>`
|
||||
- Check formula existence before operations
|
||||
|
||||
## Testing
|
||||
|
||||
### Manual Testing
|
||||
|
||||
Test all major functionality:
|
||||
|
||||
```bash
|
||||
# Version management
|
||||
phpenv install 8.3
|
||||
phpenv use 8.3
|
||||
phpenv local 8.2
|
||||
phpenv global 8.3
|
||||
|
||||
# Extension management
|
||||
phpenv extensions install xdebug
|
||||
phpenv extensions list
|
||||
|
||||
# Configuration
|
||||
phpenv config set auto-switch true
|
||||
phpenv config list
|
||||
|
||||
# Diagnostics
|
||||
phpenv doctor
|
||||
phpenv current
|
||||
phpenv which php
|
||||
```
|
||||
|
||||
### Edge Cases
|
||||
|
||||
Test edge cases:
|
||||
|
||||
- Missing jq dependency
|
||||
- Network connectivity issues
|
||||
- Invalid version files
|
||||
- Corrupt installations
|
||||
- Missing Homebrew taps
|
||||
|
||||
## Code Quality
|
||||
|
||||
### Pre-commit Hooks
|
||||
|
||||
The repository uses several pre-commit hooks for code quality:
|
||||
|
||||
- **Security**: `detect-secrets`, `gitleaks`, `checkov`
|
||||
- **Shell**: `shellcheck`, `shfmt`
|
||||
- **Format**: `markdownlint`, `yamllint`
|
||||
- **General**: File format validation, trailing whitespace removal
|
||||
|
||||
Run hooks manually:
|
||||
|
||||
```bash
|
||||
pre-commit run --all-files
|
||||
```
|
||||
|
||||
### Code Style Requirements
|
||||
|
||||
- Maximum line length: 120 characters (enforced by `.editorconfig`)
|
||||
- Use LF line endings
|
||||
- UTF-8 encoding
|
||||
- Trim trailing whitespace
|
||||
- Insert final newline
|
||||
|
||||
### Fish Shell Best Practices
|
||||
|
||||
- Use local variables (`set -l`) for function scope
|
||||
- Use session variables (`set -g`) for per-shell configuration
|
||||
- Use universal variables (`set -U`) only for persistent settings
|
||||
- Prefix all internal functions with `__phpenv_`
|
||||
- Use descriptive variable names with `phpenv_` prefix
|
||||
- Handle errors gracefully with proper return codes
|
||||
|
||||
## Performance Guidelines
|
||||
|
||||
### Optimization Principles
|
||||
|
||||
1. **Cache expensive operations** (API calls, filesystem checks)
|
||||
2. **Unify repeated patterns** into helper functions
|
||||
3. **Use session variables** instead of universal where possible
|
||||
4. **Minimize network requests** and subprocess calls
|
||||
|
||||
### Caching System
|
||||
|
||||
The codebase uses intelligent caching:
|
||||
|
||||
- `__phpenv_version_cache`: 5-minute cache for API version data
|
||||
- `__phpenv_cellar_cache`: Permanent cache for Homebrew Cellar path
|
||||
|
||||
### PATH Management Best Practices
|
||||
|
||||
- Always check `PHPENV_ORIGINAL_PATH` exists before modification
|
||||
- Use debouncing for automatic operations
|
||||
- Validate PHP paths before setting
|
||||
- Provide restoration mechanism (`phpenv use system`)
|
||||
- Clean up temporary variables in error cases
|
||||
|
||||
### Helper Functions
|
||||
|
||||
Use unified helper functions to avoid code duplication:
|
||||
|
||||
- `__phpenv_parse_version_field`: Single function for all jq parsing
|
||||
- `__phpenv_ensure_taps`: Unified Homebrew tap management
|
||||
- `__phpenv_get_tap_formulas`: Shared formula listing logic
|
||||
|
||||
## Submitting Changes
|
||||
|
||||
### Pull Request Process
|
||||
|
||||
1. **Create a branch** from `main`:
|
||||
|
||||
```bash
|
||||
git checkout -b feature/my-improvement
|
||||
```
|
||||
|
||||
2. **Make focused changes**:
|
||||
- Keep changes small and focused
|
||||
- Follow the existing code style
|
||||
- Add tests if applicable
|
||||
|
||||
3. **Run quality checks**:
|
||||
|
||||
```bash
|
||||
pre-commit run --all-files
|
||||
shellcheck functions/phpenv.fish
|
||||
```
|
||||
|
||||
4. **Test thoroughly**:
|
||||
- Test all affected functionality
|
||||
- Test edge cases
|
||||
- Test on different environments if possible
|
||||
|
||||
5. **Commit with clear messages**:
|
||||
|
||||
```bash
|
||||
git commit -m "feat: add new command for X functionality"
|
||||
```
|
||||
|
||||
6. **Submit pull request**:
|
||||
- Provide clear description of changes
|
||||
- Reference any related issues
|
||||
- Include testing instructions
|
||||
|
||||
### Commit Message Format
|
||||
|
||||
Follow conventional commits:
|
||||
|
||||
- `feat:` for new features
|
||||
- `fix:` for bug fixes
|
||||
- `docs:` for documentation changes
|
||||
- `perf:` for performance improvements
|
||||
- `refactor:` for code refactoring
|
||||
- `test:` for adding tests
|
||||
|
||||
### Code Review
|
||||
|
||||
All changes require code review. The maintainer will:
|
||||
|
||||
- Review for code quality and style
|
||||
- Test functionality
|
||||
- Check performance impact
|
||||
- Verify documentation updates
|
||||
|
||||
## Getting Help
|
||||
|
||||
- **Issues**: Open a GitHub issue for bugs or feature requests
|
||||
- **Discussions**: Use GitHub Discussions for questions
|
||||
- **Documentation**: Check the README and CLAUDE.md files
|
||||
|
||||
Thank you for contributing to phpenv.fish! 🐟
|
||||
Reference in New Issue
Block a user