Contributing

Feel free to open pull requests with additional features or improvements!

Testing

Integration tests will automatically start a Vault server in the background. Just make sure the latest vault binary is available in your PATH.

  1. Install Vault or execute VAULT_BRANCH=release tests/scripts/install-vault-release.sh
  2. Install Tox
  3. Run tests: make test

Documentation

Examples

Example code or general guides for methods in this module can be added under docs/usage. Any newly added or updated method in this module will ideally have a corresponding addition to these examples. New usage sections should also be added to the table of contents tracked in docs/usage.rst.

Backwards Compatibility Breaking Changes

Due to the close connection between this module and HashiCorp Vault versions, breaking changes are sometimes required. This can also occur as part of code refactoring to enable improvements in the module generally. In these cases:

  • A deprecation notice should be displayed to callers of the module until the minor revision +2. E.g., a notice added in version 0.6.2 could see the marked method / functionality removed in version 0.8.0.
  • Breaking changes should be called out in the CHANGELOG.md for the affected version.

Package Publishing Checklist

The follow list uses version number 0.6.2, this string should be updated to match the intended release version. It is based on this document: https://gist.github.com/audreyr/5990987

  • [ ] Ensure your working directory is clear by running: .. code-block:: guess

    make distclean

  • [ ] Checkout a working branch based on the develop branch: .. code-block:: guess

    git checkout develop git pull git checkout -b master_v0-6-2

  • [ ] Update CHANGELOG.md with a list of the included changes. Those changes can be reviewed, and their associated GitHub PR number confirmed, via GitHub’s pull request diff using the previous version’s tag. E.g.: https://github.com/hvac/hvac/compare/v0.6.1…master

  • [ ] Commit the changelog changes: .. code-block:: guess

    git add CHANGELOG.md git commit -S -m “Updates for upcoming release 0.6.2”

  • [ ] Update version number using bumpversion. This example is for the “patch” version but can also be “minor” or “major” as needed. .. code-block:: guess

    bumpversion patch version

  • [ ] Commit the version changes: .. code-block:: guess

    git add version setup.cfg git commit -S -m “Bump patch version to $(cat version)”

  • [ ] Install the package again for local development, but with the new version number: .. code-block:: guess

    python setup.py develop

  • [ ] Run the tests and verify that they all pass: .. code-block:: guess

    make test

  • [ ] Invoke setup.py / setuptools via the “package” Makefile job to create the release version’s sdist and wheel artifacts:

    make package
    
  • [ ] Publish the sdist and wheel artifacts to TestPyPI using twine:

    twine upload --repository-url https://test.pypi.org/legacy/ dist/*.tar.gz dist/*.whl
    
  • [ ] Check the TestPyPI project page to make sure that the README, and release notes display properly: https://test.pypi.org/project/hvac/

  • [ ] Test that the version is correctly listed and it pip installs (mktmpenv is available via the virtualenvwrapper module) using the TestPyPI repository (Note: installation will currently fail due to missing recent releases of requests on TestPyPI): .. code-block:: guess

    mktmpenv pip install –no-cache-dir –index-url https://test.pypi.org/simple hvac== <verify releaes version shows up with the correct formatting in the resulting list> pip install –no-cache-dir –index-url https://test.pypi.org/simple hvac==0.6.2 <verify hvac functionality> deactivate

  • [ ] Create a draft GitHub release using the contents of the new release version’s CHANGELOG.md content: https://github.com/hvac/hvac/releases/new

  • [ ] Upload the sdist and whl files to the draft GitHub release as attached “binaries”.

  • [ ] Push up the working branch (git push) and open a PR to merge the working branch into master: https://github.com/hvac/hvac/compare/master…master_v0-6-2

  • [ ] After merging the working branch into master, tag master with the release version and push that up as well:

    git checkout master
    git pull
    git tag "v$(cat version)"
    git push "v$(cat version)"
    
  • [ ] Publish the sdist and wheel artifacts to PyPI using twine:

    twine upload dist/*.tar.gz dist/*.whl
    
  • [ ] Check the PyPI project page to make sure that the README, and release notes display properly: https://pypi.org/project/hvac/

  • [ ] Test that the version is correctly listed and it pip installs (mktmpenv is available via the virtualenvwrapper module) using the TestPyPI repository:

    mktmpenv
    pip install --no-cache-dir hvac==
    <verify releaes version shows up with the correct formatting in the resulting list>
    pip install --no-cache-dir hvac==0.6.2
    <verify hvac functionality>
    deactivate
    
  • [ ] Publish the draft release on GitHub: https://github.com/hvac/hvac/releases