Skip to content

Latest commit

 

History

History
263 lines (214 loc) · 6.5 KB

CONTRIBUTING.md

File metadata and controls

263 lines (214 loc) · 6.5 KB

Contributing to Project Structure Viewer

Thank you for your interest in contributing to Project Structure Viewer! This document provides guidelines and information for contributors.

🤝 How to Contribute

Reporting Bugs

  1. Check if the bug has already been reported in Issues
  2. If not, create a new issue using the bug report template
  3. Provide as much detail as possible including:
    • PHP version
    • Operating system
    • Web server details
    • Steps to reproduce
    • Expected vs actual behavior

Suggesting Features

  1. Check existing Issues and task_pending.md
  2. Create a new issue using the feature request template
  3. Describe the use case and potential implementation

Code Contributions

Prerequisites

  • PHP 8.0 or higher
  • Composer
  • Git
  • Basic understanding of PHP OOP and PSR standards

Development Setup

  1. Fork the repository
  2. Clone your fork: 
    git clone https://github.com/your-username/project-structure-viewer.git
cd project-structure-viewer
  3. Install dependencies: 
    composer install
  4. Create a new branch: 
    git checkout -b feature/your-feature-name

Coding Standards

  • Follow PSR-12 coding standards
  • Use PHP 8.0+ type declarations
  • Write comprehensive PHPDoc comments
  • Maintain backward compatibility
  • Keep security in mind

Code Style Guidelines

<?php

namespace ProjectStructureViewer\Example;

/**
 * Example class demonstrating coding standards
 */
class ExampleClass
{
    private string $property;

    /**
     * Constructor with type declarations
     */
    public function __construct(string $property)
    {
        $this->property = $property;
    }

    /**
     * Method with proper documentation
     * 
     * @param string $input Input parameter
     * @return string Processed output
     */
    public function processData(string $input): string
    {
        // Clear, descriptive variable names
        $processedData = $this->sanitizeInput($input);
        
        return $processedData;
    }

    /**
     * Private helper method
     */
    private function sanitizeInput(string $input): string
    {
        return htmlspecialchars($input, ENT_QUOTES, 'UTF-8');
    }
}

Testing

  • Write unit tests for new features
  • Ensure all existing tests pass
  • Test on multiple PHP versions (8.0, 8.1, 8.2+)
  • Test web interface functionality

Pull Request Process

  1. Update documentation if needed
  2. Add tests for new functionality
  3. Ensure all tests pass
  4. Update CHANGELOG.md if applicable
  5. Create a pull request with:
    • Clear title and description
    • Reference to related issues
    • Screenshots if UI changes
    • Testing details

📁 Project Structure

project-structure-viewer/
├── src/                          # Main source code
│   ├── ProjectStructureViewer.php # Main class
│   ├── Utils/                    # Utility classes
│   └── Renderers/               # Output renderers
├── public/                      # Web interface
├── install/                     # Installation scripts
├── tests/                       # Unit tests (future)
├── .github/                     # GitHub templates
└── docs/                        # Documentation

🎯 Areas for Contribution

High Priority

  • Unit testing implementation
  • Performance optimizations
  • Configuration system
  • Bug fixes

Medium Priority

  • Theme system
  • Search and filter features
  • Export functionality
  • Mobile improvements

Low Priority

  • Internationalization
  • Plugin system
  • Advanced analytics
  • Framework integrations

See task_pending.md for detailed task list.

🔧 Development Guidelines

Security Considerations

  • Validate all user inputs
  • Sanitize file paths
  • Prevent directory traversal attacks
  • Handle errors gracefully
  • Don't expose sensitive information

Performance Guidelines

  • Optimize for large directory structures
  • Use efficient algorithms
  • Minimize memory usage
  • Consider caching strategies

Documentation

  • Update README.md for new features
  • Add inline code comments
  • Update API documentation
  • Include usage examples

🧪 Testing Guidelines

Unit Tests

<?php

namespace ProjectStructureViewer\Tests;

use PHPUnit\Framework\TestCase;
use ProjectStructureViewer\ProjectStructureViewer;

class ProjectStructureViewerTest extends TestCase
{
    public function testBasicFunctionality(): void
    {
        $viewer = ProjectStructureViewer::create();
        $this->assertInstanceOf(ProjectStructureViewer::class, $viewer);
    }
}

Integration Tests

  • Test web interface
  • Test different PHP versions
  • Test various directory structures
  • Test gitignore functionality

📋 Code Review Process

What We Look For

  • Code quality and readability
  • Security considerations
  • Performance implications
  • Test coverage
  • Documentation updates
  • Backward compatibility

Review Criteria

  • ✅ Follows coding standards
  • ✅ Includes appropriate tests
  • ✅ Documentation is updated
  • ✅ No security vulnerabilities
  • ✅ Performance is acceptable
  • ✅ Backward compatible

🚀 Release Process

Version Numbering

We follow Semantic Versioning:

  • MAJOR: Breaking changes
  • MINOR: New features (backward compatible)
  • PATCH: Bug fixes (backward compatible)

Release Checklist

  • All tests pass
  • Documentation updated
  • CHANGELOG.md updated
  • Version bumped in composer.json
  • Tag created
  • Packagist updated

🤔 Questions?

📜 Code of Conduct

Our Pledge

We are committed to making participation in this project a harassment-free experience for everyone.

Our Standards

  • Use welcoming and inclusive language
  • Be respectful of differing viewpoints
  • Accept constructive criticism gracefully
  • Focus on what is best for the community
  • Show empathy towards other community members

Enforcement

Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to icarosnet@gmail.com.

🎉 Recognition

Contributors will be recognized in:

  • README.md contributors section
  • Release notes
  • Special thanks in major releases

Thank you for contributing to Project Structure Viewer! 🚀