Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
175 lines (128 loc) · 4.41 KB

CONTRIBUTING.md

File metadata and controls

175 lines (128 loc) · 4.41 KB

Contributing to Qt API Client

Thank you for considering contributing to Qt API Client! This document provides guidelines for contributing to the project.

Development Setup

  1. Fork the repository

  2. Clone your fork:

    git clone https://github.com/YOUR_USERNAME/qt-api-client.git
cd qt-api-client

  3. Install dependencies:

    pip install -r requirements.txt

  4. Run the demo to verify setup:

    python demo.py

Project Structure

qt-api-client/
├── src/
│   ├── core/          # Business logic (request handling, data management)
│   └── ui/            # PyQt5 UI components
├── examples/          # Example collection files
├── main.py           # Application entry point
└── demo.py           # Demo script for testing

Making Changes

Core Modules

Core modules are in src/core/ and handle business logic:

  • request_manager.py: HTTP request handling using the requests library
  • collection_manager.py: Collection storage and management
  • environment_manager.py: Environment variable handling and substitution
  • history_manager.py: Request/response history tracking
  • authentication.py: Authentication method implementations

When modifying core modules:

  • Keep business logic separate from UI code
  • Ensure data is properly serialized/deserialized for persistence
  • Add error handling for edge cases
  • Test functionality with the demo script

UI Components

UI components are in src/ui/ and are built with PyQt5:

  • main_window.py: Main application window and menu bar
  • request_panel.py: Request builder interface
  • response_panel.py: Response display interface
  • collection_panel.py: Collection tree browser
  • history_panel.py: History dialog
  • environment_dialog.py: Environment management dialog

When modifying UI components:

  • Follow Qt best practices and signals/slots pattern
  • Keep UI responsive (use threading for long operations if needed)
  • Maintain consistent styling
  • Test in both light and dark themes if possible

Code Style

  • Follow PEP 8 Python style guide
  • Use type hints where appropriate
  • Add docstrings to classes and functions
  • Keep functions focused and single-purpose
  • Use meaningful variable names

Testing

Before submitting a pull request:

  1. Test the demo script:

    python demo.py

  2. Test the GUI application:

    python main.py

  3. Verify your changes work with example collections:

    • Import examples from examples/ directory
    • Test request execution
    • Test environment variable substitution
    • Test authentication methods

Adding Features

New Authentication Method

  1. Add the method to AuthType enum in src/core/authentication.py
  2. Implement getter methods in Authentication class
  3. Add UI controls in src/ui/request_panel.py
  4. Update documentation

New Response Format

  1. Add formatting logic in src/ui/response_panel.py
  2. Consider adding a new tab if needed
  3. Update documentation

New Collection Features

  1. Update data model in src/core/collection_manager.py
  2. Update UI in src/ui/collection_panel.py
  3. Ensure backward compatibility with existing collections
  4. Update example collections if needed

Submitting Changes

  1. Create a new branch for your feature:

    git checkout -b feature/your-feature-name

  2. Make your changes and commit:

    git add .
git commit -m "Add your descriptive commit message"

  3. Push to your fork:

    git push origin feature/your-feature-name

  4. Open a Pull Request on GitHub

Pull Request Guidelines

  • Provide a clear description of the changes
  • Reference any related issues
  • Include screenshots for UI changes
  • Ensure code follows project style
  • Test thoroughly before submitting

Reporting Issues

When reporting bugs, please include:

  • Qt API Client version
  • Python version
  • Operating system
  • Steps to reproduce the issue
  • Expected vs actual behavior
  • Error messages or logs if applicable

Feature Requests

Feature requests are welcome! Please:

  • Check if the feature already exists or is planned
  • Provide a clear use case
  • Explain how it would benefit users
  • Consider implementation complexity

Questions?

Feel free to open an issue for questions or discussions.

License

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