Envase Exceptions Utility Library
This library provides base exception classes to be used in Envase applications and services. The library has been designed to satisfy the requirements of all sorts of applications running in the cloud or in the desktop. The following sections describe how to work on this project to contribute.
Development Environment Setup
This library is used by multiple projects using Python 3.7 and Python 3.8; therefore, changes should be compatible with those two versions of Python.
The recommended approach is to create a virtual environment for this library. This avoids conflicts with other projects or the global installation of Python. Make sure the environment is based on Python 3.8 (recommended) or Python 3.7. Navigate to the root directory of this repo and run the following command:
~/envase-exceptions$ python.exe -m venv ENV
This will create a virtual environment inside a ENV directory at the root of the repo. Creating the environment should activate it, but if it isn’t active, you can activated with the appropriate script provided in ENV/Scripts.
Activate.bat: This script activates the environment in
cmd.exe.Activate.ps1: This script activates the environment in
powershell.exe.Activate.sh: This script activates the environment in the different linux shells.
You can deactivate the environment when done by invoking the deactivate command:
~/envase-exceptions$ deactivate
With the environment activated, you need to install the project requirements and dependencies. For a development environment, you should execute the following command:
~/envase-exceptions$ pip install -r requirements-dev.txt
This command installs all the requirements and dependencies needed to work on the project.
Development Environment Automation
This projects uses Bolt to automate common tasks necessary during development. The following explains the registered tasks to help during the development process.
bolt
This command executes the default task and has the same behavior than the bolt validate command. The tasks first install any new or missing dependencies and requirements, then it insures all the .pyc files are cleared, and finally executes all the tests. This task should be run after getting the latest code from master, to to insure the development environment is setup correctly.
bolt ut
This command executes the unit tests and shows any potential failures.
bolt ct
This command executes all the unit tests and waits for file changes. When files are changed, the unit tests run again. This task should be used every time that development is being done in the library to insure that changes do not break the functionality and that new code works properly.
Contributing
This library is fully implemented using TDD (Test Driven Development) and maintains high level of coverage. All new code or changes must have appropriate unit test coverage for changes to be accepted. Also, new code should be appropriately documented and integrated with the documentation of this library.
Adding Changes and New Code
All new changes should be made in a separate branch from master. The first step should be to create a new branch:
~/envase-exceptions$ git branch my-new-branch
It is important to insure that the unit tests are running continuously while changes are made. You can accomplish that by executing the following command:
~/envase-exceptions$ bolt ct
This task runs the unit tests in the background and waits for file changes. As you add new unit tests and implement the code, the unit tests will be executed providing you with the right feedback.
All changes should also be documented. We document the code using Python’s docstrings. The docstrings use reStructured text for syntax, and any new modules should be added to the documentation. We use [Sphinx] (https://www.sphinx-doc.org/en/master/index.html) to generate the documentation. Make sure you review their documentation and that you follow the already existing guidelines in the project.
Adding New Documentation Modules
The documentation indices includes all the root level packages and modules. Sub-modules will be added to the same file as the parent package. Review the existing documentation to see how it works.
Root level packages and modules require a new .rst file to be created in docs/source/ref. Always name the .rst file based on the module/package name. For example, a logging.py root module should have a counterpart docs/source/reference.rst file. Once the file is added, it should be referenced in docs/source/reference.rst.
After any documentation changes, make sure you navigate to the docs folder and that you build the documentation to catch any potential problems. The documentation must build without errors for changes to be integrated.
~/envase-exceptions$ cd docs
~/envase-exceptions/docs$ make html
The documentation will be generated and stored at docs/build/html. You can open the index.html file in that directory to look at the documentation and insure the changes you made are rendered correctly.
Submitting Your Changes
You can submit your changes for review once you are done. We encourage small change sets, so the code is easier to review. It’s always better to submit many small changes than a huge change set. The process is as follows.
First publish you branch to the origin remote (bitbucket). Once your new branch is published, you can create a PR (Pull Request) from your branch into the master branch. You should always assign at least two reviewers for your PRs.
We encourage to divide PRs into several members of the team. Try to mix the reviewers into people with more knowledge around this library and people with less experience, so they take the review process as an opportunity to learn.
New PRs will trigger builds in the CI/CD system (Jenkins). There will be two builds for every branch and PR. The first build is a standalone build of your branch; the second one is a merge of your branch with master. Any failures must be addressed before the PR is integrated.
Releasing Your Changes
The CI/CD process will automatically release a new version of the library with new changes when the version for the library is updated. Versioning is handled in the en_exceptions/about.py module. This is an example of that file:
"""
Information about the envase-exceptions (``en_exceptions``) library.
"""
project = 'en-exceptions'
package = 'en_exceptions'
description = 'Envase Exceptions Utility Library'
copyright = '2021 Envase Technologies'
author = 'Envase Technologies'
author_email = 'development@envasetechnologies.com'
release = '1.0'
build_number = 0
version = f'{release}.{build_number}'
The important properties are release and build_number. Most changes will have to increment the build number to release a new version of the library. This will happen when the PR is integrated into master. This project uses semantic versioning, so make sure that you follow guidelines when changing versions.
The library is versioned using a major.minor.build schema. Depending on your changes, you should change the library version accordingly:
build: The build number should be changed for every release of the library that includes small changes and bug fixes that are fully compatible with the previous version of the library.
minor: The minor version should be changed for changes that are compatible with previous versions but might change behavior in compatible ways. It is unusual that minor versions need to be released, but keep an eye on them. When changing the minor version, make sure you also reset the build to 0.
major: The major version should be changed when incompatible changes are made. This allows projects using the library to pin to earlier versions until work can be schedule to migrate to the new version. When changing the major version, the minor and build should be reset to 0.
Questions?
If you have any questions about this library or how to contribute, you can contact our team in the Profit Tools: Development - Public channel in Microsoft Teams.