Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
197 lines (155 loc) · 4.86 KB

CONTRIBUTING.md

File metadata and controls

197 lines (155 loc) · 4.86 KB

Contributing to System Website Blocker

Thank you for your interest in contributing to the System Website Blocker project! This document provides guidelines and information for contributors.

🚀 Getting Started

Prerequisites

  • macOS 10.12 or later
  • Python 3.6 or later
  • Administrator privileges (for testing)
  • Git

Development Setup

  1. Fork the repository
  2. Clone your fork: 
    git clone https://github.com/YOUR_USERNAME/system-website-blocker.git
cd system-website-blocker
  3. Install dependencies: 
    pip3 install -r requirements.txt
  4. Test the installation: 
    python3 test_blocker.py

🛠️ Development Guidelines

Code Style

  • Follow PEP 8 for Python code
  • Use meaningful variable and function names
  • Add comments for complex logic
  • Keep functions focused and small

Testing

  • Test all changes thoroughly
  • Run the test script before submitting
  • Test with different macOS versions if possible
  • Verify both GUI and console versions work

Security Considerations

  • This application modifies system files
  • Always backup before testing
  • Test in a safe environment
  • Document any security implications

📝 How to Contribute

Reporting Issues

  1. Check existing issues first
  2. Use the issue template
  3. Include system information:
    • macOS version
    • Python version
    • Error messages
    • Steps to reproduce

Suggesting Features

  1. Check existing feature requests
  2. Describe the use case
  3. Explain the benefits
  4. Consider implementation complexity

Submitting Code

  1. Create a feature branch: 
    git checkout -b feature/your-feature-name
  2. Make your changes
  3. Test thoroughly
  4. Commit with clear messages
  5. Push to your fork
  6. Create a pull request

🔧 Project Structure

system-website-blocker/
├── website_blocker.py      # Basic GUI version
├── advanced_blocker.py     # Advanced version with web interface
├── console_blocker.py      # Command-line version
├── launcher.py            # Application launcher
├── test_blocker.py        # Testing script
├── install.sh             # Installation script
├── uninstall.sh           # Uninstallation script
├── requirements.txt       # Python dependencies
├── README.md              # Main documentation
├── QUICK_START.md         # Quick start guide
├── CONTRIBUTING.md        # This file
├── LICENSE                # MIT License
└── .gitignore            # Git ignore rules

🧪 Testing

Manual Testing

  1. Test basic blocking functionality
  2. Test advanced features (scheduling, monitoring)
  3. Test console version
  4. Test installation/uninstallation
  5. Test on different macOS versions

Automated Testing

Run the test script:

python3 test_blocker.py

📋 Pull Request Process

  1. Fork and Clone: Fork the repository and clone your fork
  2. Create Branch: Create a feature branch from main
  3. Make Changes: Implement your changes with tests
  4. Test: Run all tests and verify functionality
  5. Commit: Make clear, descriptive commits
  6. Push: Push your branch to your fork
  7. Pull Request: Create a PR with a clear description

Pull Request Template

## Description
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Documentation update
- [ ] Code refactoring

## Testing
- [ ] Tested on macOS [version]
- [ ] All tests pass
- [ ] Manual testing completed

## Screenshots (if applicable)
Add screenshots for GUI changes

## Additional Notes
Any additional information

🐛 Bug Reports

When reporting bugs, please include:

  1. System Information:

    • macOS version
    • Python version
    • Hardware (Intel/Apple Silicon)

  2. Error Details:

    • Full error message
    • Steps to reproduce
    • Expected vs actual behavior

  3. Logs:

    • Console output
    • System logs (if relevant)

💡 Feature Requests

When suggesting features:

  1. Use Case: Describe the problem you're trying to solve
  2. Proposed Solution: How should it work?
  3. Alternatives: Other ways to solve the problem
  4. Implementation: Any ideas on how to implement it

📚 Documentation

  • Update README.md for major changes
  • Add docstrings to new functions
  • Update comments for complex code
  • Include examples for new features

🔒 Security

  • Never commit sensitive information
  • Test security implications of changes
  • Follow secure coding practices
  • Report security issues privately

📞 Getting Help

  • Check existing issues and discussions
  • Join the GitHub discussions
  • Contact the maintainer: Suraj Van Verma

📄 License

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

Thank you for contributing to make system-level website blocking better for everyone! 🚀