Skip to content

Commit 3fb2c99

Browse files
adamtheturtleadamtheturtle
committed
Merge remote-tracking branch 'origin/master' into fewer-preps
2 parents 2133d63 + 4611f12 commit 3fb2c99

18 files changed

+386
-360
lines changed

‎CONTRIBUTING.md‎

Lines changed: 0 additions & 177 deletions
This file was deleted.

‎CONTRIBUTING.rst‎

Lines changed: 178 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,178 @@
1+
Contributing to VWS Python Mock
2+
===============================
3+
4+
Contributions to this repository must pass tests and linting.
5+
6+
Travis CI is the canonical source truth.
7+
8+
Install Contribution Dependencies
9+
---------------------------------
10+
11+
Install Python dependencies in a virtual environment.
12+
13+
.. code:: sh
14+
15+
pip install --editable .[dev]
16+
17+
Spell checking requires ``enchant``.
18+
This can be installed on macOS, for example, with `Homebrew <http://brew.sh>`__:
19+
20+
.. code:: sh
21+
22+
brew install enchant
23+
24+
and on Ubuntu with ``apt``:
25+
26+
.. code:: sh
27+
28+
apt-get install -y enchant
29+
30+
Linting
31+
-------
32+
33+
Run lint tools:
34+
35+
.. code:: sh
36+
37+
make lint
38+
39+
To fix some lint errors, run the following:
40+
41+
.. code:: sh
42+
43+
make fix-lint
44+
45+
Running tests
46+
-------------
47+
48+
Create an environment variable file for secrets:
49+
50+
.. code:: sh
51+
52+
cp vuforia_secrets.env.example vuforia_secrets.env
53+
54+
Some tests require Vuforia credentials.
55+
To run these tests, add the Vuforia credentials to the file ``vuforia_secrets.env``.
56+
See “Connecting to Vuforia”.
57+
58+
Then run ``pytest``:
59+
60+
.. code:: sh
61+
62+
pytest
63+
64+
Connecting to Vuforia
65+
---------------------
66+
67+
To connect to Vuforia, Vuforia target databases must be created via the Vuforia Web UI.
68+
Then, secret keys must be set as environment variables.
69+
70+
The test infrastructure allows those keys to be set in the file ``vuforia_secrets.env``.
71+
See ``vuforia_secrets.env.example`` for the environment variables to set.
72+
73+
Do not use a target database that you are using for other purposes.
74+
This is because the test suite adds and deletes targets.
75+
76+
To create a target database, first create a license key in the `License Manager <https://developer.vuforia.com/targetmanager/licenseManager/licenseListing>`__.
77+
Then, add a database from the `Target Manager <https://developer.vuforia.com/targetmanager>`__.
78+
79+
To find the environment variables to set in the ``vuforia_secrets.env`` file, visit the Target Database in the Target Manager and view the “Database Access Keys”.
80+
81+
Two databases are necessary in order to run all the tests.
82+
One of those must be an inactive project.
83+
To create an inactive project, delete the license key associated with a database.
84+
85+
Targets sometimes get stuck at the “Processing” stage meaning that they cannot be deleted.
86+
When this happens, create a new target database to use for testing.
87+
88+
Skipping some tests
89+
-------------------
90+
91+
Set either ``SKIP_MOCK`` or ``SKIP_REAL`` to ``1`` to skip tests against the mock, or tests against the real implementation, for tests which run against both.
92+
93+
Travis CI
94+
---------
95+
96+
Tests are run on Travis CI.
97+
The configuration for this is in ``.travis.yml``.
98+
99+
Travis CI is set up with secrets for connecting to Vuforia.
100+
These variables include those from ``vuforia_secrets.env.example``.
101+
102+
To avoid hitting request quotas and to avoid conflicts when running multiple tests in prallel, we use multiple target databases.
103+
104+
Travis builds use a different credentials file depending on the build number.
105+
For example, build 2045.1 will use a different credentials file to build 2045.2.
106+
This should avoid conflicts, but in theory the same credentials file may be run across two Pull Request builds.
107+
This may cause errors.
108+
109+
How to set Travis CI secrets
110+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
111+
112+
Create environment variable files for secrets:
113+
114+
.. code:: sh
115+
116+
mkdir -p ci_secrets
117+
cp vuforia_secrets.env.example ci_secrets/vuforia_secrets_1.env
118+
cp vuforia_secrets.env.example ci_secrets/vuforia_secrets_2.env
119+
...
120+
121+
Add Vuforia credentials for different target databases to the new files in the ``ci_secrets/`` directory.
122+
Add as many credentials files as there are builds in the Travis matrix.
123+
All credentials files can share the same credentials for an inactive database.
124+
125+
Install the Travis CLI:
126+
127+
.. code:: sh
128+
129+
gem install travis --no-rdoc --no-ri
130+
131+
Add the encrypted secrets files to the repository and Travis CI:
132+
133+
.. code:: sh
134+
135+
make update-secrets
136+
137+
Note that the `Travis CI documentation <https://docs.travis-ci.com/user/encrypting-files/#Caveat>`__ warns that this might not work on Windows.
138+
139+
Travis CI Settings
140+
~~~~~~~~~~~~~~~~~~
141+
142+
All targets are deleted from the database between each test.
143+
Therefore there may be conflicts if the test suite is run concurrently as Travis CI is configured to connect to one Vuforia database.
144+
As such, Travis CI is configured not to run multiple instances of the test suite concurrently.
145+
146+
Learnings about VWS
147+
-------------------
148+
149+
Vuforia Web Services, at the time of writing, does not behave exactly as documented.
150+
151+
The following list includes details of differences between VWS and expected or documented behaviour.
152+
153+
When attempting to delete a target immediately after creating it, a ``FORBIDDEN`` response is returned.
154+
This is because the target goes into a processing state.
155+
156+
``image`` is required for ``POST /targets``, but it is documented as not mandatory.
157+
158+
The ``tracking_rating`` returned by ``GET /targets/<target_id>`` can be -1.
159+
160+
The database summary from ``GET /summary`` has multiple undocumented return fields.
161+
162+
The database summary from ``GET /summary`` has is not immediately accurate.
163+
164+
Some of the `Vuforia Web Services documentation <https://library.vuforia.com/articles/Training/Image-Target-Guide>`__ states that “The size of the input images must 2 MB or less”.
165+
However, other `Vuforia Web Services documentation <https://library.vuforia.com/articles/Solution/How-To-Perform-an-Image-Recognition-Query>`__ is more accurate: “Maximum image size: 2.1 MPixel.
166+
512 KiB for JPEG, 2MiB for PNG”.
167+
168+
The documentation page `How To Perform an Image Recognition Query <https://library.vuforia.com/articles/Solution/How-To-Perform-an-Image-Recognition-Query>`__ states that the ``Content-Type`` header must be set to ``multipart/form-data``.
169+
However, it must be set to ``multipart/form-data; boundary=<BOUNDARY>`` where ``<BOUNDARY>`` is the boundary used when encoding the form data.
170+
171+
The documentation page `How To Perform an Image Recognition Query <https://library.vuforia.com/articles/Solution/How-To-Perform-an-Image-Recognition-Query>`__ states that ``Content-Type`` with be the only response header.
172+
This is not the case.
173+
174+
Performing a release
175+
--------------------
176+
177+
There is currently no release process.
178+
See `this issue <https://github.com/adamtheturtle/vws-python/issues/55>`__ for details.

‎Makefile‎

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -7,14 +7,11 @@ lint:
77
flake8 .
88
isort --recursive --check-only
99
mypy src/ tests/ ci/
10-
pip-extra-reqs src/
11-
pip-missing-reqs src/
1210
pydocstyle
1311
pylint *.py src tests ci
1412
pyroma .
1513
vulture . --min-confidence 100
1614
yapf --diff --recursive src/ tests/ ci/
17-
markdownlint --config .markdownlint.json README.md CONTRIBUTING.md
1815

1916
.PHONY: fix-lint
2017
fix-lint:

0 commit comments

Comments
 (0)