Contributions are welcome, and they are greatly appreciated! Every bit helps, and credit will always be given.
There are several types of contributions that can be made:
If you are reporting a bug, please include:
- Your operating system name and version.
- Any details about your local setup that might be helpful in troubleshooting.
- Detailed steps to reproduce the bug.
Look through the GitHub issues for bugs. Anything tagged with "bug" and "help wanted" is open to whoever wants to implement it.
Look through the GitHub issues for features. Anything tagged with "enhancement" and "help wanted" is open to whoever wants to implement it.
You can never have enough documentation! Please feel free to contribute to any part of the documentation, such as the official docs, docstrings, or even on the web in blog posts, articles, and such.
The docstring and commenting convention this project follows is the Google Python styleguide with a few minor exceptions:
- This project uses imperative-style docstrings (
Fetch rows from a Bigtable.
), not Google's recommended descriptive-style docstrings (Fetches rows from a Bigtable.
).
If you are proposing a feature:
- Explain in detail how it would work.
- Keep the scope as narrow as possible, to make it easier to implement.
- Remember that this is a volunteer-driven project, and that contributions are welcome :)
Ready to contribute? Here's how to set up tm_data_types
for local development.
-
Set up commit signing, see GitHub's documentation for details.
!!! hint All commits going into the main repository are required to be signed, so make sure to set up commit signing before starting to make changes.
-
Fork
tm_data_types
into a new repository. -
Set up a virtual environment and install the project with its dependencies:
- Using the helper script (recommended):
python scripts/contributor_setup.py
- Or manually:
python -m venv .env
# Linux source .venv/bin/activate # Windows .venv\Scripts\activate.bat
python -m pip install -U pip poetry poetry install pre-commit install
- Using the helper script (recommended):
-
Check to see if there are any open issues or pull requests that are related to the change you wish to make.
-
Create or update an issue to track the status of your change.
-
Use
git
to create a branch for local development and make your changes:git checkout -b name-of-your-bugfix-or-feature
-
Update the Unreleased section in the CHANGELOG using the proper format.
-
When you're done making changes, check that your changes conform to any code formatting requirements and pass any tests.
!!! note Always remember to activate the virtual environment before attempting to run tests or other code.
```console # Linux source .venv/bin/activate # Windows .venv\Scripts\activate.bat ```
-
To run full static code analysis, tests, and documentation validation (running this prior to opening a pull request is highly recommended, but it is slow):
tox -p
-
To run just the tests and static code analysis (much quicker):
tox -p -m basic
-
To run just the pre-commit checks:
pre-commit run --all
-
To run just the tests:
tox -e tests
!!! note Two html outputs are generated:
- Code coverage report: `.results_tests/htmlcov/index.html` - Test results: `.results_tests/results.html`
-
To just build the documentation:
tox -e docs
!!! hint To view the documentation locally you will need to first build and then serve the site using one of the following methods:
```console mkdocs serve --clean --no-livereload ``` ```console tox -e docs python -m http.server -d .results_docs ```
-
-
Commit and push your changes, then open a pull request from the fork back into the main repository.
- Commit messages must be structured as follows:
<type>[optional scope]: <description> [optional body] [optional footer(s)]
<type>
can be one offix
,feat
,build
,ci
,docs
,style
,refactor
, ortest
.- See the Conventional Commits website for more details on this format.
- Commit messages must be structured as follows:
To update the required python packages and commit hooks run the following commands:
!!! note Always remember to activate the virtual environment before attempting to run tests or other code.
```console
# Linux
source .venv/bin/activate
# Windows
.venv\Scripts\activate.bat
```
python scripts/update_development_dependencies.py
Before you submit a pull request, check that it meets these guidelines:
- The pull request should include additional tests if appropriate.
- If the pull request adds functionality, the docs should be updated.
- The pull request should work for all currently supported operating systems and versions of Python.
- The Unreleased section in the Changelog should be updated.
This project undergoes rigorous testing to ensure a high quality product.
- 100% of the source code will have unit tests (except for accepted exceptions)
- All static code analysis will pass
- All features will have documentation
- Changelog will be updated
- Pull requests will have all required approvals prior to merging
- Each supported VISA Implementation will be validated as working
- Each supported Connection Type will be validated as working
Please note that the tm_data_types
project is released with a
Code of Conduct. By contributing to this project you agree
to abide by its terms.