From b868e1370697a7d44e0380ee4fe83c0229d0d6ec Mon Sep 17 00:00:00 2001 From: dronefreak Date: Sun, 18 Jan 2026 16:47:55 +0100 Subject: [PATCH] feat: Add GitHub governance files --- .github/CHANGELOG.md | 77 ++++++++++++++++ .github/CODE_OF_CONDUCT.md | 80 ++++++++++++++++ .github/CONTRIBUTING.md | 164 +++++++++++++++++++++++++++++++++ .github/GOVERNANCE.md | 87 +++++++++++++++++ README.md => .github/README.md | 0 .github/SECURITY.md | 73 +++++++++++++++ .github/SUPPORT.md | 84 +++++++++++++++++ .pre-commit-config.yaml | 2 +- 8 files changed, 566 insertions(+), 1 deletion(-) create mode 100644 .github/CHANGELOG.md create mode 100644 .github/CODE_OF_CONDUCT.md create mode 100644 .github/CONTRIBUTING.md create mode 100644 .github/GOVERNANCE.md rename README.md => .github/README.md (100%) create mode 100644 .github/SECURITY.md create mode 100644 .github/SUPPORT.md diff --git a/.github/CHANGELOG.md b/.github/CHANGELOG.md new file mode 100644 index 0000000..791522f --- /dev/null +++ b/.github/CHANGELOG.md @@ -0,0 +1,77 @@ +# Changelog + +All notable changes to this project will be documented in this file. + +The format is based on **Keep a Changelog**, +and this project adheres to **Semantic Versioning**. + +* Keep a Changelog: [https://keepachangelog.com/en/1.1.0/](https://keepachangelog.com/en/1.1.0/) +* Semantic Versioning: [https://semver.org/](https://semver.org/) + +--- + +## [Unreleased] + +### Added + +* Initial project structure +* Pre-commit hooks for linting, formatting, typing, and security +* Documentation and governance templates + +### Changed + +* N/A + +### Deprecated + +* N/A + +### Removed + +* N/A + +### Fixed + +* N/A + +### Security + +* N/A + +--- + +## [0.1.0] - YYYY-MM-DD + +### Added + +* Initial public release + +--- + +## Versioning Policy + +This project follows **Semantic Versioning**: + +* **MAJOR** version for incompatible API changes +* **MINOR** version for backward-compatible functionality +* **PATCH** version for backward-compatible bug fixes + +--- + +## How to Update This File + +* Update **[Unreleased]** as part of each PR +* Move entries to a new version section at release time +* Keep entries concise and user-focused +* Avoid low-level implementation details + +--- + +## Types of Changes + +* **Added** – New features +* **Changed** – Changes in existing functionality +* **Deprecated** – Soon-to-be removed features +* **Removed** – Removed features +* **Fixed** – Bug fixes +* **Security** – Vulnerability-related changes diff --git a/.github/CODE_OF_CONDUCT.md b/.github/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..1d6224e --- /dev/null +++ b/.github/CODE_OF_CONDUCT.md @@ -0,0 +1,80 @@ +# Code of Conduct + +## Our Pledge + +We as contributors and maintainers pledge to make participation in this project a respectful and harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation. + +--- + +## Our Standards + +Examples of behavior that contributes to a positive environment include: + +* Using welcoming and inclusive language +* Being respectful of differing viewpoints and experiences +* Accepting constructive criticism gracefully +* Focusing on what is best for the project and community +* Showing empathy towards other contributors + +Examples of unacceptable behavior include: + +* Harassment, discrimination, or derogatory comments +* Trolling, insulting or dismissive remarks +* Public or private harassment +* Publishing others’ private information without explicit permission +* Other conduct which could reasonably be considered inappropriate in a professional setting + +--- + +## Enforcement Responsibilities + +Project maintainers are responsible for clarifying standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior. + +Maintainers have the right and responsibility to remove, edit, or reject contributions that are not aligned with this Code of Conduct. + +--- + +## Scope + +This Code of Conduct applies within all project spaces, including: + +* GitHub issues and pull requests +* Discussions and code reviews +* Project documentation +* Community interactions related to this project + +--- + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project maintainers at: + +**** + +Since this is a template project, the contact email has been left as a dummy, please update this while using the template in your project. + +All complaints will be reviewed and investigated promptly and fairly. +Confidentiality will be respected where possible. + +--- + +## Enforcement Guidelines + +Maintainers will follow these principles when enforcing this Code of Conduct: + +1. **Correction** – A private or public warning +2. **Temporary Ban** – Temporary restriction from participation +3. **Permanent Ban** – Permanent removal from the project community + +The response will depend on the severity and context of the violation. + +--- + +## Attribution + +This Code of Conduct is adapted from the +[Contributor Covenant, version 2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct.html). + +--- + +By participating in this project, you agree to abide by this Code of Conduct. diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md new file mode 100644 index 0000000..e4fe6ed --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,164 @@ +# Contributing Guide + +Thank you for your interest in contributing to this project. +Contributions are welcome, but please read this document carefully before opening an issue or pull request. + +This project prioritizes **code quality, clarity, and long-term maintainability** over rapid feature growth. + +--- + +## Ways to Contribute + +You can contribute by: + +* Reporting bugs +* Proposing new features or improvements +* Improving documentation +* Submitting code changes +* Reviewing pull requests + +Before starting work, please check existing issues and pull requests to avoid duplication. + +--- + +## Development Setup + +### Prerequisites + +* Python 3.9 or newer +* `uv` (recommended) or `pip` +* `git` + +### Clone and Install + +```bash +git clone https://github.com/lfagotbouquet/template_python +cd template_python + +# Create a virtual environment +uv venv +source .venv/bin/activate + +# Install dependencies +uv pip install -r requirements.txt + +# Install the project in editable mode +uv pip install -e . + +# Install pre-commit hooks +pre-commit install +``` + +--- + +## Code Standards + +This project enforces strict automated checks. + +### Formatting and Linting + +* **Ruff** is used for linting and formatting +* Manual formatting is discouraged; rely on tooling instead + +Run locally: + +```bash +pre-commit run --all-files +``` + +### Typing + +* **Mypy** is used with a strict configuration +* **Bandit** is used to catch early security issues +* New code must include type annotations +* Public APIs must be fully typed + +### Tests + +* **Pytest** is used for testing +* New features and bug fixes must include tests +* Tests should be deterministic and fast + +Run tests with: + +```bash +python -m pytest tests/ +``` + +--- + +## Commit Messages + +This project follows **Conventional Commits**. Please read the docs here for more information [DOCS](https://www.conventionalcommits.org/en/v1.0.0/#specification) + +Examples: + +* `feat: add decrement CLI command` +* `fix: handle empty config file` +* `docs: update installation instructions` +* `refactor: simplify config loading logic` + +Pull requests with non-conforming commit messages will be rejected. + +--- + +## Pull Request Guidelines + +Before opening a pull request: + +* Ensure all pre-commit checks pass +* Ensure tests pass locally +* Keep changes focused and minimal +* Avoid unrelated refactors +* Update documentation where applicable +* Avoid making large PRs as and where possible + +Each pull request should: + +* Clearly state **what** is changed +* Clearly explain **why** the change is needed +* Reference relevant issues if applicable + +--- + +## Issue Reporting + +When reporting bugs, include: + +* A clear description of the problem +* Steps to reproduce +* Expected vs actual behavior +* Python version and environment details +* Relevant logs or stack traces + +Incomplete or vague issues may be closed without response. + +--- + +## Design Philosophy + +This project favors: + +* Explicit over implicit behavior +* Simple solutions over clever ones +* Readability over brevity +* Fewer dependencies over convenience + +Changes that significantly increase complexity or maintenance burden may be declined. + +--- + +## Code of Conduct + +All contributors are expected to follow the project’s +[Code of Conduct](CODE_OF_CONDUCT.md). + +--- + +## Questions + +If you are unsure whether a change is appropriate, open an issue **before** starting work. + +--- + +Thank you for contributing. diff --git a/.github/GOVERNANCE.md b/.github/GOVERNANCE.md new file mode 100644 index 0000000..ee84f75 --- /dev/null +++ b/.github/GOVERNANCE.md @@ -0,0 +1,87 @@ +# Project Governance + +This document describes how this project is governed and how decisions are made. + +--- + +## Maintainer Model + +This project follows a **maintainer-led governance model**. + +* One or more maintainers are responsible for the project +* Maintainers have final authority over technical and strategic decisions +* Contributions are welcome, but acceptance is at the discretion of the maintainers + +--- + +## Roles + +### Maintainers + +Maintainers: + +* Define the project vision and roadmap +* Review and merge pull requests +* Manage releases +* Enforce code quality, security, and contribution standards +* Moderate community interactions + +### Contributors + +Contributors: + +* Submit issues, pull requests, and documentation improvements +* Participate in discussions and reviews +* Follow the Code of Conduct and contribution guidelines + +Contributors do not have decision-making authority unless explicitly granted. + +--- + +## Decision Making + +Decisions are made using the following principles: + +1. **Technical merit over popularity** +2. **Long-term maintainability over short-term convenience** +3. **Clarity over cleverness** +4. **Backward compatibility when reasonable** + +For significant changes: + +* Discussion happens in a GitHub issue or pull request +* Maintainers consider community feedback +* Final decisions rest with the maintainers + +--- + +## Changes to Governance + +This governance model may evolve as the project grows. + +Any changes to this document must be approved by the maintainers and documented via a pull request. + +--- + +## Scope + +This governance applies to: + +* Source code +* Documentation +* Issue discussions +* Pull requests +* Project-related communication channels + +--- + +## Acknowledgement + +By contributing to this project, you agree to follow this governance model along with the: + +* [Code of Conduct](CODE_OF_CONDUCT.md) +* [Contributing Guidelines](CONTRIBUTING.md) + +--- + +This project aims to remain open, focused, and sustainable. diff --git a/README.md b/.github/README.md similarity index 100% rename from README.md rename to .github/README.md diff --git a/.github/SECURITY.md b/.github/SECURITY.md new file mode 100644 index 0000000..c6c4007 --- /dev/null +++ b/.github/SECURITY.md @@ -0,0 +1,73 @@ +# Security Policy + +## Supported Versions + +Security updates are provided on a best-effort basis. + +In general: + +* The **latest released version** is supported +* Older versions may not receive security fixes + +Users are encouraged to stay up to date. + +--- + +## Reporting a Vulnerability + +If you discover a security vulnerability, **do not open a public issue**. + +Instead, please report it privately using one of the following methods: + +* Email: **** +* GitHub Security Advisories (preferred, if enabled) + +*Since this is a template project, the contact email has been left as a dummy, please update this while using the template in your project.* + +Please include: + +* A clear description of the vulnerability +* Steps to reproduce the issue +* Potential impact +* Any suggested mitigation or fix + +--- + +## Responsible Disclosure + +We ask that you follow responsible disclosure practices: + +* Do not publicly disclose the issue until it has been reviewed +* Allow maintainers reasonable time to investigate and respond +* Avoid exploiting the vulnerability beyond proof-of-concept + +We aim to acknowledge reports promptly and will work with you on disclosure timing where appropriate. + +--- + +## Automated Security Checks + +This project uses automated tooling to detect common security issues, including: + +* Static analysis (e.g. Bandit) +* Dependency scanning (where applicable) + +These tools are helpful but **not a guarantee** of security. + +--- + +## Scope + +This security policy applies to: + +* Source code under `src/`, `apps/`, and related modules +* Distributed artifacts produced from this repository + +It does **not** apply to: + +* Third-party dependencies +* Downstream projects using this code + +--- + +Thank you for helping keep this project and its users safe. diff --git a/.github/SUPPORT.md b/.github/SUPPORT.md new file mode 100644 index 0000000..857b128 --- /dev/null +++ b/.github/SUPPORT.md @@ -0,0 +1,84 @@ +# Support + +This document explains how to get help with this project. + +Please read this carefully before opening an issue. + +--- + +## Getting Help + +The preferred way to get support is through **GitHub Issues**. + +Before opening a new issue: + +1. Check the existing issues (open and closed) +2. Read the README and documentation +3. Make sure you are using a supported Python version +4. Ensure all dependencies are up to date + +If your question is answered in the documentation, the issue may be closed without response. + +--- + +## Bug Reports + +Use GitHub Issues to report bugs. + +A good bug report includes: + +* Clear description of the problem +* Steps to reproduce +* Expected vs actual behavior +* Python version and operating system +* Relevant logs or stack traces + +Incomplete reports slow things down and may be closed. + +--- + +## Feature Requests + +Feature requests are welcome, but not all will be accepted. + +When proposing a feature: + +* Explain the problem you are trying to solve +* Describe why existing functionality is insufficient +* Consider the impact on complexity and maintenance + +Features that significantly increase scope or maintenance burden may be declined. + +--- + +## What This Project Does NOT Provide + +Please note that this project does **not** offer: + +* One-on-one support +* Guaranteed response times +* Help with unrelated tooling or environments +* Debugging of downstream projects + +For general Python questions, consider forums like Stack Overflow or Reddit (or just use online AI platforms). + +--- + +## Security Issues + +Do **not** report security vulnerabilities here. + +See [SECURITY.md](SECURITY.md) for responsible disclosure instructions. + +--- + +## Maintainer Availability + +This project is maintained on a best-effort basis. + +Responses may take time, especially for non-critical issues. +Polite, well-prepared questions are more likely to receive help. + +--- + +Thank you for respecting the maintainers’ time and contributing responsibly. diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 21377c5..8b071b9 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -119,7 +119,7 @@ repos: rev: v0.38.0 hooks: - id: markdownlint-fix - args: [--disable, MD013, MD033, MD041, --] + args: [--disable, MD013, MD033, MD041, MD024, --] - repo: https://github.com/adrienverge/yamllint rev: v1.38.0