validators/CONTRIBUTING.md at master · python-validators/validators

Hi, to start, you need the following installed on your system.

Git
Python v3.8 or later
PDM for easy dependency management
(Optional/Recommended) NodeJS for type checking
(Optional/Recommended) mise to manage multiple versions of Python, NodeJS and other such tools.

First fork this repository. (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.

# clone repository
$ git clone "https://github.com/YOUR-USERNAME/validators.git"
# change directory 
$ cd validators
# install development dependencies
$ pdm install

Activate the virtual environment and run tox to verify test cases.

# activate virtual environment
$ . ./.venv/bin/activate # replace `/bin/` with `/Scripts/` if you're on Windows.
# run tox for linting, type checking, formatting etc.
$ tox

Create a git branch and make changes to the source code. If needed, test your changes by running pytest. Execute tox to format, lint and type-check your code before committing. Commit, push and create a pull request. If you're in doubt, feel free to start a discussion here.

Documentation

Documentation is extracted from the source code. Please follow Google's Python Doc Style.

If you're adding/removing a module, you must update the nav key in mkdocs.yml. Then export documentation as follows:

$ . ./.venv/bin/activate
# generate documentation
$ python package/export TYPE # where TYPE is any of `doc`, `man` or `web`.

# doc - generates docs found here: https://nandgator.github.io/pyvalidators
# man - generates sphinx based manpages
# web - generates sphinx based web docs

You can preview the generated documentation:

$ . ./.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 and Python packaging.

Tagging

Take a look at CHANGES.md. They are generated with GitHub's releaser, and then modified to fit the shown style.
Update the changelog. Version number must be updated in both SECURITY.md and src/validators/__init__.py.

The final merge commit on the upstream (i.e. this repo) is tagged.

# 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" MAJOR.MINOR.PATCH
# pushing tag to remote
$ git push --tag
$ git push upstream --tag

Versioned documentation

To preview versioned docs, run mike serve (mike is a dev dependency).
Then (look at https://nandgator.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.
This will deploy docs to the gh-pages branch (see: https://github.com/python-validators/validators/tree/gh-pages/)

Packaging and releasing

Run ./package/roll.sh (or ./package/roll.ps1) to generate both sdist and bdist.

Install twine using pipx to upload package to PyPI.

# publishing
$ twine check dist/*
$ twine upload dist/*

Create a GitHub release with the contents from the changelog. Upload the wheel from dist/ along with the shasum file generated with:
```
# generate sha256sum
$ sha256sum dist/validators-VERSION-py3-none-any.whl > dist/validators-VERSION-py3-none-any.whl.sha256
```

Thank your for taking interest in this library!