2020-11-14 01:08:22 +03:00
|
|
|
|
|
|
|
## Guidelines
|
|
|
|
|
|
|
|
### Checking the Format, Coding Style, and Type Hints
|
|
|
|
|
2020-11-19 20:16:16 +03:00
|
|
|
Code is formatted with [black](https://github.com/psf/black).
|
|
|
|
Coding style is checked with [flake8](http://flake8.pycqa.org).
|
|
|
|
Type hints, [PEP484](https://www.python.org/dev/peps/pep-0484/), are checked with
|
|
|
|
[mypy](http://mypy-lang.org/).
|
2020-11-14 01:08:22 +03:00
|
|
|
|
2020-11-19 22:32:13 +03:00
|
|
|
You can check the format, coding style, and type hints at the same time just by executing
|
2020-11-19 20:16:16 +03:00
|
|
|
a script `scripts/linting.sh`. If your environment misses some dependencies such as
|
|
|
|
black, flake8, or mypy, you will be asked to install them.
|
2020-11-14 01:08:22 +03:00
|
|
|
|
|
|
|
```bash
|
|
|
|
# Without any fixes.
|
2020-11-19 20:16:16 +03:00
|
|
|
bash scripts/linting.sh
|
2020-11-14 01:08:22 +03:00
|
|
|
|
2020-11-19 22:32:13 +03:00
|
|
|
# With fixes on the format by `black`
|
2020-11-19 20:16:16 +03:00
|
|
|
bash scripts/linting.sh -u
|
2020-11-14 01:08:22 +03:00
|
|
|
```
|
|
|
|
|
|
|
|
### Documentation
|
|
|
|
|
2020-11-19 22:32:13 +03:00
|
|
|
The API documentation is mostly based on doc strings. Inline comments should be used
|
|
|
|
whenever code may be difficult to understand for others. Type hints should be throughout.
|
2020-11-19 20:16:16 +03:00
|
|
|
|
|
|
|
## Tests
|
|
|
|
|
|
|
|
The test suite uses a mixture of [unittest](https://docs.python.org/3.8/library/unittest.html)
|
|
|
|
and [pytest](https://pytest-cov.readthedocs.io/en/latest/), depending on what is most
|
|
|
|
convenient for the actual test and the preference of the author. Pytest should be used
|
|
|
|
as the test runner.
|
|
|
|
|
|
|
|
Test are grouped into those which require a linked Dropbox account ("linked") and those
|
|
|
|
who can run by themselves ("offline"). The former tend to be integration test while the
|
|
|
|
latter are mostly unit tests. The current focus currently lies on integration tests,
|
|
|
|
especially for the sync engine, as they are easier to maintain when the implementation
|
|
|
|
and internal APIs change. Exceptions are made for performance tests, for instance for
|
|
|
|
indexing and cleaning up sync events, and for particularly complex functions that are
|
|
|
|
prone to regressions.
|
|
|
|
|
|
|
|
The current test suite uses a Dropbox access token provided by the environment variable
|
2020-11-19 20:45:28 +03:00
|
|
|
`DROPBOX_TOKEN` to connect to a real account. The GitHub action which is running the
|
2020-11-19 20:16:16 +03:00
|
|
|
tests will set this environment variable for you with a temporary access token that
|
2020-11-19 20:45:28 +03:00
|
|
|
expires after 4 hours. Tests are run on `ubuntu-latest` and `macos-latest` in parallel
|
2020-11-19 20:16:16 +03:00
|
|
|
on different accounts and you should acquire a "lock" on the account before running
|
|
|
|
tests. Fixtures to create and clean up a test config and to acquire a lock are provided
|
2020-11-19 20:45:28 +03:00
|
|
|
in the `tests/linked/conftest.py`. If you run the tests locally, you will need to
|
|
|
|
provide an access token for your own Dropbox account.
|