chore: improve CONTRIBUTING.md

Author: yozachar

CONTRIBUTING.md

@@ -1,14 +1,14 @@
-# How to contribute to `validators`
+# Contributing to `validators`
 
 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
 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.
+4. (Optional/Recommended) [`NodeJS`](https://nodejs.org/en) for type checking
+5. (Optional/Recommended) [`mise`](https://github.com/jdx/mise) to manage multiple versions of Python, NodeJS and other such tools.
 
-First [fork this repository](https://github.com/python-validators/validators/fork). Uncheck "fork only `master`", because for versioned docs you'll need `gh-pages` too. Clone it to your system. Install development dependencies.
+First [fork this repository](https://github.com/python-validators/validators/fork). (If you are or intend to be a collaborator, uncheck "fork only `master`", because for versioned docs you'll need `gh-pages` branch too.) Clone it to your system and install the development dependencies.
 
 ```sh
 # clone repository
@@ -63,39 +63,49 @@ $ python -m http.server -d docs/_build/web
 
 > 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).
+### Tagging
+
+1. Take a look at [`CHANGES.md`](CHANGES.md). They are generated with [GitHub's releaser](https://github.com/python-validators/validators/releases/new), and then modified to fit the shown style.
+2. Update the [changelog](CHANGES.md). 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 (i.e. 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
+    $ GIT_COMMITTER_DATE=$(git log -n1 --pretty=%aD) git tag -a -m "vMAJOR.MINOR.PATCH" MAJOR.MINOR.PATCH
     # pushing tag to remote
     $ git push --tag
     $ git push upstream --tag
     ```
 
-4. To preview versioned docs, run `mike serve` (`mike` is already a dev dependency).
-5. To update it, checkout to the tag you want to include in the versioned documentation `git checkout TAG_NAME`.
-6. Then run `mike deploy -p -u VERSION stable` OR run `mike deploy -p -u dev master`,
-7. Which will deploy docs in the CURRENT commit as the `latest` documentation, onto `gh-pages` branch.
-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.
+### Versioned documentation
+
+1. To preview versioned docs, run `mike serve` (`mike` is a dev dependency).
+2. Then (look at <https://yozachar.github.io/pyvalidators/stable/>)
+    - to publish stable docs run `mike deploy -p -u VERSION stable` after checking out to a stable tag name like `0.28.3` (note: document `VERSION = 0.29 if tag_name == 0.29.1`).
+    - to publish bleeding-edge docs run `mike deploy -p -u dev master` after checking out to the `master` branch.
+3. This will deploy docs to the `gh-pages` branch (see: <https://github.com/python-validators/validators/tree/gh-pages/>)
+
+### Packaging and releasing
+
+1. Run `./package/roll.sh` (or `./package/roll.ps1`) to generate both `sdist` and `bdist`.
+2. 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:
+3. 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
     ```
 
-Thanks for taking interest in this library!
+---
+
+Thank your for taking interest in this library!