From 2ff3b122f53e2231ad4c90666be01ca35ea516b2 Mon Sep 17 00:00:00 2001
From: yozachar <38415384+yozachar@users.noreply.github.com>
Date: Fri, 19 Apr 2024 17:41:40 +0530
Subject: [PATCH] chore: update contribution guidelines

- removes unused `.pre-commit-config.yaml`
- removes unused `compose.yaml`
---
 .pre-commit-config.yaml | 27 ------------
 CONTRIBUTING.md         | 92 +++++++++++++++++++++++++++++++++++------
 compose.yaml            |  8 ----
 3 files changed, 79 insertions(+), 48 deletions(-)
 delete mode 100644 .pre-commit-config.yaml
 delete mode 100644 compose.yaml

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
deleted file mode 100644
index e7b12674..00000000
--- a/.pre-commit-config.yaml
+++ /dev/null
@@ -1,27 +0,0 @@
-repos:
-  - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.4.0
-    hooks:
-      - id: check-added-large-files
-      - id: check-ast
-      - id: check-case-conflict
-      - id: check-toml
-      - id: check-yaml
-      - id: end-of-file-fixer
-      - id: debug-statements
-      - id: destroyed-symlinks
-      - id: no-commit-to-branch
-        args: ["--branch", "master"]
-      - id: trailing-whitespace
-  - repo: https://github.com/psf/black
-    rev: 23.7.0
-    hooks:
-      - id: black
-  - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.0.282
-    hooks:
-      - id: ruff
-  - repo: https://github.com/RobertCraigie/pyright-python
-    rev: v1.1.320
-    hooks:
-      - id: pyright
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 6307a603..373b64c0 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -2,22 +2,20 @@
 
 Hi, to start, you need the following installed on your system.
 
-1. [Git](https://git-scm.com/)
-2. [Python](https://www.python.org/) v3.8 or later and
-3. [PDM](https://pdm-project.org/en/stable/) for easy dependency management.
-4. (Optional/Recommended) NodeJS for type checking.
-5. (Optional/Recommended) [mise](https://github.com/jdx/mise) to manage multiple versions of Python, NodeJS etc.
-
-
-First [fork](https://github.com/python-validators/validators/fork) this repository. Then clone it to your system. Then install development dependencies.
+1. [Git](https://git-scm.com)
+2. [Python](https://www.python.org) v3.8 or later
+3. [PDM](https://pdm-project.org) for easy dependency management
+4. (Optional/Recommended) NodeJS for type checking
+5. (Optional/Recommended) [mise](https://github.com/jdx/mise) to manage multiple versions of Python & NodeJS.
 
+First [fork this repository](https://github.com/python-validators/validators/fork). Clone it to your system. Install development dependencies.
 
 ```sh
-# cloning repository
-$ git clone "https://github.com/YOUR_USERNAME/validators.git"
-# changing directory 
+# clone repository
+$ git clone "https://github.com/YOUR-USERNAME/validators.git"
+# change directory 
 $ cd validators
-# installing development dependencies
+# install development dependencies
 $ pdm install
 ```
 
@@ -30,6 +28,74 @@ $ . ./.venv/bin/activate # replace `/bin/` with `/Scripts/` if you're on Windows
 $ tox
 ```
 
-Create a git branch. You can now make changes to the source code. If needed, test your change by running `pytest`. Commit, push and create a pull request.
+Create a git branch. You can now make changes to the source code. If needed, test your change by running `tox`. Commit, push and create a pull request.
 
 If you're in doubt feel free to start a discussion [here](https://github.com/python-validators/validators/discussions). Thanks for taking interest in this library.
+
+## Documentation
+
+> Documentation is extracted from the source code. Please follow [Google's Python Doc Style](https://google.github.io/styleguide/pyguide.html).
+
+If you're adding/removing a module, you must update the `nav` key in `mkdocs.yml`.
+Then export documentation as follows:
+
+```sh
+$ . ./.venv/bin/activate
+# generate documentation
+$ python package/export TYPE # where TYPE is any of `doc`, `man` or `web`.
+
+# doc - generates docs found here: https://yozachar.github.io/pyvalidators
+# man - generates sphinx based manpages
+# web - generates sphinx based web docs
+```
+
+You can preview the generated documentation:
+
+```sh
+$ . ./.venv/bin/activate
+# To preview mkdocs
+$ mkdocs serve
+# To preview man pages
+$ man docs/_build/man/validators.1
+# To preview sphinx webpages
+$ python -m http.server -d docs/_build/web
+```
+
+## Versioning, Packaging & Releasing (for collaborators)
+
+> You must be familiar with [semantic versioning](https://semver.org) and [Python packaging](https://packaging.python.org).
+
+1. Take a look at the [`CHANGES.md`](CHANGES.md). They are generated with [GitHub's releaser](https://github.com/python-validators/validators/releases/new), and then modified.
+2. Update the changelog. Version number must be updated in both [`SECURITY.md`](SECURITY.md) and [`src/validators/__init__.py`](src/validators/__init__.py).
+3. The final merge commit on the upstream (ie. this repo) is tagged.
+
+    ```sh
+    # syncing with upstream
+    $ git pull upstream master
+    $ git push
+    # tagging that final merge commit before release
+    $ GIT_COMMITTER_DATE=$(git log -n1 --pretty=%aD) git tag -a -m "vMAJOR.MINOR.PATCH" vMAJOR.MINOR.PATCH
+    # pushing tag to remote
+    $ git push --tag
+    $ git push upstream --tag
+    ```
+
+4. To update versioned docs, you must track the `gh-pages` onto a local branch. `git checkout --track upstream/gh-pages`, once.
+5. Checkout to the tag you want to include in the versioned documentation `git checkout TAG_NAME`.
+6. Then using [`mike`](https://github.com/jimporter/mike) (which is already a dev dependency) run `mike deploy -p -u VERSION stable`.
+7. Or use `mike deploy -p -u dev master`, which will deploy docs in the CURRENT commit as the `latest` documentation.
+8. Run `./package/roll.sh` (or `./package/roll.ps1`) to generate both sdist and bdist.
+9. Install [`twine`](https://pypi.org/project/twine) using [`pipx`](https://pipx.pypa.io) to upload package to PyPI.
+
+    ```sh
+    # publishing
+    $ twine check dist/*
+    $ twine upload dist/*
+    ```
+
+10. Create a GitHub release with the contents from the [changelog](CHANGES.md). Upload the wheel from `dist/` along with the shasum file generated with:
+
+    ```sh
+    # generate sha256sum
+    $ sha256sum dist/validators-VERSION-py3-none-any.whl > dist/validators-VERSION-py3-none-any.whl.sha256
+    ```
diff --git a/compose.yaml b/compose.yaml
deleted file mode 100644
index c5f97269..00000000
--- a/compose.yaml
+++ /dev/null
@@ -1,8 +0,0 @@
-services:
-  web:
-    image: docker.io/nginx:alpine-slim
-    container_name: validators
-    ports:
-      - "8080:80"
-    volumes:
-      - ./site:/usr/share/nginx/html:ro