Skip to content

Latest commit

 

History

History
101 lines (78 loc) · 4.09 KB

CONTRIBUTING.md

File metadata and controls

101 lines (78 loc) · 4.09 KB

How to contribute to validators

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

  1. Git
  2. Python v3.8 or later
  3. PDM for easy dependency management
  4. (Optional/Recommended) NodeJS for type checking
  5. (Optional/Recommended) mise to manage multiple versions of Python & NodeJS.

First fork this repository. Clone it to your system. Install 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://yozachar.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.

  1. Take a look at the CHANGES.md. They are generated with GitHub's releaser, and then modified.

  2. Update the changelog. Version number must be updated in both SECURITY.md and src/validators/__init__.py.

  3. 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" 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 (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 using pipx to upload package to PyPI.

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

  10. 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

Thanks for taking interest in this library!