Harden CI quality gates and add OSS governance docs

Author: FraLotito

.github/workflows/tests.yml

@@ -11,7 +11,42 @@ permissions:
   contents: read
 
 jobs:
+  quality:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set Up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Upgrade pip
+        run: python -m pip install --upgrade pip
+
+      - name: Install
+        run: python -m pip install -e ".[dev]"
+
+      - name: Formatting (Black)
+        run: black --check .
+
+      - name: Lint (Ruff)
+        run: ruff check .
+
+      - name: Type Check (Mypy)
+        run: mypy
+
+      - name: Build Package
+        run: python -m build
+
+      - name: Validate Package Metadata
+        run: twine check dist/*
+
   pytest:
+    needs: quality
     runs-on: ubuntu-latest
     strategy:
       fail-fast: false

.pre-commit-config.yaml

@@ -1,4 +1,9 @@
 repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.9.10
+    hooks:
+      - id: ruff
+      - id: ruff-format
   - repo: https://github.com/psf/black
     rev: 24.3.0
     hooks:

CODE_OF_CONDUCT.md

@@ -0,0 +1,44 @@
+# Code of Conduct
+
+## Our Pledge
+
+We as contributors and maintainers pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment include:
+
+- Demonstrating empathy and kindness toward other people.
+- Being respectful of differing opinions, viewpoints, and experiences.
+- Giving and gracefully accepting constructive feedback.
+- Taking responsibility and apologizing to those affected by our mistakes.
+- Focusing on what is best for the overall community.
+
+Examples of unacceptable behavior include:
+
+- The use of sexualized language or imagery, and sexual attention or advances of any kind.
+- Trolling, insulting or derogatory comments, and personal or political attacks.
+- Public or private harassment.
+- Publishing others' private information, such as a physical or email address, without their explicit permission.
+- Other conduct which could reasonably be considered inappropriate in a professional setting.
+
+## Enforcement Responsibilities
+
+Project maintainers are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior they deem inappropriate, threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies within all project spaces, and also applies when an individual is officially representing the project in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the maintainers at lotitoqf@gmail.com. All complaints will be reviewed and investigated promptly and fairly.
+
+All maintainers are obligated to respect the privacy and security of the reporter of any incident.
+
+## 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

CONTRIBUTING.md

@@ -1,107 +1,68 @@
-# Contributing to Hypergraphx on GitHub
+# Contributing to Hypergraphx
 
-Follow this step-by-step guide to contribute to Hypergraphx.
+Thanks for contributing to Hypergraphx.
 
-## 1. Set Up Your GitHub Account
+## Development Setup
 
-If you haven't already, create a GitHub account at [GitHub.com](https://github.com/).
-
-## 2. Fork the Repository
-
-- Go to the main page of the Hypergraphx repository.
-- In the top-right corner of the page, click on the "Fork" button. This will create a copy of the repository in your
-  GitHub account.
-
-## 3. Clone Your Forked Repository
-
-- Navigate to your forked repository in your GitHub account.
-- Click the "Code" button and copy the URL.
-- Open your terminal and navigate to the directory where you want to clone the repository.
-- Run the following command:
-
-```bash
-git clone [URL]
-```
-
-Replace `[URL]` with the URL you copied.
-
-## 4. Set Upstream Remote
-
-To keep your forked repository updated with the changes from the original repository, you need to set an upstream
-remote:
-
-- Navigate to the directory of your cloned repository in the terminal.
-- Run the following command:
+1. Fork the repository and clone your fork.
+2. Create and activate a virtual environment.
+3. Install the package in editable mode with development dependencies:
 
 ```bash
-git remote add upstream https://github.com/HGX-Team/hypergraphx.git
-```
-
-## 5. Create a New Branch
-
-Before making any changes, it's a good practice to create a new branch:
-
-- Navigate to the directory of your cloned repository in the terminal.
-- Run the following command to create and switch to a new branch:
-
-```bash
-git checkout -b your-branch-name
+python -m pip install --upgrade pip
+python -m pip install -e ".[dev,viz,temporal]"
+pre-commit install
 ```
 
-## 6. Make Your Changes
+## Local Quality Checks
 
-- Edit the files or add new files as required.
-- Once you've made your changes, save them.
-- Format Python code with Black before committing:
+Run these before opening a pull request:
 
 ```bash
-black .
+black --check .
+ruff check .
+mypy
+pytest
+python -m build
+twine check dist/*
 ```
 
-- (Recommended) Install pre-commit so formatting happens automatically:
+If you want to run pre-commit hooks across the repository:
 
 ```bash
-pre-commit install
+pre-commit run --all-files
 ```
 
-## 7. Commit Your Changes
+## Documentation
 
-- In the terminal, navigate to the directory of your cloned repository.
-- Run the following commands to add and commit your changes:
+Build docs locally when your change affects docs, APIs, or tutorials:
 
 ```bash
-git add .
-git commit -m "Your commit message here"
+python -m pip install -e ".[docs]"
+make -C docs html
 ```
 
-## 8. Push Your Changes to GitHub
-
-- Push your changes to your forked repository on GitHub:
-
-```bash
-git push origin your-branch-name
-```
+## Branch and Commit Guidelines
 
-## 9. Create a Pull Request (PR)
+- Create a focused branch from `main`.
+- Keep pull requests small and scoped to one change.
+- Write clear commit messages in imperative mood (for example: `Add temporal centrality regression test`).
+- Add or update tests for behavioral changes.
+- Update docs when user-facing behavior changes.
 
-- Go to your forked repository on GitHub.
-- Click on the "Pull requests" tab and then click on the "New pull request" button.
-- Ensure the base repository is the original Hypergraphx repository and the base branch is the branch you want to merge
-  your changes into (usually `main`).
-- Ensure the head repository is your forked repository and the compare branch is the branch you made your changes in.
-- Click on the "Create pull request" button.
-- Fill in the PR title and description, explaining your changes.
-- Click on the "Create pull request" button to submit your PR.
+## Pull Request Checklist
 
-## 10. Wait for Review
+- Tests added/updated for new behavior.
+- Local quality checks pass.
+- Docs updated (if relevant).
+- PR description explains motivation, approach, and impact.
 
-- The maintainers of the Hypergraphx repository will review your PR.
-- They might request some changes or improvements. If so, make the required changes in your branch, commit them, and
-  push them to GitHub. Your PR will be automatically updated.
+## Reporting Bugs and Requesting Features
 
-## 11. PR Gets Merged
+- Use GitHub Issues for bugs and feature requests.
+- Include a minimal reproducible example for bugs.
+- For security issues, do not open a public issue. See `SECURITY.md`.
 
-Once your PR is approved, the maintainers will merge it into the main branch of the Hypergraphx repository.
+## Code of Conduct
 
-**Note:** Always follow the contribution guidelines provided by the repository maintainers, and always be respectful and
-constructive in your interactions.
+By participating in this project, you agree to follow the Code of Conduct in `CODE_OF_CONDUCT.md`.

SECURITY.md

@@ -0,0 +1,22 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability in Hypergraphx, please report it privately by email to:
+
+- lotitoqf@gmail.com
+
+Please do not open a public GitHub issue for security vulnerabilities.
+
+When reporting, include:
+
+- A clear description of the issue and affected component(s).
+- Reproduction steps or a proof of concept.
+- Potential impact.
+- Any suggested mitigation.
+
+We will acknowledge receipt as soon as possible and work with you to validate and remediate the issue.
+
+## Supported Versions
+
+Security fixes are generally applied to the latest release on PyPI and the `main` branch.

pyproject.toml

@@ -25,6 +25,7 @@ dependencies = [
   "scipy",
   "networkx",
   "pandas",
+  "tqdm",
 ]
 dynamic = ["version"]
 
@@ -35,11 +36,12 @@ Homepage = "https://github.com/HGX-Team/hypergraphx"
 dev = [
   "pytest",
   "black>=24.3.0",
+  "ruff>=0.6.0",
+  "mypy>=1.10.0",
+  "build>=1.2.1",
+  "twine>=5.1.1",
   "pre-commit",
 ]
-temporal = [
-  "tqdm",
-]
 viz = [
   "matplotlib",
   # optional interactive hover labels in plot_motifs
@@ -71,3 +73,16 @@ local_scheme = "dirty-tag"
 [tool.black]
 line-length = 88
 target-version = ["py310"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E9", "F63", "F7", "F82"]
+
+[tool.mypy]
+python_version = "3.10"
+ignore_missing_imports = true
+warn_unused_configs = true
+files = ["hypergraphx"]