Skip to content

Commit 0325ee0

Browse files
adamtheturtleadamtheturtle
authored
Merge pull request #531 from adamtheturtle/rst
Switch from Markdown to Rst
2 parents d3129b0 + a3a3915 commit 0325ee0

File tree

5 files changed

+300
-331
lines changed

5 files changed

+300
-331
lines changed

‎CONTRIBUTING.md‎

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

‎CONTRIBUTING.rst‎

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

‎Makefile‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,6 @@ lint:
1212
pyroma .
1313
vulture . --min-confidence 100
1414
yapf --diff --recursive src/ tests/ ci/
15-
markdownlint --config .markdownlint.json README.md CONTRIBUTING.md
1615

1716
.PHONY: fix-lint
1817
fix-lint:

0 commit comments

Comments
 (0)