Add maintainers-guidelines.md (#1)

.gitignore

@@ -1,3 +1,4 @@
 __pycache__/
+cache/
 output/
 venv/

.pre-commit-config.yaml

@@ -1,4 +1,4 @@
-# pre-commit run --all-files
+# To execute those rules on all files: pre-commit run --all-files
 repos:
 -   repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v4.4.0
@@ -10,35 +10,8 @@ repos:
     -   id: check-yaml
     -   id: debug-statements
     -   id: end-of-file-fixer
-        exclude: "resources/.*|docs/make.bat"
     -   id: trailing-whitespace
     -   id: mixed-line-ending
         args: ['--fix=lf']
-        exclude: "docs/make.bat"
     -   id: check-added-large-files
         args: ['--maxkb=1000']
-# -   repo: https://github.com/pre-commit/mirrors-mypy
-#     rev: v0.942
-#     hooks:
-#     -   id: mypy
--   repo: https://github.com/psf/black
-    rev: 23.1.0
-    hooks:
-    -   id: black
-        args: [--target-version, py36]
--   repo: https://github.com/asottile/blacken-docs
-    rev: 1.13.0
-    hooks:
-    -   id: blacken-docs
-        additional_dependencies: [black==22.1.0]
-        exclude: "docs/user/robustness.md"
--   repo: https://github.com/charliermarsh/ruff-pre-commit
-    rev: 'v0.0.259'
-    hooks:
-    -   id: ruff
-        args: ['--fix']
--   repo: https://github.com/asottile/pyupgrade
-    rev: v3.3.1
-    hooks:
-    -   id: pyupgrade
-        args: [--py39-plus]

README.md

@@ -2,14 +2,21 @@
 Website py-pdf
 
 ## Install requirements
-
 ```
 $ pip install -r requirements.txt
 $ pre-commit install
 ```
 
-## Publish
+## Launch local server with livereload
+```
+$ invoke livereload
+```
+
+## Adding a Python dependency
+1. Edit `requirements.in`
+2. Run `pip-compile requirements.in` to generate `requirements.txt`
 
+## Publish
 ```
 $ make github
 ```

content/pages/index.md

@@ -0,0 +1,10 @@
+Title: The py-pdf organization
+Slug: ../index
+Save_as: index.html
+Authors: Martin Thoma
+Summary: What py-pdf is about
+
+The py-pdf organization is a group of Python developers who provide
+libraries and applications around PDF documents.
+
+<center>![pypdf logo](images/pypdf-snake.png)</center>

content/pages/maintainer-guidelines.md

@@ -0,0 +1,97 @@
+Title: Maintainer guidelines
+Tags: guideline, maintainer
+
+## Table of contents
+<!-- To update this ToC based on the sections below : markdown-toc -i content/pages/maintainer-guidelines.md -->
+
+<!-- toc -->
+
+- [Volunteering](#volunteering)
+- [Governance](#governance)
+  * [The relationship of py-pdf to its projects](#the-relationship-of-py-pdf-to-its-projects)
+  * [Conditions for projects to be added to py-pdf](#conditions-for-projects-to-be-added-to-py-pdf)
+  * [Responsibility of project maintainers](#responsibility-of-project-maintainers)
+  * [GitHub roles](#github-roles)
+- [Releases](#releases)
+
+<!-- tocstop -->
+
+## Volunteering
+All [@py-pdf](https://github.com/py-pdf) members are volunteers.
+They dedicate some of their time to maintain open-source projects, answer questions and review Pull Requests.
+
+[@py-pdf](https://github.com/py-pdf) members should never be required to operate within deadlines, or even respond within a given time frame.
+
+If you are a user of a [@py-pdf](https://github.com/py-pdf) project and want something done,
+whether it is a bugfix or a feature request, your best options for achieving what you want are:
+
+* being polite and patient
+* volunteer to contribute yourself
+
+To all [@py-pdf](https://github.com/py-pdf) members, remember: [it's okay to hit pause](https://opensource.guide/best-practices/#its-okay-to-hit-pause), and take time away from volunteer open-source work.
+
+<br>
+
+## Governance
+`py-pdf` governance model is descibed there:
+<https://pypdf.readthedocs.io/en/latest/meta/project-governance.html>
+
+<br>
+
+## The relationship of py-pdf to its projects
+
+`py-pdf` wants to ensure the Python-PDF ecosystem is prospering. We recognize that individual
+maintainers did and still do an outstanding job, but we also see that personal lives sometimes
+move away from software projects.
+
+That means:
+
+1. `py-pdf` offers the platform to exchange ideas and provide feedback
+2. `py-pdf` administrators who are not project members do interfere, when (a) no activity by the maintainers is in the project for at least 6 months and at least 3 friendly "are you alive" questions over at least 6 weeks. (b) security issues are detected
+3. `py-pdf` leaves the projects do their thing in all other cases.
+
+<br>
+
+## Conditions for projects to be added to py-pdf
+
+We want projects which provide value to users and we need to be able to maintain them. We want to improve the Python / PDF ecosystem and not scatter it.
+
+1. The project has to be a Python project and about PDF documents
+2. If it's a software project, it has (1) a README with the projects purpose, installation instructions, and a usage example (2) it's either the main project or the fork that has more popularity measured in GitHub stars
+3. It either has a different purpose than all other projects in `py-pdf` or is more popular than the existing projects for that purpose
+4. It needs to be a FOSS license (e.g. BSD, MIT, Apache)
+
+<br>
+
+## Responsibility of project maintainers
+
+1. **Software Reliability**: Please ensure that your project follows best practices in software development. Introduce a [deprecation process](https://pypdf.readthedocs.io/en/latest/dev/deprecations.html) and follow it.
+2. **Kindness**: We are all here because it's fun to help others and create good software. But we are humans: people can have bad days and people might not speak English as a mother tongue. When in doubt, assume the best. Let people know how you perceived their interaction.
+3. **Know your Limits**: It's ok to reduce the time you spend on your project or even step away from it. Stay healthy.
+4. **Let your Project Grow**: Especially if you step away, let others take over. Make it explicit that you're looking for another person who would take over.
+It's OK to [say no](https://opensource.guide/best-practices/#learning-to-say-no).
+
+<!--
+As recommended [by the opensource.guide](https://opensource.guide/leadership-and-governance/), a `GOVERNANCE.md` file in every repository could point to this page as reference.
+-->
+
+<br>
+
+## GitHub roles
+The base permission for [@py-pdf](https://github.com/py-pdf) members is set to **Write**,
+meaning any [@py-pdf](https://github.com/py-pdf) member has read permissions,
+can manage issues and pull requests, and also push to repositories.
+
+We encourage [@py-pdf](https://github.com/py-pdf) members, and especially maintainers, to make their organization membership **public**
+on <https://github.com/orgs/py-pdf/people>, in order to clarify who has ownership of the organization, and the associated rights to perform package releases:
+
+![](../images/github-org-public-membership.png)
+
+<br>
+
+## Releases
+Depending on the projects, the release process can be automated inside GitHub Actions pipelines, or stays manual.
+
+<!-- TODO: use a dedicated Pypi user like Jazzband does? cf. https://jazzband.co/about/releases -->
+
+<!-- TODO: add a section on Security & reporting vulnerabilities ? cf. https://jazzband.co/about/security -->

content/py-pdf-owners.md → content/pages/py-pdf-owners.md

@@ -1,7 +1,6 @@
 Title: Rules for py-pdf owners
 Date: 2023-04-18 17:10
 Modified: 2023-04-18 17:10
-Category: py-pdf
 Tags: Governance
 Slug: py-pdf-owners
 Authors: Martin Thoma

pelicanconf.py

@@ -1,19 +1,21 @@
+import logging
+
+logging.root.setLevel(logging.INFO)
+logging.getLogger('pelican.utils').setLevel(logging.WARN)  # avoids verbose "-> Copying ..." logs
+logging.getLogger('tornado.access').setLevel(logging.WARN)  # avoids verbose HTTP logs from livereload server
+# Configure LOG_FORMAT to prefix it with "%(asctime)s [%(module)s]":
+if logging.root.handlers:  # handlers are only set the 2nd time this file is evaluated by Pelican
+    formatter = logging.root.handlers[0].formatter
+    formatter._fmt = formatter._style._fmt = "%(asctime)s [%(name)s] %(levelname)s %(message)s"
+
 AUTHOR = "The py-pdf owners"
 SITENAME = "The py-pdf organization"
-SITEURL = ""
-
-PATH = "content"
 
 TIMEZONE = "Europe/Berlin"
-
 DEFAULT_LANG = "en"
 
-# Feed generation is usually not desired when developing
-FEED_ALL_ATOM = None
-CATEGORY_FEED_ATOM = None
-TRANSLATION_FEED_ATOM = None
-AUTHOR_FEED_ATOM = None
-AUTHOR_FEED_RSS = None
+PATH = './content'
+OUTPUT_PATH = './output'
 
 # Blogroll
 LINKS = (
@@ -32,5 +34,17 @@
 
 DEFAULT_PAGINATION = 10
 
+
+#######################################
+# Config options specific to dev-mode:
+#######################################
+
 # Uncomment following line if you want document-relative URLs when developing
 # RELATIVE_URLS = True
+
+# Feed generation is usually not desired when developing
+FEED_ALL_ATOM = None
+CATEGORY_FEED_ATOM = None
+TRANSLATION_FEED_ATOM = None
+AUTHOR_FEED_ATOM = None
+AUTHOR_FEED_RSS = None

requirements.in

@@ -1,7 +1,9 @@
-pip-tools  # brings pip-compile to update the requirements.txt
 ghp-import  # publish blog on https://py-pdf.github.io/
+pip-tools  # brings pip-compile to update the requirements.txt
 pre-commit  # automatically apply style checks/autofixes
 
 # For the blog:
-pelican
+invoke
+livereload
 markdown
+pelican

requirements.txt

@@ -1,10 +1,10 @@
 #
-# This file is autogenerated by pip-compile with Python 3.11
+# This file is autogenerated by pip-compile with Python 3.8
 # by the following command:
 #
 #    pip-compile requirements.in
 #
-blinker==1.5
+blinker==1.6
     # via pelican
 build==0.10.0
     # via pip-tools
@@ -24,8 +24,14 @@ ghp-import==2.1.0
     # via -r requirements.in
 identify==2.5.22
     # via pre-commit
+importlib-metadata==6.1.0
+    # via markdown
+invoke==2.0.0
+    # via -r requirements.in
 jinja2==3.1.2
     # via pelican
+livereload==2.6.3
+    # via -r requirements.in
 markdown==3.4.3
     # via -r requirements.in
 markdown-it-py==2.2.0
@@ -56,7 +62,7 @@ python-dateutil==2.8.2
     # via
     #   ghp-import
     #   pelican
-pytz==2023.2
+pytz==2023.3
     # via
     #   feedgenerator
     #   pelican
@@ -65,13 +71,27 @@ pyyaml==6.0
 rich==13.3.3
     # via pelican
 six==1.16.0
-    # via python-dateutil
+    # via
+    #   livereload
+    #   python-dateutil
+tomli==2.0.1
+    # via
+    #   build
+    #   pyproject-hooks
+tornado==6.2
+    # via livereload
+typing-extensions==4.5.0
+    # via
+    #   blinker
+    #   rich
 unidecode==1.3.6
     # via pelican
 virtualenv==20.21.0
     # via pre-commit
 wheel==0.40.0
     # via pip-tools
+zipp==3.15.0
+    # via importlib-metadata
 
 # The following packages are considered to be unsafe in a requirements file:
 # pip

tasks.py

@@ -6,6 +6,7 @@
 
 from invoke import task
 from invoke.main import program
+from livereload import Server
 from pelican import main as pelican_main
 from pelican.server import ComplexHTTPRequestHandler, RootedHTTPServer
 from pelican.settings import DEFAULT_CONFIG, get_settings_from_file
@@ -96,8 +97,6 @@ def preview(c):
 @task
 def livereload(c):
     """Automatically reload browser tab upon file modification."""
-    from livereload import Server
-
     def cached_build():
         cmd = "-s {settings_base} -e CACHE_CONTENT=true LOAD_CONTENT_CACHE=true"
         pelican_run(cmd.format(**CONFIG))