Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
146 lines (99 loc) · 5.87 KB

CONTRIBUTING.md

File metadata and controls

146 lines (99 loc) · 5.87 KB

Contributing Guidelines

Thank you for your interest in contributing to the project! I welcome contributions from the community and am pleased that you are interested in helping me make this project better.

How Can I Contribute?

Reporting Bugs

Before creating bug reports, please check the issue tracker to avoid duplicates. When you create a bug report, include as many details as possible:

  • Use a clear and descriptive title
  • Describe the exact steps to reproduce the problem
  • Provide specific examples to demonstrate the steps
  • Describe the behavior you observed and what behavior you expected to see
  • Include screenshots if applicable
  • Include details about your configuration and environment

Suggesting Enhancements

If you have a suggestion for improving the project, we'd love to hear it. Please provide:

  • A clear and detailed explanation of the feature
  • The motivation behind the suggestion
  • Any potential alternatives you've considered
  • Examples of how this enhancement would be used

Pull Requests

  1. Fork the repository
  2. Create a new branch for your feature (git checkout -b feature/amazing-feature)
  3. Make your changes
  4. Run any tests and linting tools
  5. Commit your changes (git commit -m 'Add some amazing feature')
  6. Push to the branch (git push origin feature/amazing-feature)
  7. Open a Pull Request

Pull Request Guidelines

  • Follow the existing code style and conventions
  • Update documentation as needed
  • Add tests for new features
  • Keep commits focused and atomic
  • Write clear, descriptive commit messages
  • Reference any relevant issues

Development Setup

Prerequisites

Before getting started with pi-hole, ensure your runtime environment meets the following requirements:

  • Programming Language: TypeScript
  • Package Manager: Npm

Installation

Install pi-hole using one of the following methods:

Build from source:

  1. Clone the pi-hole repository:
❯ git clone https://github.com/homeassistant-extras/pi-hole-card
  1. Navigate to the project directory:
❯ cd pi-hole
  1. Install the project dependencies:

Using npm   

❯ npm install

Usage

Run parcel using the following command: Using npm   

❯ npm run watch

Or to do a single build

❯ npm run build

Documentation

  • Keep READMEs and other documentation up to date
  • Use clear, concise language
  • Include examples where appropriate
  • Document any new features or changes in behavior

Questions?

If you have any questions, please feel free to:

  • Open an issue with the question label
  • Contact me here on GitHub

Features

Feature Summary
Architecture
  • Modular development with a focus on isolation of modules.
  • Emphasis on building a suite of web components.
  • Centered around Home Assistant's architecture and integration.
🔩 Code Quality
  • Follows strict coding standards and adheres to modern JavaScript features.
  • Utilizes tools like Prettier for code formatting and organization.
  • Maintains a consistent coding style throughout the project.
📄 Documentation
  • Provides detailed documentation on the project's architecture, components, and usage.
  • Includes links to relevant GitHub pages and repositories.
  • Maintains a clear and concise writing style for easy understanding.
🔌 Integrations
  • Integrates with Home Assistant's custom card registry and Lit library for web component development.
  • Utilizes GitHub Actions workflows for automation and deployment.
  • Maintains compatibility with various browsers and environments.
🧩 Modularity
  • Emphasizes modular development to facilitate easy maintenance and updates.
  • Provides a clear separation of concerns between components and features.
  • Maintains a consistent structure throughout the project.
🧪 Testing
  • Utilizes Mocha, Chai, and Sinon for testing and debugging purposes.
  • Maintains comprehensive test suites for various components and features.
  • Ensures coverage of edge cases and scenarios.
⚡️ Performance
  • Optimizes project configuration for performance and compilation.
  • Utilizes TypeScript and Prettier for efficient code maintenance.
  • Maintains a focus on data integrity and accuracy.
🛡️ Security
  • Emphasizes security through the use of GitHub Actions workflows and authentication tokens.
  • Maintains compatibility with various browsers and environments.
  • Ensures secure communication between components and features.
📦 Dependencies
  • Maintains a clear dependency graph using package-lock.json and npm.
  • Utilizes tools like hacs.json for efficient package management.
  • Maintains compatibility with various browsers and environments.
🚀 Scalability
  • Emphasizes scalability through modular development and efficient testing.
  • Maintains a focus on data integrity and accuracy.
  • Ensures seamless integration with Home Assistant's architecture and integration.

Key Tools and Technologies:

  • TypeScript
  • Prettier
  • GitHub Actions
  • Lit library
  • Mocha
  • Chai

// todo - project structure

License

By contributing, you agree that your contributions will be licensed under the project's license.

Thank you for contributing!